lib/rio/if/grande.rb in rio-0.3.8 vs lib/rio/if/grande.rb in rio-0.3.9

- old
+ new

@@ -1,8 +1,8 @@ #-- # =============================================================================== -# Copyright (c) 2005, 2006 Christopher Kleckner +# Copyright (c) 2005,2006,2007 Christopher Kleckner # All rights reserved # # This file is part of the Rio library for ruby. # # Rio is free software; you can redistribute it and/or modify @@ -21,664 +21,694 @@ # =============================================================================== #++ # # To create the documentation for Rio run the command # ruby build_doc.rb -# from the distribution directory. Then point your browser at the 'doc/rdoc' directory. +# from the distribution directory. # # Suggested Reading # * RIO::Doc::SYNOPSIS # * RIO::Doc::INTRO # * RIO::Doc::HOWTO +# * RIO::Doc::EXAMPLES # * RIO::Rio # -# <b>Rio is pre-alpha software. -# The documented interface and behavior is subject to change without notice.</b> require 'rio/no_warn' module RIO - class Rio -# module IF -# module Grande - # Returns the contents of the rio as an array. - # Rio#to_a is implemented in terms of Rio#each so the the following are roughly equivelent - # - # ary = ario.to_a - # - # ary = [] - # ario.each do |rec| - # ary << ary - # end - # - # What constitutes an array element is determined by Rio#lines, Rio#bytes, or - # by an extension such as Rio#csv. Rio#lines is the default. - # - # rio('afile.txt').to_a # returns an array of the lines in afile.txt - # - # rio('afile.txt').lines(1...3).to_a # an array containing lines 1 and 2 of afile.txt - # - # rio('afile.dat').bytes(50).to_a # an array containing the contents of afile.dat broken - # # up into 50 byte chunks - # - # See also Rio#[] (subscript operator) - # -# def to_a() target.to_a() end + module IF + module Grande - # Grande subscript operator. - # - # For files this returns all or part of a file as an array. - # - # For directories this returns all or some of the entries in a directory - # - # === Files - # - # This combines the record selection offered by Rio#records with - # the conversion to an array provided by Rio#to_a. The following two are equivelant: - # * ario[*args] - # * ario.records(*args).to_a - # - # What constitutes an array element is determined by Rio#lines, Rio#bytes, - # or by an extension such as Rio#csv. Rio#lines is the default. - # - # Arguments may consist of zero or more integers, ranges, regular expressions, symbols, - # procs, and arrays - # An empty argument list selects all records - # - # Records are selected as follows. - # range:: specifies a range of records to be selected (zero based) - # regexp:: matching records will be selected. - # integer:: treated like a one element range - # symbol:: the symbol is sent to each record. Record is selected - # unless false is returned - # proc:: the proc is called with the record as an argument. - # Record is selected unless false is returned - # array:: the array may contain any of the other selector types. Record is selected - # unless any of the selectors returns false. (a logical and) - # - # A record matching *any* of the selectors will be included in the array. (acts like an _or_) - # - # Because this is implemented in terms of the Rio#each, - # When only record ranges are used to select records, - # iteration will stop when the recno exceeds the maximum of any range. That is to say - # - # This reads one record from a file and returns it - # rio('bigfile.mp3').bytes(1024)[0] - # While this reads *all* records from a file and returns the first one - # rio('bigfile.mp3').bytes(1024).to_a[0] - # - # === Directories - # - # This combines the entry selection offered by Rio#entries with - # the conversion to an array provided by Rio#to_a. The following two are equivelant: - # * ario[*args] - # * ario.entries(*args).to_a - # - # Arguments may consist of strings (treated as globs) or regular expressions. - # An empty argument list selects all entries - # See ::Dir#glob and ::File::fnmatch? for more in information on _globs_. Be warned that using the '**' glob - # recurses into directories independently of Rio#all and using both is unsupported. - # - # ario = rio('adir') - # ario[] # returns an array containg all entries in _adir_ - # ario[/^zippy/] # all entries starting with 'zippy' - # ario['zippy*'] # same thing - # - # As with Rio#each: - # * Files and directories are returned as Rios - # * The types of entries is also affected by Rio#files and Rio#dirs. - # rio('adir').files['*.txt'] # array of all _.txt_ files - # rio('adir').dirs(/^\./) # array of all dot directories - # * Recursion is enabled using Rio#all - # rio('adir').all.files['*.[ch]'] # array of c source files in _adir_ and its subdirecories - # rio('adir').all.dirs[/^\.svn/] # array of subversion directories in _adir_ and subdirectories - # * Rio#files and Rio#dirs act independetly of each other. Specifying both will cause both to be returned. - # The argument list to Rio#[] will be applied to the closest. - # rio('adir').files('*.rb').dirs['ruby*'] # array of _.rb_ files and - # # directories starting with 'ruby' - # rio('adir').dirs('ruby*').files['*.rb'] # same thing - # - # === Lines - # This section applies similarly to Rio#lines, Rio#bytes, Rio#records, and Rio#rows - # - # Using Rio#lines and related methods with a Rio referencing a directory - # imples Rio#files and will cause an array of the lines or bytes in the files to be returned. As above, - # the arguments to the subscript operator will be applied to the closest. - # rio('adir').lines[] # array of all lines in the files in 'adir' - # rio('adir').files.lines[] # same thing - # rio('adir').lines(0..9).files['*.txt'] # array of the first ten lines of all .txt files - # rio('adir').files('*.txt').lines[0..9] # same thing - # rio('adir').all.files('*.rb').lines[/^\s*require/] # array of 'require' lines in .rb files in - # # 'adir and its subdirectories - # - # Note the difference between the following similar usages - # it1 = rio('adir').files('*.rb') # returns a Rio, prepared for selecting ruby files - # it2 = rio('adir').files['*.rb'] # returns an array of the ruby files - # - # The second example above could have been written - # it2 = it1.to_a - # - # Examples: - # - # rio('afile.txt').lines[1..2] # array containing the 2nd and 3rd line - # - # rio('afile.txt')[1,3..5] # array containing lines 1,3,4 and 5 - # - # rio('afile.txt')[/Zippy/] # array of all lines containing 'Zippy' - # - # rio('afile.txt')[1,3..5,/Zippy/] # array with lines 1,3,4 and 5 and all lines containing 'Zippy' - # - # rio('afile.dat').bytes(50)[] # array containing the contents of afile.dat broken up into 50 byte chunks - # - # rio('afile.dat').bytes(50)[0,2] # array containing the first and third such chunk - # - # rio('afile.dat').bytes(50).records[0,2] # same thing - # - # rio('afile.dat').bytes(50).records(0,2).to_a # once again - # - # rio('afile.csv').csv[0..9] # array of the first 10 records of afile.csv parsed by the ::CSV module - # - # rio('afile.csv').csv.records[0..9] # same thing - # - # rio('afile.csv').csv(';').records[0..9] # same thing using semi-colon as the value separator - # - # rio('afile.csv').csv.records[0,/Zippy/] # record 0 and all records containing 'Zippy' - # # the regexp is matched against the line before parsing by ::CSV - # - # rio('adir')[] # array of entries in 'adir' - # - # rio('adir')['*.txt'] # array of all .txt entries - # - # rio('adir').all['*.txt'] # array of all .txt entries in 'adir and its subdirectories - # - # rio('adir').files['*.txt'] # array of all .txt files - # - # rio('adir').dirs['CSV'] # array of all CSV directories - # rio('adir').skipdirs['CSV'] # array of all non-CSV directories - # - def [](*selectors) target[*selectors] end + # Returns the contents of the rio as an array. (See ::Enumerable#to_a) + # + # IF::Grande#to_a is implemented in terms of #each so the the following are roughly equivelent + # + # ary = ario.to_a + # + # ary = [] + # ario.each do |rec| + # ary << ary + # end + # + # What constitutes an array element is determined by IF::GrandeStream#lines, + # IF::GrandeStream#bytes, IF::GrandeStream#records, IF::GrandeStream#rows or + # by an extension such as IF::CSV#csv. IF::GrandeStream#lines is the default. + # + # rio('afile.txt').to_a # returns an array of the lines in afile.txt + # + # rio('afile.txt').lines(1...3).to_a # an array containing lines 1 and 2 of afile.txt + # + # rio('afile.dat').bytes(50).to_a # an array containing the contents of afile.dat broken + # # up into 50 byte chunks + # + # See also IF::Grande#[] (subscript operator) + # + def to_a() target.to_a() end + # Grande subscript operator. + # + # For files this returns all or part of a file as an array. + # + # For directories this returns all or some of the entries in a directory + # + # === Files + # + # This combines the record selection offered by IF::GrandeStream#records with + # the conversion to an array provided by IF::Grande#to_a. The following two are equivelant: + # ario[*args] + # ario.records(*args).to_a + # + # What constitutes an array element is determined by IF::GrandeStream#lines, IF::GrandeStream#bytes, + # or by an extension such as IF::CSV#csv. IF::GrandeStream#lines is the default. + # + # Arguments may consist of zero or more integers, ranges, regular expressions, symbols, + # procs, and arrays + # An empty argument list selects all records + # + # Records are selected as follows. + # range:: specifies a range of records to be selected (zero based) + # regexp:: matching records will be selected. + # integer:: treated like a one element range + # symbol:: the symbol is sent to each record. Record is selected + # unless false is returned + # proc:: the proc is called with the record as an argument. + # Record is selected unless false is returned + # array:: the array may contain any of the other selector types. Record is selected + # unless any of the selectors returns false. (a logical and) + # + # A record matching *any* of the selectors will be included in the array. (acts like an _or_) + # + # Because this is implemented in terms of the IF::Grande#each, + # When only record ranges are used to select records, + # iteration will stop when the recno exceeds the maximum of any range. That is to say + # + # This reads one record from a file and returns it + # rio('bigfile.mp3').bytes(1024)[0] + # While this reads *all* records from a file and returns the first one + # rio('bigfile.mp3').bytes(1024).to_a[0] + # + # === Directories + # + # This combines the entry selection offered by IF::GrandeEntry#entries with + # the conversion to an array provided by IF::Grande#to_a. The following two are equivelant: + # ario[*args] + # ario.entries(*args).to_a + # + # Arguments may consist of strings (treated as globs) or regular expressions. + # An empty argument list selects all entries + # See ::Dir#glob and ::File::fnmatch? for more in information on _globs_. Be warned that using the '**' glob + # recurses into directories independently of IF::GrandeEntry#all and using both is unsupported. + # + # ario = rio('adir') + # ario[] # returns an array containg all entries in _adir_ + # ario[/^zippy/] # all entries starting with 'zippy' + # ario['zippy*'] # same thing + # + # As with IF::Grande#each: + # * Files and directories are returned as Rios + # * The types of entries is also affected by IF::GrandeEntry#files and IF::GrandeEntry#dirs. + # rio('adir').files['*.txt'] # array of all _.txt_ files + # rio('adir').dirs(/^\./) # array of all dot directories + # * Recursion is enabled using IF::GrandeEntry#all + # rio('adir').all.files['*.[ch]'] # array of c source files in _adir_ and its subdirecories + # rio('adir').all.dirs[/^\.svn/] # array of subversion directories in _adir_ and subdirectories + # * IF::GrandeEntry#files and IF::GrandeEntry#dirs act independetly of each other. + # Specifying both will cause both to be returned. + # The argument list to IF::Grande#[] will be applied to the closest. + # rio('adir').files('*.rb').dirs['ruby*'] # array of _.rb_ files and + # # directories starting with 'ruby' + # rio('adir').dirs('ruby*').files['*.rb'] # same thing + # + # === Lines + # This section applies similarly to IF::GrandeStream#lines, IF::GrandeStream#bytes, + # IF::GrandeStream#records, and IF::GrandeStream#rows + # + # Using IF::GrandeStream#lines and related methods with a Rio referencing a directory + # imples IF::GrandeEntry#files and will cause an array of the lines or bytes in the files to be returned. As above, + # the arguments to the subscript operator will be applied to the closest. + # rio('adir').lines[] # array of all lines in the files in 'adir' + # rio('adir').files.lines[] # same thing + # rio('adir').lines(0..9).files['*.txt'] # array of the first ten lines of all .txt files + # rio('adir').files('*.txt').lines[0..9] # same thing + # rio('adir').all.files('*.rb').lines[/^\s*require/] # array of 'require' lines in .rb files in + # # 'adir and its subdirectories + # + # Note the difference between the following similar usages + # it1 = rio('adir').files('*.rb') # returns a Rio, prepared for selecting ruby files + # it2 = rio('adir').files['*.rb'] # returns an array of the ruby files + # + # The second example above could have been written + # it2 = it1.to_a + # + # Examples: + # + # rio('afile.txt').lines[1..2] # array containing the 2nd and 3rd line + # + # rio('afile.txt')[1,3..5] # array containing lines 1,3,4 and 5 + # + # rio('afile.txt')[/Zippy/] # array of all lines containing 'Zippy' + # + # rio('afile.txt')[1,3..5,/Zippy/] # array with lines 1,3,4 and 5 and all lines containing 'Zippy' + # + # rio('afile.dat').bytes(50)[] # array containing the contents of afile.dat broken up into 50 byte chunks + # + # rio('afile.dat').bytes(50)[0,2] # array containing the first and third such chunk + # + # rio('afile.dat').bytes(50).records[0,2] # same thing + # + # rio('afile.dat').bytes(50).records(0,2).to_a # once again + # + # rio('afile.csv').csv[0..9] # array of the first 10 records of afile.csv parsed by the ::CSV module + # + # rio('afile.csv').csv.records[0..9] # same thing + # + # rio('afile.csv').csv(';').records[0..9] # same thing using semi-colon as the value separator + # + # rio('afile.csv').csv.records[0,/Zippy/] # record 0 and all records containing 'Zippy' + # # the regexp is matched against the line before parsing by ::CSV + # + # rio('adir')[] # array of entries in 'adir' + # + # rio('adir')['*.txt'] # array of all .txt entries + # + # rio('adir').all['*.txt'] # array of all .txt entries in 'adir and its subdirectories + # + # rio('adir').files['*.txt'] # array of all .txt files + # + # rio('adir').dirs['CSV'] # array of all CSV directories + # rio('adir').skipdirs['CSV'] # array of all non-CSV directories + # + def [](*selectors) target[*selectors] end - # Iterate through a rio. Executes the block for each item selected for the Rio. - # See Rio#lines, Rio#records, Rio#bytes, Rio#files, Rio#dirs, Rio#[] - # and Rio#to_a for more information - # on how records are selected and what kind of record is passed to the block. - # - # Rio#each is the fundemental method for all the Rio grande operators. - # Rio#to_a and the Rio copy operators Rio#< Rio#<< Rio#>> Rio#> are all implemented - # in terms of Rio#each. - # - # While Rio#each is fundamental to a Rio, it rarely needs - # actually be called because all the grande configuration methods will also take a block - # and call Rio#each if one is given. - # So the existance of a block after many methods is taken as an implied - # Rio#each - # - # For Rios that refer to files, the item passed to the block is a String containing - # the line or block as selected by Rio#lines, or Rio#bytes. +lines+ is the default. - # rio('afile').lines.each { |line| ...} - # - # The block passed to +each+ will also accept an optional second parameter which will contain - # the result of the matching function. What this variable contains depends on the argument - # to +lines+ that resulted in the match as follows: - # - # Regexp:: The MatchData that resulted from the match. - # Range:: The record number of the matching record. - # Fixnum:: The record number of the matching record. - # Proc:: The value returned by the proc. - # Symbol:: The value resulting from sending the symbol to the String. - # - # If no selection arguments were used, this variable will simply contain +true+. - # - # rio(??).puts(%w[0:zero 1:one]).rewind.lines(/(\d+):([a-z]+)/) do |line,match| - # puts("#{match[1]} is spelled '#{match[2]}'") - # end - # - # Produces: - # 0 is spelled 'zero' - # 1 is spelled 'one' - # - # - # For Rios that refer to directories, the item passed to the block is a Rio refering to - # the directory entry. - # - # rio('adir').files.each do |file| - # file.kind_of?(RIO::Rio) # true - # end - # - # In addition, the Rio passed to the block inherits certain attributes from the directory Rio. - # - # rio('adir').files.chomp.each do |file| # chomp is ignored for directories, - # file.each do |line| # chomp attribute is inherited by the file rio - # # .. line is chomped - # end - # end - # - # Rio#each returns the Rio which called it. - # - # Here are a few illustrative examples - # - # * Processing lines in a file - # - # rio('f.txt').each { |line| ... } # execute block for every line in the file - # rio('f.txt').lines.each { |line| ... } # same thing - # rio('f.txt').lines { |line| ... } # same thing - # - # rio('f.txt').chomp.each { |line| ... } # same as above with lines chomped - # rio('f.txt').chomp { |line| ... } # ditto - # rio('f.txt').lines.chomp { |line| ... } # ditto - # rio('f.txt').chomp.lines { |line| ... } # ditto - # - # rio('f.txt.gz').gzip.each { |line| ... } # execute block for every line in a gzipped file - # rio('f.txt.gz').gzip { |line| ... } # same thing - # rio('f.txt.gz').lines.gzip { |line| ... } # same thing - # - # rio('f.txt.gz').gzip.chomp { |line| ... } # chomp lines from a gzipped file - # rio('f.txt.gz').gzip.chomp.each { |line| ... } # ditto - # rio('f.txt.gz').chomp.lines.gzip { |line| ... } # ditto - # - # rio('f.txt').lines(0..9) { |line| ... } # execute block for the first 10 lines in the file - # rio('f.txt').lines(0..9).each { |line| ... } # same thing - # - # rio('f.txt').lines(/^\s*#/) { |line| ... } # execute block for comment-only lines - # rio('f.txt').lines(/^\s*#/).each { |line| ... } # same thing - # - # rio('f.txt').lines(0,/Rio/) { |line| ... } # execute block for the first line and - # # all lines containing 'Rio' - # - # rio('f.txt.gz').gzip.chomp.lines(0..1) { |line| ... } # first 2 lines chomped from a gzip file - # - # * Processing a file a block at a time - # - # rio('f.dat').bytes(10).each { |data| ... } # process the file 10 bytes at a time - # rio('f.dat').bytes(10) { |data| ... } # same thing - # rio('f.dat').bytes(10).records(2,4) { |data| ... } # only 3rd and 5th ten-byte data-block - # rio('f.dat.gz').gzip.records(2,4).bytes(10) { |data| ... } # same from a gzipped file - # - # * Iterating over directories - # rio('adir').each { |ent| ... } # execute the block for each entry in the directory 'adir' - # rio('adir').files.each { |file| ...} # only files - # rio('adir').files { |file| ...} # ditto - # rio('adir').all.files { |file| ...} # files, recurse into subdirectories - # rio('adir').dirs { |dir| ...} # only directories - # rio('adir').files('*.rb') { |file| ...} # only .rb files using a glob - # rio('adir').files(/\.rb$/) { |file| ...} # only .rb files using a regular expression - # rio('adir').all.files('*.rb') { |file| ...} # .rb files, recursing into subdirectories - # rio('adir').dirs(/^\./) { |dir| ... } # only dot directories - # rio('adir').dirs('/home/*') { |dir| ... } # home directories - # - # See RIO::Doc::HOWTO and RIO::Doc::SYNOPSIS for more examples, and RIO::Doc::INTRO for further explanation. - # - def each(*args,&block) target.each(*args,&block); self end + # Iterate through a rio. Executes the block for each item selected for the Rio. + # See IF::GrandeStream#lines, IF::GrandeStream#records, IF::GrandeStream#bytes, + # IF::GrandeEntry#files, IF::GrandeEntry#dirs, IF::Grande#[] + # and IF::Grande#to_a for more information + # on how records are selected and what kind of record is passed to the block. + # + # IF::Grande#each is the fundemental method for all the Rio grande operators. + # IF::Grande#to_a and the Rio copy operators + # IF::Grande#<, IF::Grande#<<, IF::Grande#>>, and IF::Grande#> + # are all implemented in terms of IF::Grande#each. + # + # While IF::Grande#each is fundamental to a Rio, it rarely needs + # actually be called because all the grande configuration methods will also take a block + # and call IF::Grande#each if one is given. + # So the existance of a block after many methods is taken as an implied + # IF::Grande#each + # + # For Rios that refer to files, the item passed to the block is a String containing + # the line or block as selected by IF::GrandeStream#lines, or IF::GrandeStream#bytes. +lines+ is the default. + # rio('afile').lines.each { |line| ...} + # + # The block passed to +each+ will also accept an optional second parameter which will contain + # the result of the matching function. What this variable contains depends on the argument + # to +lines+ that resulted in the match as follows: + # + # Regexp:: The MatchData that resulted from the match. + # Range:: The record number of the matching record. + # Fixnum:: The record number of the matching record. + # Proc:: The value returned by the proc. + # Symbol:: The value resulting from sending the symbol to the String. + # + # If no selection arguments were used, this variable will simply contain +true+. + # + # rio(??).puts(%w[0:zero 1:one]).rewind.lines(/(\d+):([a-z]+)/) do |line,match| + # puts("#{match[1]} is spelled '#{match[2]}'") + # end + # + # Produces: + # 0 is spelled 'zero' + # 1 is spelled 'one' + # + # + # For Rios that refer to directories, the item passed to the block is a Rio refering to + # the directory entry. + # + # rio('adir').files.each do |file| + # file.kind_of?(RIO::Rio) # true + # end + # + # In addition, the Rio passed to the block inherits certain attributes from the directory Rio. + # + # rio('adir').files.chomp.each do |file| # chomp is ignored for directories, + # file.each do |line| # chomp attribute is inherited by the file rio + # # .. line is chomped + # end + # end + # + # IF::Grande#each returns the Rio which called it. + # + # Here are a few illustrative examples + # + # * Processing lines in a file + # + # rio('f.txt').each { |line| ... } # execute block for every line in the file + # rio('f.txt').lines.each { |line| ... } # same thing + # rio('f.txt').lines { |line| ... } # same thing + # + # rio('f.txt').chomp.each { |line| ... } # same as above with lines chomped + # rio('f.txt').chomp { |line| ... } # ditto + # rio('f.txt').lines.chomp { |line| ... } # ditto + # rio('f.txt').chomp.lines { |line| ... } # ditto + # + # rio('f.txt.gz').gzip.each { |line| ... } # execute block for every line in a gzipped file + # rio('f.txt.gz').gzip { |line| ... } # same thing + # rio('f.txt.gz').lines.gzip { |line| ... } # same thing + # + # rio('f.txt.gz').gzip.chomp { |line| ... } # chomp lines from a gzipped file + # rio('f.txt.gz').gzip.chomp.each { |line| ... } # ditto + # rio('f.txt.gz').chomp.lines.gzip { |line| ... } # ditto + # + # rio('f.txt').lines(0..9) { |line| ... } # execute block for the first 10 lines in the file + # rio('f.txt').lines(0..9).each { |line| ... } # same thing + # + # rio('f.txt').lines(/^\s*#/) { |line| ... } # execute block for comment-only lines + # rio('f.txt').lines(/^\s*#/).each { |line| ... } # same thing + # + # rio('f.txt').lines(0,/Rio/) { |line| ... } # execute block for the first line and + # # all lines containing 'Rio' + # + # rio('f.txt.gz').gzip.chomp.lines(0..1) { |line| ... } # first 2 lines chomped from a gzip file + # + # * Processing a file a block at a time + # + # rio('f.dat').bytes(10).each { |data| ... } # process the file 10 bytes at a time + # rio('f.dat').bytes(10) { |data| ... } # same thing + # rio('f.dat').bytes(10).records(2,4) { |data| ... } # only 3rd and 5th ten-byte data-block + # rio('f.dat.gz').gzip.records(2,4).bytes(10) { |data| ... } # same from a gzipped file + # + # * Iterating over directories + # rio('adir').each { |ent| ... } # execute the block for each entry in the directory 'adir' + # rio('adir').files.each { |file| ...} # only files + # rio('adir').files { |file| ...} # ditto + # rio('adir').all.files { |file| ...} # files, recurse into subdirectories + # rio('adir').dirs { |dir| ...} # only directories + # rio('adir').files('*.rb') { |file| ...} # only .rb files using a glob + # rio('adir').files(/\.rb$/) { |file| ...} # only .rb files using a regular expression + # rio('adir').all.files('*.rb') { |file| ...} # .rb files, recursing into subdirectories + # rio('adir').dirs(/^\./) { |dir| ... } # only dot directories + # rio('adir').dirs('/home/*') { |dir| ... } # home directories + # + # See RIO::Doc::HOWTO and RIO::Doc::SYNOPSIS for more examples, and RIO::Doc::INTRO for further explanation. + # + def each(*args,&block) target.each(*args,&block); self end - # For a file Rio +delete+ calls FileUtils#rm. - # For a directory Rio +delete+ calls FileUtils#rmdir - # Returns the Rio. If the Rio does not exist, simply return the Rio. - # - # rio('afile,txt').delete # delete 'afile.txt' - # rio('adir').delete # delete adir - # rio('something').delete # delete something - # - def delete() target.delete(); self end - # For a file Rio#delete! calls FileUtils#rm. - # For a directory Rio#delete! calls FileUtils#rmtree - # Returns the Rio. If the rio does not exist, simply return itself. - # - # rio('afile,txt').delete! # delete f.txt - # rio('adir').delete! # delete adir - # - # # create a directory, after deleting anything that previously had its name - # rio('adir/asubdir').delete!.mkpath - # - # ==== Deleting Summary - # * To delete something only if it is not a directory use Rio#rm - # * To delete an empty directory use Rio#rmdir - # * To delete an entire directory tree use Rio#rmtree - # * To delete anything except a populated directory use Rio#delete - # * To delete anything use Rio#delete! - # - # In all cases, deleting something that does not exist is considered successful - # - def delete!() target.delete!(); self end + # For a file Rio +delete+ calls FileUtils#rm. + # For a directory Rio +delete+ calls FileUtils#rmdir + # Returns the Rio. If the Rio does not exist, simply return the Rio. + # + # rio('afile,txt').delete # delete 'afile.txt' + # rio('adir').delete # delete adir + # rio('something').delete # delete something + # + def delete() target.delete(); self end - # Grande Copy-To Operator - # - # The copy grande-operator copies a Rio to a another Rio or another ruby object. The behaviour - # and the library used depend on the types of the of the source and destination. For - # simple file or directory copying ::FileUtils#cp or ::FileUtils#cp_r will be used. If - # any of the Rio grande methods are specified for the source or destination, the - # source Rio will be iterated through copying records to the destintion as specified. Roughly - # equivelant to - # dst = rio('dst_file') - # rio('src_file').each do |line| - # dst.print(line) - # end - # dst.close - # - # The destination of the copy operators may be a: - # IO:: Each record of the Rio is written to the IO using IO#print. The IO must be opened for writing. - # Array:: Each record or entry of the Rio becomes an element of the array - # String:: Puts the entire contents of the Rio into the string - # Rio:: Depends on the destination. See below. - # - # Copy a file to a file - # rio('src_file') > rio('dst_file') - # - # Copy a file to a directory - # rio('src_file') > rio('dst_dir') - # - # Copy a directory to another directory - # rio('src_dir') > rio('dst_dir') - # - # Make an ungizipped copy of a gzipped file - # rio('src.txt.gz').gzip > rio('dst.txt') - # - # Copying to an array - # rio('afile') > ary # each line of the file becomes and element of the ary - # rio('afile').chomp > ary # same thing with lines chomped - # rio('afile.gz').gzip.chomp > ary # same thing from a gzipped file - # - # rio('afile').lines(0..9) > ary # ary will contain only the first ten lines of the file - # rio('afile').chomp.lines(0..9) > ary # same thing with lines chomped - # rio('afile').gzip.chomp.lines(0..9) > ary # same thing from a gzipped file - # - # rio('afile').skiplines(0..9) > ary # ary will contain all but the first ten lines of the file - # - # rio('adir') > ary # ary will contain a Rio for each entry in the directory - # rio('adir').files > ary # same, but only files - # rio('adir').files('*.rb') >ary # same, but only .rb files - # - # Copying to a string - # rio('afile') > astring # slurp the entire contents of the file into astring - # astring = rio('afile').contents # same effect - # - # Copy the first line *and* every line containing the word Rio into a gzipped file - # rio('src').lines(1,/Rio/) > rio('dst.gz').gzip - # - # Copy lines of a web page into an array with each line chomped - # rio('http://ruby-doc.org/index.html').chomp > an_array - # - # Copy the first and 8th through 10th columns of the first ten rows of a gzipped csv - # file on a web site into a local gzipped csv file that uses semi-colons as separators - # rio('http://domain/file.csv.gz').columns(0,7..9).gzip.csv[0..9] > rio('localfile.csv.gz').csv(';').gzip - # - def >(destination) - RIO::no_warn { - target > destination; - } - self - end + # For a file IF::Grande#delete! calls FileUtils#rm. + # For a directory IF::Grande#delete! calls FileUtils#rmtree + # Returns the Rio. If the rio does not exist, simply return itself. + # + # rio('afile,txt').delete! # delete f.txt + # rio('adir').delete! # delete adir + # + # # create a directory, after deleting anything that previously had its name + # rio('adir/asubdir').delete!.mkpath + # + # ==== Deleting Summary + # * To delete something only if it is not a directory use IF::File#rm + # * To delete an empty directory use IF::Dir#rmdir + # * To delete an entire directory tree use IF::Dir#rmtree + # * To delete anything except a populated directory use IF::Grande#delete + # * To delete anything use IF::Grande#delete! + # + # In all cases, deleting something that does not exist is considered successful + # + def delete!() target.delete!(); self end - # Alias for Rio#> (copy-to grande operator) - def copy_to(destination) target.copy_to(destination); self end + # Grande Copy-To Operator + # + # The copy grande-operator copies a Rio to a another Rio or another ruby object. The behaviour + # and the library used depend on the types of the of the source and destination. For + # simple file or directory copying ::FileUtils#cp or ::FileUtils#cp_r will be used. If + # any of the Rio grande methods are specified for the source or destination, the + # source Rio will be iterated through copying records to the destintion as specified. Roughly + # equivelant to + # dst = rio('dst_file') + # rio('src_file').each do |line| + # dst.print(line) + # end + # dst.close + # + # The destination of the copy operators may be a: + # IO:: Each record of the Rio is written to the IO using IO#print. The IO must be opened for writing. + # Array:: Each record or entry of the Rio becomes an element of the array + # String:: Puts the entire contents of the Rio into the string + # Rio:: Depends on the destination. See below. + # + # Copy a file to a file + # rio('src_file') > rio('dst_file') + # + # Copy a file to a directory + # rio('src_file') > rio('dst_dir') + # + # Copy a directory to another directory + # rio('src_dir') > rio('dst_dir') + # + # Make an ungizipped copy of a gzipped file + # rio('src.txt.gz').gzip > rio('dst.txt') + # + # Copying to an array + # rio('afile') > ary # each line of the file becomes and element of the ary + # rio('afile').chomp > ary # same thing with lines chomped + # rio('afile.gz').gzip.chomp > ary # same thing from a gzipped file + # + # rio('afile').lines(0..9) > ary # ary will contain only the first ten lines of the file + # rio('afile').chomp.lines(0..9) > ary # same thing with lines chomped + # rio('afile').gzip.chomp.lines(0..9) > ary # same thing from a gzipped file + # + # rio('afile').skiplines(0..9) > ary # ary will contain all but the first ten lines of the file + # + # rio('adir') > ary # ary will contain a Rio for each entry in the directory + # rio('adir').files > ary # same, but only files + # rio('adir').files('*.rb') >ary # same, but only .rb files + # + # Copying to a string + # rio('afile') > astring # slurp the entire contents of the file into astring + # astring = rio('afile').contents # same effect + # + # Copy the first line *and* every line containing the word Rio into a gzipped file + # rio('src').lines(1,/Rio/) > rio('dst.gz').gzip + # + # Copy lines of a web page into an array with each line chomped + # rio('http://ruby-doc.org/index.html').chomp > an_array + # + # Copy the first and 8th through 10th columns of the first ten rows of a gzipped csv + # file on a web site into a local gzipped csv file that uses semi-colons as separators + # rio('http://domain/file.csv.gz').columns(0,7..9).gzip.csv[0..9] > rio('localfile.csv.gz').csv(';').gzip + # + # See also IF::Grande#>>, IF::Grande#| + # + def >(destination) + RIO::no_warn { + target > destination; + } + self + end + # Alias for IF::Grande#> (copy-to grande operator) + def copy_to(destination) target.copy_to(destination); self end - # Grande Pipe Operator - # - # The Rio pipe operator is actually an alternative syntax for calling the copy-to operator, designed to - # allow several copy operation to be performed in one line of code, with behaviour that mimics - # the pipe operator commonly available in shells. - # - # If +destination+ is a +cmdio+, a <tt>cmdpipe</tt> Rio is returned, and none of the commands are run. - # - # Otherwise the +cmdpipe+ Rio is run with the output of the pipe being copied to the destination. - # In this case a Rio representing the +destination+ is returned. - # - # If destination is not a Rio it is passed to the Rio constructor as is done with the copy-to operator - # except that if +destination+ is a String it is assumed to be a command instead of a path. - # - # rio('afile') | rio(?-,'grep i') | rio(?-) # returns rio(?-) - # # equivelent to rio(?-, 'grep i') < rio('afile') > rio(?-) - # - # rio('infile') | rio(?-, 'acmd') | rio(?-, 'acmd2') | rio('outfile') - # # same as - # # acmd = rio(?-,'acmd') - # # acmd2 = rio(?-,'acmd2') - # # out = rio('outfile') - # # acmd < rio('infile') - # # acmd2 < acmd - # # out < acmd2 - # - # rio('afile') | 'acmd' | 'acmd2' | rio('outfile') # same thing - # - # acmdpipe = rio(?-,'acmd') | 'acmd2' - # rio('afile') | acmdpipe | rio('outfile') # same thing - # - # acmdpipe1 = rio(?|,'acmd','acmd2') - # rio('afile') | acmdpipe1 | rio('outfile') # same thing - # - # acmdpipe2 = rio('afile') | 'acmd' | 'acmd2' - # acmdpipe2 | rio('outfile') # same thing - # - # The grande pipe operator can not be used to create a +cmdpipe+ Rio that includes a destination. - # This must be done using a Rio constructor - # cmd_with_output = rio(?|,'acmd',rio('outfile')) - # rio('afile') | cmd_with_output # same as above - # - def |(destination) target | destination end - # Grande Append-To Operator - # - # The append-to grande-operator is the same as Rio#> (copy-to) except that it opens the destination - # for append. - # The destination can be a kind of: - # IO:: Each record of the Rio is written to the IO using IO#print. The IO must be opened for writing. - # Array:: Each record or entry of the Rio is appended to the destination array - # String:: Appends the entire contents of the Rio to destination - # Rio:: Just like Rio#> (copy-to) except the unopened object are - # opened for append. If the destination is already opened for writing or is a - # directory, this is identical to Rio#> (copy-to) - # - # See Rio#> (copy-to) - # - # rio('afile') >> rio('anotherfile') # append the contents of 'afile' to 'anotherfile' - # rio('afile') >> rio('adir') # copies 'afile' to the directory 'adir' - # rio('adir') >> rio('anotherdir') # copy directory 'adir' recursively to 'anotherdir' - # rio('adir') >> array # a Rio for each entry in the directory will be appended to ary - def >>(destination) target >> destination; self end + # Grande Pipe Operator + # + # The Rio pipe operator is actually an alternative syntax for calling the copy-to operator, designed to + # allow several copy operation to be performed in one line of code, with behaviour that mimics + # the pipe operator commonly available in shells. + # + # If +destination+ is a +cmdio+, a <tt>cmdpipe</tt> Rio is returned, and none of the commands are run. + # + # Otherwise the +cmdpipe+ Rio is run with the output of the pipe being copied to the destination. + # In this case a Rio representing the +destination+ is returned. + # + # If destination is not a Rio it is passed to the Rio constructor as is done with the copy-to operator + # except that if +destination+ is a String it is assumed to be a command instead of a path. + # + # rio('afile') | rio(?-,'grep i') | rio(?-) # returns rio(?-) + # # equivelent to rio(?-, 'grep i') < rio('afile') > rio(?-) + # + # rio('infile') | rio(?-, 'acmd') | rio(?-, 'acmd2') | rio('outfile') + # # same as + # # acmd = rio(?-,'acmd') + # # acmd2 = rio(?-,'acmd2') + # # out = rio('outfile') + # # acmd < rio('infile') + # # acmd2 < acmd + # # out < acmd2 + # + # rio('afile') | 'acmd' | 'acmd2' | rio('outfile') # same thing + # + # acmdpipe = rio(?-,'acmd') | 'acmd2' + # rio('afile') | acmdpipe | rio('outfile') # same thing + # + # acmdpipe1 = rio(?|,'acmd','acmd2') + # rio('afile') | acmdpipe1 | rio('outfile') # same thing + # + # acmdpipe2 = rio('afile') | 'acmd' | 'acmd2' + # acmdpipe2 | rio('outfile') # same thing + # + # The grande pipe operator can not be used to create a +cmdpipe+ Rio that includes a destination. + # This must be done using a Rio constructor + # cmd_with_output = rio(?|,'acmd',rio('outfile')) + # rio('afile') | cmd_with_output # same as above + # + def |(destination) target | destination end - - # Alias for Rio#>> (append-to grande operator) - def append_to(destination) target.append_to(destination); self end + # Grande Append-To Operator + # + # The append-to grande-operator is the same as IF::Grande#> (copy-to) except that it opens the destination + # for append. + # The destination can be a kind of: + # IO:: Each record of the Rio is written to the IO using IO#print. The IO must be opened for writing. + # Array:: Each record or entry of the Rio is appended to the destination array + # String:: Appends the entire contents of the Rio to destination + # Rio:: Just like IF::Grande#> (copy-to) except the unopened object are + # opened for append. If the destination is already opened for writing or is a + # directory, this is identical to IF::Grande#> (copy-to) + # + # See IF::Grande#> (copy-to) + # + # rio('afile') >> rio('anotherfile') # append the contents of 'afile' to 'anotherfile' + # rio('afile') >> rio('adir') # copies 'afile' to the directory 'adir' + # rio('adir') >> rio('anotherdir') # copy directory 'adir' recursively to 'anotherdir' + # rio('adir') >> array # a Rio for each entry in the directory will be appended to ary + def >>(destination) target >> destination; self end + + # Alias for IF::Grande#>> (append-to grande operator) + def append_to(destination) target.append_to(destination); self end - # Grande Append-From Operator - # - # The append-from grande-operator copies a Rio from another Rio or another ruby object. This - # behaves like Rio#< (copy-from) except unopened Rios are opened for append. - # - # The following summarizes how objects are copied: - # IO:: IO#each is used to iterate through the source with each record appended to the Rio - # Array:: Each element of the Array is appended individually to the Rio. - # String:: The string is appended to the Rio using Rio#print - # Rio:: The source Rio is appended using its Rio#>> (append-to) operator - # - # See Rio#< (copy-from) - def <<(source) target << source; self end + # Grande Append-From Operator + # + # The append-from grande-operator copies a Rio from another Rio or another ruby object. This + # behaves like IF::Grande#< (copy-from) except unopened Rios are opened for append. + # + # The following summarizes how objects are copied: + # IO:: IO#each is used to iterate through the source with each record appended to the Rio + # Array:: Each element of the Array is appended individually to the Rio. + # String:: The string is appended to the Rio using IF::RubyIO#print + # Rio:: The source Rio is appended using its IF::Grande#>> (append-to) operator + # + # See IF::Grande#< (copy-from) + def <<(source) target << source; self end - # Alias for Rio#<< (append-from grande operator) - def append_from(source) target.append_from(source); self end + # Alias for IF::Grande#<< (append-from grande operator) + def append_from(source) target.append_from(source); self end - # Grande Copy-From Operator - # - # The copy-from grande-operator copies a Rio from another Rio or another ruby object. - # Its operation is dependent on the the file system objects referenced, the rio - # options set, and the state of its source and destination. In the broadest of terms - # it could be described as doing the following: - # source.each do |entry| - # destination << entry - # end - # That is to say, it iterates through its argument, calling the copy-from operator - # again for each element. While it is not implemented like this, and the above code would - # not give the same results, This generalized description is convenient. - # For example the code: - # dst < src - # # is like - # src.each { |line| dst << line } - # for any of the following definitions of src and dst - # * copying files - # src = rio('afile') - # dst = rio('acopy') - # * copying parts of files - # src = rio('afile').lines(0..9) - # dst = rio('acopy') - # * copying directories - # src = rio('srcdir') - # dst = rio('dstdir') - # * copy directories selectively - # src = rio('srcdir').dirs(/^\./).files('*.tmp') - # dst = rio('dstdir') - # * copying to a file from an array - # src = ["line0\n","line1\n"] - # dst = rio('afile') - # * copying to a directory from an array - # array = [rio("file1"),rio("file2")] - # dst = rio('adir') - # - # Arrays are handled differently depending on whether the rio references a file or a directory. - # * If the destination is a file. - # dest = rio('afile') - # dest < array - # # is roughly equivelent to - # array.each do |el| - # case el - # when ::String then dest.print(el) - # when ::Rio then dest << el - # else dest << rio(el) - # end - # * If the destination is a directory - # dest = rio('adir') - # dest < array - # # is roughly equivelent to - # array.each do |el| - # case el - # when ::String then rio(el) - # when ::Rio then dest << el - # else dest << rio(el) - # end - # - # To improve run-time efficiency, Rio will choose from among several strategies when - # copying. For instance when no file or directory filtering is specified, FileUtils#cp_r is - # used to copy directories; and when no line filtering is specified, FileUtils#cp is used to copy - # files. - # - # rio('adir') < rio('anotherdir') # 'anotherdir' is copied to 'adir' using FileUtils#cp_r - # rio('adir') < rio('anotherdir').files('*.rb') # copy only .rb files - # rio('afile') < rio('anotherfile') # 'anotherfile' is copied to 'afile' using FileUtils#cp - # rio('afile') < ios # ios must be an IO object opened for reading - # rio('afile') < astring # basically the same as rio('afile').print(astring) - # - # anarray = [ astring, rio('anotherfile') ] - # rio('afile') < anarray # copies each element to 'afile' as if one had written - # ario = rio('afile') - # anarray.each do |el| - # ario << el - # end - # ario.close - # rio('skeldir') < rio('adir').dirs # copy only the directory structure - # rio('destdir') < rio('adir').dirs.files(/^\./) # copy the directory structure and all dot files - # - # See also Rio#> (copy-to), Rio#each, Rio#[] - # - def <(source) - RIO::no_warn { - target < source - } - self - end - # Alias for Rio#< (copy-from grande operator) - def copy_from(source) target.copy_from(source); self end + # Grande Copy-From Operator + # + # The copy-from grande-operator copies a Rio from another Rio or another ruby object. + # Its operation is dependent on the the file system objects referenced, the rio + # options set, and the state of its source and destination. In the broadest of terms + # it could be described as doing the following: + # source.each do |entry| + # destination << entry + # end + # That is to say, it iterates through its argument, calling the copy-from operator + # again for each element. While it is not implemented like this, and the above code would + # not give the same results, This generalized description is convenient. + # For example the code: + # dst < src + # # is like + # src.each { |line| dst << line } + # for any of the following definitions of src and dst + # * copying files + # src = rio('afile') + # dst = rio('acopy') + # * copying parts of files + # src = rio('afile').lines(0..9) + # dst = rio('acopy') + # * copying directories + # src = rio('srcdir') + # dst = rio('dstdir') + # * copy directories selectively + # src = rio('srcdir').dirs(/^\./).files('*.tmp') + # dst = rio('dstdir') + # * copying to a file from an array + # src = ["line0\n","line1\n"] + # dst = rio('afile') + # * copying to a directory from an array + # array = [rio("file1"),rio("file2")] + # dst = rio('adir') + # + # Arrays are handled differently depending on whether the rio references a file or a directory. + # * If the destination is a file. + # dest = rio('afile') + # dest < array + # # is roughly equivelent to + # array.each do |el| + # case el + # when ::String then dest.print(el) + # when ::Rio then dest << el + # else dest << rio(el) + # end + # * If the destination is a directory + # dest = rio('adir') + # dest < array + # # is roughly equivelent to + # array.each do |el| + # case el + # when ::String then rio(el) + # when ::Rio then dest << el + # else dest << rio(el) + # end + # + # To improve run-time efficiency, Rio will choose from among several strategies when + # copying. For instance when no file or directory filtering is specified, FileUtils#cp_r is + # used to copy directories; and when no line filtering is specified, FileUtils#cp is used to copy + # files. + # + # rio('adir') < rio('anotherdir') # 'anotherdir' is copied to 'adir' using FileUtils#cp_r + # rio('adir') < rio('anotherdir').files('*.rb') # copy only .rb files + # rio('afile') < rio('anotherfile') # 'anotherfile' is copied to 'afile' using FileUtils#cp + # rio('afile') < ios # ios must be an IO object opened for reading + # rio('afile') < astring # basically the same as rio('afile').print(astring) + # + # anarray = [ astring, rio('anotherfile') ] + # rio('afile') < anarray # copies each element to 'afile' as if one had written + # ario = rio('afile') + # anarray.each do |el| + # ario << el + # end + # ario.close + # rio('skeldir') < rio('adir').dirs # copy only the directory structure + # rio('destdir') < rio('adir').dirs.files(/^\./) # copy the directory structure and all dot files + # + # See also IF::Grande#> (copy-to), IF::Grande#each, IF::Grande#[] + # + def <(source) + RIO::no_warn { + target < source + } + self + end + # Alias for IF::Grande#< (copy-from grande operator) + def copy_from(source) target.copy_from(source); self end - # Temporarily set the Rio to read records, and call #get - # - # See also Rio#records, Rio#lines, Rio#each, Rio#[] - # - def getrec() target.getrec() end - # Temporarily set the Rio to read rows, and call #get - # - # See also Rio#rows, Rio#lines, Rio#each, Rio#[] - # - def getrow() target.getrow() end + # Reads and returns the next record or entry from a Rio, + # honoring the grande selection methods. + # + # Returns nil on end of file. + # + # See also IF::GrandeStream#records, IF::GrandeStream#lines, IF::Grande#each, IF::Grande#[] + # + # ario = rio('afile').lines(10..12) + # line10 = ario.get + # line11 = ario.get + # line12 = ario.get + # a_nil = ario.get + # + # ario = rio('adir').entries('*.txt') + # ent1 = ario.get + # ent2 = ario.get + # + def get() target.get() end - # Temporarily set the Rio to read lines, and call #get - # - # See also Rio#records, Rio#lines, Rio#each, Rio#[] - # - def getline() target.getline() end + # Grande Exclude method + # + # +skip+ can be used in two ways. + # + # If called with no arguments it reverses the polarity of the + # next non-skip grande selection method that is called. That is, + # it turns +lines+, +records+, +rows+, +files+, +dirs+ and +entries+ + # into +skiplines+, +skiprecords+, +skiprows+, +skipfiles+, + # +skipdirs+, and +skipentries+, respectively. + # + # rio('afile').skip.lines(0..5) # same as rio('afile').skiplines(0..5) + # rio('adir').skip.files('*~') # same as rio('adir').skipfiles('*~') + # + # Note that it only affects the next selection method seen -- and may be + # used more than once. If no grande selection method is seen, +skip+ is + # ignored. + # + # When called with arguments it acts like IF::GrandeEntry#skipentries for directory + # Rios and like IF::GrandeStream#skiprecords for stream Rios. + # + # rio('afile').lines(/Rio/).skip[0..4] # lines containg 'Rio' excluding the + # # first five lines + # + # rio('adir').files('*.rb').skip[:symlink?] # .rb files, but not symlinks to + # # .rb files + # + # If a block is given, behaves as if <tt>skip(*args).each(&block)</tt> had been called. + # + # Returns the Rio. + # + # See IF::GrandeStream#skiplines, IF::GrandeStream#skiprecords, IF::GrandeStream#skiprows, + # IF::GrandeEntry#skipfiles, IF::GrandeEntry#skipdirs, and IF::GrandeEntry#skipentries. + # + def skip(*args,&block) target.skip(*args,&block); self end - # Reads and returns the next record or entry from a Rio, - # honoring the grande selection methods. - # - # Returns nil on end of file. - # - # See also Rio#records, Rio#lines, Rio#each, Rio#[] - # - # ario = rio('afile').lines(10..12) - # line10 = ario.get - # line11 = ario.get - # line12 = ario.get - # a_nil = ario.get - # - # ario = rio('adir').entries('*.txt') - # ent1 = ario.get - # ent2 = ario.get - # - def get() target.get() end - # Writes a single record to a Rio - def putrec(el) target.putrec(el) end + # Returns true if the referenced file or directory is empty after honoring the grande + # selection methods. + # + # rio('f0').delete!.touch.empty? #=> true + # rio('f1').puts!("Not Empty\n").empty? #=> false + # rio('d0').delete!.mkdir.empty? #=> true + # + def empty?() target.empty? end + # IF::Grande#split has two distinct behaviors depending on + # whether or not it is called with an argument. + # + # ==== split-with-no-aruments: + # + # Returns an array of Rios, one for each path element. + # (Note that this behavior differs from File#split.) + # + # rio('a/b/c').split #=> [rio('a'),rio('b'),rio('c')] + # + # The array returned is extended with a +to_rio+ method, + # which will put the parts back together again. + # + # ary = rio('a/b/c').split #=> [rio('a'),rio('b'),rio('c')] + # ary.to_rio #=> rio('a/b/c') + # + # ary = rio('a/b/c').split #=> [rio('a'),rio('b'),rio('c')] + # ary[1] = rio('d') + # ary.to_rio #=> rio('a/d/c') + # + # See also IF::Path#join, IF::Path#/, IF::Path#splitpath + # + # ==== split-with-an-argument: + # + # 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]] + # + # + def split(*args,&block) target.split(*args,&block) end - # Grande Exclude method - # - # +skip+ can be used in two ways. - # - # If called with no arguments it reverses the polarity of the - # next non-skip grande selection method that is called. That is, - # it turns +lines+, +records+, +rows+, +files+, +dirs+ and +entries+ - # into +skiplines+, +skiprecords+, +skiprows+, +skipfiles+, - # +skipdirs+, and +skipentries+, respectively. - # - # rio('afile').skip.lines(0..5) # same as rio('afile').skiplines(0..5) - # rio('adir').skip.files('*~') # same as rio('adir').skipfiles('*~') - # - # Note that it only affects the next selection method seen -- and may be - # used more than once. If no grande selection method is seen, +skip+ is - # ignored. - # - # When called with arguments it acts like Rio#skipentries for directory - # Rios and like Rio#skiprecords for stream Rios. - # - # rio('afile').lines(/Rio/).skip[0..4] # lines containg 'Rio' excluding the - # # first five lines - # - # rio('adir').files('*.rb').skip[:symlink?] # .rb files, but not symlinks to - # # .rb files - # - # If a block is given, behaves as if <tt>skip(*args).each(&block)</tt> had been called. - # - # Returns the Rio. - # - # See Rio#skiplines, Rio#skiprecords, Rio#skiprows, Rio#skipfiles, - # Rio#skipdirs, and Rio#skipentries. - # - def skip(*args,&block) target.skip(*args,&block); self end + end + end +end - # Returns true if the referenced file or directory is empty after honoring the grande - # selection methods. - # - # rio('f0').delete!.touch.empty? #=> true - # rio('f1').puts!("Not Empty\n").empty? #=> false - # rio('d0').delete!.mkdir.empty? #=> true - # - def empty?() target.empty? end - +module RIO + class Rio + #include RIO::IF::Grande end end