Ruby » Ruby master

scanf for Ruby

$Release Version: 1.1.2 $

$Revision$

$Id$

$Author$

A product of the Austin Ruby Codefest (Austin, Texas, August 2002)

=scanf for ruby

==description

scanf for ruby is an implementation of the c function scanf(3),

modified as necessary for ruby compatibility.

the methods provided are string#scanf, io#scanf, and

kernel#scanf. kernel#scanf is a wrapper around stdin.scanf. io#scanf

can be used on any io stream, including file handles and sockets.

scanf for ruby scans an input string or stream according to a

<b>format</b>, as described below ("conversions"), and returns an

array of matches between the format and the input. the format is

formats used in kernel#printf and kernel#sprintf.

the format may contain <b>conversion specifiers</b>, which tell scanf

etc.) the matches and conversions take place from left to right, and

the format string may also contain characters other than those in the

conversion specifiers. white space (blanks, tabs, or newlines) in the

the input. everything else matches only itself.

scanning stops, and scanf returns, when any input character fails to

matched. all matches found up to the stopping point are returned in

==basic usage

# string#scanf and io#scanf take a single argument (a format string)

array = astring.scanf("%d%s")

array = anio.scanf("%d%s")

# kernel#scanf reads from stdin

==License and copyright

Copyright:: (c) 2002-2003 David Alan Black

License:: Distributed on the same licensing terms as Ruby itself

==Warranty disclaimer

This software is provided "as is" and without any express or implied

warranties, including, without limitation, the implied warranties of

merchantibility and fitness for a particular purpose.

==Credits and acknowledgements

scanf for Ruby was developed as the major activity of the Austin

Ruby Codefest (Austin, Texas, August 2002).

Principal author:: David Alan Black (mailto:dblack@superlink.net)

Co-author:: Hal Fulton (mailto:hal9000@hypermetrics.com)

Project contributors:: Nolan Darilek, Jason Johnston

Thanks to Hal Fulton for hosting the Codefest.

Thanks to Matz for suggestions about the class design.

Thanks to Gavin Sinclair for some feedback on the documentation.

The text for parts of this document, especially the Description and

Conversions sections, above, were adapted from the Linux Programmer's

Manual manpage for scanf(3), dated 1995-11-01.

==Bugs and bug reports

scanf for Ruby is based on something of an amalgam of C scanf

implementations and documentation, rather than on a single canonical

description. Suggestions for features and behaviors which appear in

other scanfs, and would be meaningful in Ruby, are welcome, as are

reports of suspicious behaviors and/or bugs. (Please see "Credits and

acknowledgements", above, for email addresses.)

=end

#:stopdoc:

module Scanf

=begin

#:startdoc:

# When required, +scanf.rb+ adds the +scanf+ method to the +IO+

# class, for reading formatted strings from streams.

#:stopdoc:

# The trick here is doing a match where you grab one *line*

# of input at a time. The linebreak may or may not occur

# at the boundary where the string matches a format specifier.

# And if it does, some rule about whitespace may or may not

# be in effect...

#

# That's why this is much more elaborate than the string

# version.

#

# For each line:

# Match succeeds (non-emptily)

# and the last attempted spec/string sub-match succeeded:

#

# could the last spec keep matching?

# yes: save interim results and continue (next line)

#

# The last attempted spec/string did not match:

#

# are we on the next-to-last spec in the string?

# yes:

# is fmt_string.string_left all spaces?

# yes: does current spec care about input space?

# yes: fatal failure

# no: save interim results and continue

# no: continue [this state could be analyzed further]

#

#:startdoc:

# Scans the current string until the match is exhausted,

# yielding each match as it is encountered in the string.

# A block is not necessary though, as the results will simply

# be aggregated into the final array.

#

# "123 456".block_scanf("%d")

# # => [123, 456]

#

# If a block is given, the value from that is returned from

# the yield is added to an output array.

#

# "123 456".block_scanf("%d) do |digit,| # Requires a ',' to unpack the Array

# digit + 100

# end

# # => [223, 556]

#

def scanf(str,&b) #:yield: +current_match+

# String has two convenience methods for scanning the contents

# of a string object into an +Array+. The first is the standard

# +scanf+ function; the second is the +block_scanf+, which

# yields a match to the given block, accumulating the output.

#

# Note that the String#scanf method will perform in the exact

# same way as String#block_scanf if passed a block.

#

# Scans the current string. If a block is given, it

# functions exactly like +block_scanf+.

#

# arr = "123 456".scanf("%d%d")

# # => [123, 456]

#

# require 'pp'

#

# "this 123 read that 456 other".scanf("%s%d%s") {|m| pp m}

#

# # ["this", 123, "read"]

# # ["that", 456, "other"]

# # => [["this", 123, "read"], ["that", 456, "other"]]

#

def scanf(fstr,&b) #:yield: +current_match+ if block_given?

# Scans the current string until the match is exhausted,

# yielding each match as it is encountered in the string.

# A block is not necessary though, as the results will simply

# be aggregated into the final array.

#

# "123 456".block_scanf("%d")

# # => [123, 456]

#

# If a block is given, the value from that is returned from

# the yield is added to an output array.

#

# "123 456".block_scanf("%d) do |digit,| # Requires a ',' to unpack the Array

# digit + 100

# end

# # => [223, 556]

#

def block_scanf(fstr,&b) #:yield: +current_match+

# The Kernel#scanf method is private by default, but because +Kernel+

# is mixed in the +Object+ inheritance heirarchy, it is thus

# available everywhere.

#

# It reads from +STDIN+.

#

module Kernel

# Queries +STDIN+ for input.

def scanf(fs,&b) #:doc: