Module: RIO::IF::GrandeStream

Included in:
Rio
Defined in:
lib/rio/if/grande_stream.rb

Instance Method Summary collapse

Instance Method Details

#+@ ⇒ Object

Unary Plus. Alternate form of #a rio('f1') > rio('f2') # copy f1 to f2 rio('f1') > rio('f2').a # append f1 to f2 rio('f1') > +rio('f2') # same thing rio('f1') >> rio('f2') # same thing



287
288
289
290
 
# File 'lib/rio/if/grande_stream.rb', line 287

def +@()
  RIO::no_warn { +target }
  self
end

#a ⇒ Object

Sets the implicit output mode to 'a'.

This is the mode Rio will use for output when no mode is specified

Rios normally don't need to be opened or have their open mode specified. A Rio determines the mode based on the file system object and on the action specified. For instance when a Rio encounters a read on a file it opens the file for reading using File#open and calls IO#read; when it encounters a read on a directory it knows to use Dir#open and call Dir#read. When it encounters a #puts, it knows to perform a File#open, and call IO#puts on the returned handle. By default when a method requires a file be opened for writing the file is opened with a mode of 'w'. #a changes this implicit output mode to 'a'.

Note that this is not the same as setting the output mode explicitly, as in rio('afile').mode('a'). When the mode is set explicitly using #mode, the mode specified will be used regardless of the operation being performed. The #a method only affects how Rio opens a file when it sees an operator that requires writing, and must determine for itself how to open it.

rio('afile').puts!('Hello World') # call IO#puts on a file handle opened in 'w' mode rio('afile').a.puts!('Hello World') # call IO#puts on a file handle opened in 'a' mode

See also #a!, #w! for setting the implicit output mode 'a+' and 'w+' respectively

The methods #a, #a!, #w, #w!, #r, #r! set the implicit open mode to 'a','a+','w','w+','r' and 'r+' respectively.

See also #+@



278
 
# File 'lib/rio/if/grande_stream.rb', line 278

def a() target.a(); self end

#a! ⇒ Object

Sets the implicit output mode to 'a+'.

The implicit output mode is the mode Rio will use for output when no mode is specified.

Returns the Rio

See the discussion for #a.



301
 
# File 'lib/rio/if/grande_stream.rb', line 301

def a!() target.a!(); self end

#bytes(n = 1, *args, &block) ⇒ Object

Sets the rio to read bytes and returns the rio

n specifies the number of bytes to be returned on each iteration of #each or by #getrec. If args are provided, they are treated as record selectors as if ario.bytes(n).records(*args) had been called. See also #records, #lines, #each, #[]

If called with a block behaves as if ario.bytes(n,*args).each(&block) had been called

rio('f.dat').bytes(1024) { |rec| ... } # iterate through f.txt 1024 bytes at a time rio('f.dat').bytes(1024).each { |rec| ... } # same as above

rio('f.dat').bytes(1024,0..4) { |rec| ... } # iterate through the first five 1024 byte blocks

rio('f.dat').bytes(64).to_a # return the contents of f.dat as an array of 64 byte chunks

rio('f.dat').bytes(512).records(0,7..9) > rio('dfile.dat') # copy 512-byte blocks 0,7,8 and 9 to dfile.dat

rio('f.dat').bytes(2048).records # return an array containing the first 10 2K blocks of f.dat rio('f.dat').bytes(2048)[0...10] # same thing

rio('f.dat').bytes { |bytestr| ... } # iterate over f.dat 1 byte at a time. rio('f.dat').bytes # returns an array of the first 100 bytes of f.dat



102
 
# File 'lib/rio/if/grande_stream.rb', line 102

def bytes(n=1,*args,&block) target.bytes(n,*args,&block); self end

#chomp(arg = true, &block) ⇒ Object

Sets the Rio to chomp lines and returns the Rio

When called with a block, behaves as if chomp.each(&block) had been called

chomp causes lines returned by each, to_a, readlines, readline, gets, each_line etc. to be chomped before iterated over or assigned

rio('f.txt').chomp.each { |line| ... } # Block is called with lines already chomped

rio('f.txt').chomp { |line| ... } # same as above

rio('f.txt').chomp.to_a # returns the lines of f.txt chomped

rio('f.txt').chomp.lines(1..2).to_a # returns an array containg lines 1 and 2 of the file after being chomped

This would have similar results to rio('f.txt').lines(1..2).to_a.map{ |line| line.chomp}

rio('f.txt').lines(1..2).chomp.to_a # same as above

rio('f.txt').chomp.readlines # returns the lines of f.txt chomped

rio('f.txt').chomp.gets # returns the first line of 'f.txt' chomped

rio('f.txt').chomp > an_array # copies the chomped lines of f.txt into an_array

fill an array with all the 'require' lines in all the .rb files (recursively) in adir

chomping each line

an_array = [] rio('adir').chomp.all.files(".rb") { |file| an_array += file.lines[/^\srequire/] }

or simply

an_array = rio('adir').chomp.all.files(".rb").lines[/^\srequire/]



593
 
# File 'lib/rio/if/grande_stream.rb', line 593

def chomp(arg=true,&block) target.chomp(arg,&block); self end

#chomp? ⇒ Boolean

Queries the Rio's chomp-mode. See #chomp.

Returns:

  • (Boolean) 


553
 
# File 'lib/rio/if/grande_stream.rb', line 553

def chomp?() target.chomp?() end

#closeoncopy(arg = true, &block) ⇒ Object

Set a Rio's closeoncopy mode

ario.closeoncopy(&block) => ario

#closeoncopy causes the Rio being written to to be closed when using a grande copy operator. While #closeoneof causes all Rio's to be closed when reading to the end of file, it does not affect Rios being written to. #closeoncopy only affects the Rio being written to and only when a grande copy operator is used. closeoncopy is on by default, with one exception.

dest = rio('destfile') dest < rio('srcfile') dest.closed? #=> true

dest = rio('destfile').nocloseoncopy dest < rio('srcfile') dest.closed? #=> false dest.close # must be explicitly closed

dest = rio('destfile') dest.print(rio('srcfile').contents) dest.closed? #=> false (#print is not a copy operator) dest.close

The Exception

When a block is passed directly to the rio constructor closeoncopy is turned off.

rio('afile') { |file| file.closeoncopy? #=> false file < a_string file.closed? #=> false }

The file is now closed. See #rio for more informatioin

Why?

Some of my favorite Rio idioms are its copy one-liners

rio('afile') < a_string # put a string into a file rio('afile') < an_array # put an array into a file rio('afile') < rio('anotherfile').lines(0..9) # copy the first 10 lines of anotherfile into afile rio('afile.gz').gzip < rio('anotherfile').lines(0..9) # same thing into a gzipped file

In each of these cases, 'afile' would remain open after the copy and furthermore since the destination Rio was not saved in a variable, There is no way to close file. Without closeoncopy Something like this would be required:

ario = rio('afile') ario < something_else ario.close

Or this...

ario = rio('afile') < something_else ario.close

Or this...

(rio('afile') < something_else).close One line, but ugly, and prone to error.

What I want is this:

rio('afile') < something_else

Simple. I want to copy this to that, I point the arrow and it works.

In perl the rio's destructor would be called, because there are no remaining references to the Rio However, it my understanding and experience that in Ruby the finalizer will not necessarily be called at this point.



515
 
# File 'lib/rio/if/grande_stream.rb', line 515

def closeoncopy(arg=true,&block) target.closeoncopy(arg,&block); self end

#closeoncopy? ⇒ Boolean

Query a Rio's closeoncopy mode

ario.closeoncopy? => true or false

See #closeoncopy

Returns:

  • (Boolean) 


533
 
# File 'lib/rio/if/grande_stream.rb', line 533

def closeoncopy?() target.closeoncopy?() end

#closeoneof(arg = true, &block) ⇒ Object

Set the Rio's closeoneof mode.

ario.closeoneof(&block) => ario

closeoneof causes a Rio to be closed automatically whenever the end of file is reached. This affects# all methods that read from a rio (#readlines, #to_a, #each #gets etc.) Because closeoneof must be on for many of Rio's most useful idioms, it is on by default. closeoneof can be turned off using #nocloseoneof.

If a block is given behaves like ario.closeoneof.each(&block) had been called

Returns the Rio

ario = rio('afile') lines = ario.readlines ario.closed? #=> true

ario = rio('afile').nocloseoneof lines = ario.readlines ario.closed? #=> false ario.close # must be explicitly closed

closeoneof is ignored by directory Rios, however, setting it on a directory Rio causes each file Rio returned while iterating to inherit the directory's setting

rio('adir').files do |file| file.closeoneof? #=> true end

rio('adir').files.nocloseoneof do |file| file.closeoneof? #=> false end

rio('adir').files.nocloseoneof # array of .rb file Rios in adir with closeoneof off

drio = rio('adir').files frio1 = drio.read frio1.closeoneof? #=> true drio.nocloseoneof frio2 = drio.read frio2.closeoneof? #=> false



400
 
# File 'lib/rio/if/grande_stream.rb', line 400

def closeoneof(arg=true,&block) target.closeoneof(arg,&block); self end

#closeoneof? ⇒ Boolean

Query a Rio's closeoneof mode ario.closeoneof? => true or false

See #closeoneof and #nocloseoneof

ario = rio('afile') ario.closeoneof? #=> true lines = ario.to_a ario.closed? #=> true

ario = rio('afile').nocloseoneof ario.closeoneof? #=> false lines = ario.to_a ario.closed? #=> false ario.close # must be explicitly closed

Returns:

  • (Boolean) 


438
 
# File 'lib/rio/if/grande_stream.rb', line 438

def closeoneof?() target.closeoneof?() end

#contents ⇒ Object

Slurps the contents of the rio into a string.

astring = rio('afile.txt').contents # slurp the entire contents of afile.txt into astring



245
 
# File 'lib/rio/if/grande_stream.rb', line 245

def contents() target.contents() end

#getline ⇒ Object

Temporarily set the Rio to read lines, and call #get

See also #records, #lines, #each, #[]



238
 
# File 'lib/rio/if/grande_stream.rb', line 238

def getline() target.getline() end

#getrec ⇒ Object

Temporarily set the Rio to read records, and call #get

See also #records, #lines, #each, #[]



224
 
# File 'lib/rio/if/grande_stream.rb', line 224

def getrec() target.getrec() end

#getrow ⇒ Object

Temporarily set the Rio to read rows, and call #get

See also #rows, #lines, #each, #[]



231
 
# File 'lib/rio/if/grande_stream.rb', line 231

def getrow() target.getrow() end

#gzip(&block) ⇒ Object

Sets the Rio to gzip mode. ario.gzip #=> ario If applied to a Rio that is being read from Reads through a Zlib::GzipReader; If applied to a Rio that is being written to writes through a Zlib::GzipWriter.

Returns the Rio

If a block is given, acts like ario.gzip.each(&block)

rio('afile') > rio('afile.gz').gzip # gzip a file rio('afile.gz').gzip < rio('afile') # same thing

rio('afile.gz').gzip > rio('afile') # ungzip a file rio('afile') < rio('afile.gz').gzip # same thing

rio('afile.gz').gzip.chomp { |line| ...} # process each chomped line of a gzipped file rio('afile.gz').gzip # an array containing the first 10 lines of a gzipped file



634
 
# File 'lib/rio/if/grande_stream.rb', line 634

def gzip(&block) target.gzip(true,&block); self end

#gzip? ⇒ Boolean

Queries the Rio's gzip-mode ario.gzip? #=> true or false See #gzip

Returns:

  • (Boolean) 


641
 
# File 'lib/rio/if/grande_stream.rb', line 641

def gzip?() target.gzip?() end

#line(*args, &block) ⇒ Object

Calls #lines(*args) but when used with the subscript operator returns the first element of the returned array instead of the array.

If afile contains ["line 0\n","line 1\n"] rio('afile').line #=> "line 0\n" rio('afile').line #=> "line 1\n" rio('afile').lines #=> ["line 0\n"] rio('afile').lines #=> ["line 1\n"] rio('afile').lines[0] #=> "line 0\n" rio('afile').lines[0] #=> "line 1\n"



38
 
# File 'lib/rio/if/grande_stream.rb', line 38

def line(*args,&block) target.line(*args,&block); self end

#lines(*args, &block) ⇒ Object

Sets the rio to read lines and returns the Rio

If called with a block behaves as if lines(*args).each(&block) had been called

lines returns the Rio which called it. This might seem counter-intuitive at first. One might reasonably assume that rio('adir').lines(0..10) would return lines. It does not. It configures the rio to return lines and returns the Rio. This enables chaining for further configuration so constructs like rio('afile').lines(0..10).skiplines(/::/) are possible.

If args are provided they may be one or more of the following:

Regexp

any matching record will be processed

Range

specifies a range of records (zero-based) to be included

Integer

interpreted as a one element range of lines to be processed

Proc

a proc which will be called for each record, records are included unless nil or false is returned

Symbol

a symbol which will sent to each record, records are included unless nil or false is returned

Array

an array of other selectors. records are selected unless any of the matches fail.

rio('f.txt').lines(/^\s*#/) { |line| ... } # iterate over comment-only lines rio('f.txt').lines(/^\s*#/).each { |line| ... } # same as above

rio('f.txt').lines(1,7..9) > rio('anotherfile.txt') # copy lines 1,7,8 and 9 to anotherfile.txt

rio('f.txt').lines(1...3).to_a # return an array containing lines 1 and 2 of f.txt rio('f.txt').lines # same thing



77
 
# File 'lib/rio/if/grande_stream.rb', line 77

def lines(*args,&block) target.lines(*args,&block); self end

#noautoclose(arg = false, &block) ⇒ Object

Turns off both closeoneof and closeoncopy. Equivelent to: ario.nocloseoneof.nocloseoncopy Returns the Rio ario.noautoclose(&block) => ario If a block is given, acts as if ario.noautoclose.each(&block) had been called.

See #nocloseoneof and #nocloseoncopy



547
 
# File 'lib/rio/if/grande_stream.rb', line 547

def noautoclose(arg=false,&block) target.noautoclose(arg,&block); self end

#nocloseoncopy(arg = false, &block) ⇒ Object

Set a Rio's closeoncopy mode to false

ario.nocloseoncopy(&block) => ario

See #closeoncopy



524
 
# File 'lib/rio/if/grande_stream.rb', line 524

def nocloseoncopy(arg=false,&block) target.nocloseoncopy(arg,&block); self end

#nocloseoneof(arg = false, &block) ⇒ Object

Set the Rio's closeoneof mode to false ario.nocloseoneof(&block) => ario See #closeoneof

If a block is given behaves like ario.nocloseoneof.each(&block)

Returns the Rio

ario = rio('afile') lines = ario.to_a ario.closed? #=> true

ario = rio('afile').nocloseoneof lines = ario.to_a ario.closed? #=> false ario.close # must be explicitly closed



420
 
# File 'lib/rio/if/grande_stream.rb', line 420

def nocloseoneof(arg=false,&block) target.nocloseoneof(arg,&block); self end

#putrec(el) ⇒ Object

Writes a single record to a Rio



249
 
# File 'lib/rio/if/grande_stream.rb', line 249

def putrec(el) target.putrec(el) end

#r ⇒ Object

Sets the implicit input mode to 'r'.

The implicit input mode is the mode Rio will use for input when no mode is specified.

Returns the Rio

See the discussion for #a.

Since 'r' is the implicit input mode used by default, this method is probably uneeded.



315
 
# File 'lib/rio/if/grande_stream.rb', line 315

def r() target.r(); self end

#r! ⇒ Object

Sets the implicit input mode to 'r+'.

The implicit input mode is the mode Rio will use for input when no mode is specified.

Returns the Rio

See the discussion for #a.



326
 
# File 'lib/rio/if/grande_stream.rb', line 326

def r!() target.r!(); self end

#record(*args, &block) ⇒ Object

See #line.



42
 
# File 'lib/rio/if/grande_stream.rb', line 42

def record(*args,&block) target.record(*args,&block); self end

#records(*args, &block) ⇒ Object

Specifies which records will be iterated through by #each or returned by #getrec

If called with a block behaves as if records(*args).each(&block) had been called

Returns the Rio

If no args are provided, all records are selected. What constitutes a record is affected by #lines,#bytes, and extensions such as #csv and #yaml.

If args are provided they may be one or more of the following:

Regexp

any matching record will be iterated over by #each or returned by #getrec

Integer

specifies a record-number (zero-based) to be iterated over by #each or returned by #getrec

Range

specifies a range of records (zero-based) to included in the iteration

Proc

a proc which will be called for each record, records are included unless nil or false is returned

Symbol

a symbol which will sent to each record, records are included unless nil or false is returned

Array

an array of any of above. All must match for a line to be included

Any other argument type is compared with the record using its === method.

If the argument is a ::Proc it may be called with one, two or three paramaters.

  1. the record
  2. the recno (optional)
  3. the rio (optional)

Note in the following examples that since lines is the default ario.records(*args) is effectively the same as ario.lines(*args).

rio('afile').records(0) { |line| ... } # iterate over the first line of 'afile' rio('afile').records(0,5..7)) { |line| ... } # iterate over lines 0,5,6 and 7 rio('afile').records(/Zippy/) { |line| ... } # iterate over all lines containing 'Zippy'

rio('f.csv').puts!(["h0,h1","f0,f1"]) # Create f.csv

rio('f.csv').csv.records #==>[["h0", "h1"], ["f0", "f1"]] rio('f.csv').csv.lines #==>["h0,h1\n", "f0,f1\n"] rio('f.csv').csv.records #==>[["h0", "h1"]]



144
 
# File 'lib/rio/if/grande_stream.rb', line 144

def records(*args,&block) target.records(*args,&block); self end

#row(*args, &block) ⇒ Object

See #line.



46
 
# File 'lib/rio/if/grande_stream.rb', line 46

def row(*args,&block) target.row(*args,&block); self end

#rows(*args, &block) ⇒ Object

Sets the Rio to read rows and specifies rows which should be iterated through by #each or returned by #getrec. #rows is intended for use by extensions, where the concept of a row is reasonable. In the absensence of an extension behaves like #records.



210
 
# File 'lib/rio/if/grande_stream.rb', line 210

def rows(*args,&block) target.rows(*args,&block); self end

#skiplines(*args, &block) ⇒ Object

Sets the Rio to read lines and specifies lines which should not be iterated through by #each or returned by #getrec

If called with a block behaves as if skiplines(*args).each(&block) had been called

Returns the Rio

See also #lines, #records, #skip

If no args are provided, no lines are rejected.

If args are provided they may be one or more of the following:

Regexp

any matching line will not be processed

Integer

specifies a line-number (zero-based) to be skipped

Range

specifies a range of lines (zero-based) to be excluded

Proc

a proc which will be called for each line, lines are excluded unless nil or false is returned

Symbol

a symbol which will sent to each line, lines are excluded unless nil or false is returned

Array

an array of any of above. All must match for a line to be included

rio('afile').skiplines(0) { |line| ... } # iterate over all but the first line of 'afile' rio('afile').skiplines(0,5..7)) { |line| ... } # don't iterate over lines 0,5,6 and 7 rio('afile').skiplines(/Zippy/) { |line| ... } # skip all lines containing 'Zippy' rio('afile').chomp.skiplines(:empty?) { |line| ... } # skip empty lines



203
 
# File 'lib/rio/if/grande_stream.rb', line 203

def skiplines(*args,&block) target.skiplines(*args,&block); self end

#skiprecords(*args, &block) ⇒ Object

Specifies records which should not be iterated through by #each or returned by #getrec

If called with a block behaves as if skiprecords(*args).each(&block) had been called

Returns the Rio

See also #records, #skiplines, #lines, #skip

If no args are provided, no records are rejected. What constitutes a record is affected by #lines,#bytes, and extensions such as #csv and #yaml.

If args are provided they may be one or more of the following:

Regexp

any matching record will not be processed

Integer

specifies a record-number (zero-based) to be skipped

Range

specifies a range of records (zero-based) to be excluded

Proc

a proc which will be called for each record, records are excluded unless nil or false is returned

Symbol

a symbol which will sent to each record, records are excluded unless nil or false is returned

Array

an array of any of the above, all of which must match for the array to match.

Note in the following examples that since lines is the default record type ario.skiprecords(*args) is effectively the same as ario.skiplines(*args).

rio('afile').skiprecords(0) { |line| ... } # iterate over all but the first line of 'afile' rio('afile').skiprecords(0,5..7)) { |line| ... } # don't iterate over lines 0,5,6 and 7 rio('afile').skiprecords(/Zippy/) { |line| ... } # skip all lines containing 'Zippy' rio('afile').chomp.skiplines(:empty?) { |line| ... } # skip empty lines



176
 
# File 'lib/rio/if/grande_stream.rb', line 176

def skiprecords(*args,&block) target.skiprecords(*args,&block); self end

#skiprows(*args, &block) ⇒ Object

Sets the Rio to read rows and specifies lines which should not be iterated through by #each or returned by #getrec #skiprows is intended for use by extensions, where the concept of a row is reasonable. In the absence of an extension behaves like #skiprecords



217
 
# File 'lib/rio/if/grande_stream.rb', line 217

def skiprows(*args,&block) target.skiprows(*args,&block); self end

#splitlines(*args, &block) ⇒ Object

This causes String#split(arg) to be called on every line before it is returned. An array of the split lines is returned when iterating

rio('/etc/passwd').split(':').columns(0,2) { |ary| username,uid = ary }

rio('/etc/passwd').split(':').columns(0,2).to_a #=> [[user1,uid1],[user2,uid2]]

See also #split



663
 
# File 'lib/rio/if/grande_stream.rb', line 663

def splitlines(*args,&block) target.splitlines(*args,&block) end

#strip(arg = true, &block) ⇒ Object

Sets the Rio to strip lines and returns the Rio

When called with a block, behaves as if strip.each(&block) had been called

strip causes lines returned by each, to_a, readlines, readline, gets, each_line etc. to be stripped with String#strip before iterated over or assigned

ans = rio(?-).print("A Prompt> ").strip.gets # prompt the user

See also #chomp



612
 
# File 'lib/rio/if/grande_stream.rb', line 612

def strip(arg=true,&block) target.strip(arg,&block); self end

#strip? ⇒ Boolean

Queries the Rio's strip-mode. See #strip.

Returns:

  • (Boolean) 


599
 
# File 'lib/rio/if/grande_stream.rb', line 599

def strip?() target.strip?() end

#w ⇒ Object

Sets the implicit output mode to 'w'.

The implicit output mode is the mode Rio will use for output when no mode is specified.

Returns the Rio

See the discussion for #a.

Since 'w' is the implicit output mode used by default, this method is uneeded, but is provided for completeness..



340
 
# File 'lib/rio/if/grande_stream.rb', line 340

def w() target.w(); self end

#w! ⇒ Object

Sets the implicit output mode to 'w+'.

The implicit output mode is the mode Rio will use for output when no mode is specified.

Returns the Rio

rio(?-,'cat').w!.puts!("Hello Kitty").readline #=> "Hello Kitty"

See the discussion for #a.



353
 
# File 'lib/rio/if/grande_stream.rb', line 353

def w!() target.w!(); self end