Grande Directory Recursion Method

Sets the Rio to all mode (recursive)

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

all causes subsequent calls to files or dirs to be applied recursively to subdirectories

 rio('adir').all.files('*.[ch]').each { |file| ... } # process all c language source files in adir
                                                     # and all subdirectories of adir
 rio('adir').all.files(/\.[ch]$/) { |file| ... }     # same as above
 rio('adir').files("*.[ch]").all { |file| ... }      # once again
 rio('adir').all.files["*.[ch]"]                     # same, but return an array instead of iterating

Returns true if the rio is in all (recursive) mode. See all

 adir = rio('adir').all.dirs
 adir.all? # true
 adir.each do |subdir|
   subdir.all?  # true
 end

 rio('adir').all? # false

Grande Directory Selection Method

Sets the rio to return directories. args can be used to select which directories are returned.

 ario.files(*args) do |f|
   f.directory?      #=> true
 end

No aguments selects all directories. if args are:

If a block is given, behaves like ario.dirs(*args).each(&block)

See also files, entries, skipdirs

 rio('adir').dirs { |frio| ... } # process all directories in 'adir'
 rio('adir').all.dirs { |frio| ... } #  same thing recursively
 rio('adir').dirs(/^\./) { |frio| ...} # process dot directories
 rio('adir').dirs[/^\./] # return an array of dot directories
 rio('adir').dirs[:symlink?] # an array of symlinks to directories

Given the directory structure ‘adir/a/b/c/d‘

 rio('adir').all.dirs[2]          #=> 'adir/a/b'
 rio('adir').all.dirs[0..2]       #=> 'adir/a','adir/a/b'
 rio('adir').all.skipdirs[0..2]   #=> 'adir/a/b/c','adir/a/b/c/d'

Grande Directory Entry Selection Method

No aguments selects all entries.

if args are:

If a block is given, behaves like ario.etries(*args).each(&block)

See also files, dirs, skipentries

 rio('adir').entries { |frio| ... } # process all entries in 'adir'
 rio('adir').all.entries { |frio| ... } #  same thing recursively
 rio('adir').entries(/^\./) { |frio| ...} # process entries starting with a dot
 rio('adir').entries[/^\./] # return an array of all entries starting with a dot
 rio('adir').entries[:symlink?] # an array of symlinks in 'adir'

Grande File Selection Method

Configures the rio to process files. args can be used to select which files are returned.

 ario.files(*args) do |f|
   f.file?      #=> true
 end

No aguments selects all files.

args may be zero or more of the following:

files returns the Rio which called it. This might seem counter-intuitive at first. One might reasonably assume that

 rio('adir').files('*.rb')

would return files. It does not. It configures the rio to return files and returns the Rio. This enables chaining for further configuration so constructs like

 rio('adir').all.files('*.rb').norecurse('.svn')

are possible.

If a block is given, behaves like

 ario.files(*args).each

See also dirs, entries, skipfiles

 rio('adir').files { |frio| ... } # process all files in 'adir'
 rio('adir').all.files { |frio| ... } #  same thing recursively
 rio('adir').files('*.rb') { |frio| ...} # process .rb files
 rio('adir').files['*.rb'] # return an array of .rb files
 rio('adir').files[/\.rb$/] # same thing using a regular expression
 rio('adir').files[:symlink?] # an array of symlinks to files
 rio('adir').files >> rio('other_dir') # copy files to 'other_dir'
 rio('adir').files('*.rb') >> rio('other_dir') # only copy .rb files

For Rios that refer to files, files(*args) causes the file to be processed only if it meets the criteria specified by the args.

 rio('afile.z').files['*.z'] #=> [rio('afile.z')]
 rio('afile.q').files['*.z'] #=> []

Example Problem

Fill the array ruby_progs with all ruby programs in a directory and its subdirectories, skipping those in subversion (.svn) directories.

 ruby_progs = []

For the purposes of this problem, a Ruby program is defined as a file ending with .rb or a file that is executable and whose shebang line contains ‘ruby’:

 is_ruby_exe = proc{ |f| f.executable? and f.gets =~ /^#!.+ruby/ }

Solution 1. Use the subscript operator.

 ruby_progs = rio('adir').norecurse('.svn').files['*.rb',is_ruby_exe]

Explanation:

1. Create the Rio

   Create a Rio for a directory

    rio('adir')
   

2. Configure the Rio

   Specify recursion and that ’.svn’ directories should not be included.

    rio('adir').norecurse('.svn')
   

   Select files

    rio('adir').norecurse('.svn').files
   

   Limit to files ending with ’.rb’

    rio('adir').norecurse('.svn').files('*.rb')
   

   Also allow files for whom is_ruby_exe returns true

    rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe)
   

3. Do the I/O

   Return an array rather than iterating thru them

    ruby_progs = rio('adir').norecurse('.svn').files['*.rb',is_ruby_exe]
   

Solution 2. Use the copy-to operator

 rio('adir').files('*.rb',is_ruby_exe).norecurse('.svn') > ruby_progs

Explanation:

1. Create the Rio

   Create a Rio for a directory

    rio('adir')
   

2. Configure the Rio

   Select only files

    rio('adir').files
   

   Limit to files ending with ’.rb’

    rio('adir').files('*.rb')
   

   Also allow files for whom is_ruby_exe returns true

    rio('adir').files('*.rb',is_ruby_exe)
   

   Specify recursion and that ’.svn’ directories should not be included.

    rio('adir').files('*.rb',is_ruby_exe).norecurse('.svn')
   

3. Do the I/O

   Copy the Rio to ruby_progs

    rio('adir').files('*.rb',is_ruby_exe).norecurse('.svn') > ruby_progs
   

Example Discussion

Note that the only difference between Step 2 of Solution 1 and that of Solution 2 is the order of the configuration methods. Step 2 of Solution 1 would have worked equally well:

 rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe) > ruby_progs

Furthermore if our problem were changed slightly and instead of having our results ending up in an array, we wished to iterate through them, we could use:

 rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe) { |ruby_prog_rio| ... }

Note the similarities. In fact, solution 1 could have been written:

 rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe).to_a

or

 rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe)[]

Passing the arguments for files to the subscript operator is syntactic sugar. The subscript operator does not really take any arguments of its own. It always passes them to the most recently called of the grande selection methods (or the default selection method, if none have been called). So,

 rio('adir').files['*.rb']

is a shortcut for

 rio('adir').files('*.rb').to_a

and

 rio('adir')['*.rb']

is a shortcut for

 rio('adir').entries('*.rb').to_a

and

 rio('afile').lines[0..10]

is a shortcut for

 rio('afile').lines(0..10).to_a

And so on.

Grande Directory Recursion Exclude Method

Sets the Rio to recurse into directories like all. If no args are provided, no directories will be recursed into. If args are provided, behaves like recurse, except that matching directories will not be recursed into

 rio('adir').norecurse('.svn') { |drio| ... } # recurse, skipping subversion directories

 rio('adir').norecurse(3) {|drio| ... } # only recurse 2 levels deep into a directory structure

Grande Directory Recursion Selection Method

Sets the Rio to recurse into directories like all. If no args are provided behaves like all. If args are provided, they are processed like dirs to select which subdirectories should be recursed into. recurse always implies all.

args may be one or more of:

If a block is given, behaves like ario.recurse(*args).each(&block)

See also norecurse, all, dirs

 rio('adir').recurse('test*') { |drio| ... } # process all entries and all entries in subdirectories
                                             # starting with 'test' -- recursively

Grande Directory Exclude Method

If no args are provided selects anything but directories.

 ario.skipdirs do |el|
   el.directory?     #=> false
 end

If args are provided, sets the rio to select directories as with dirs, but the arguments are used to determine which directories will not be processed

If a block is given behaves like

 ario.skipdirs(*args).each(&block)

See dirs

 rio('adir').skipdirs { |ent| ... } # iterate through everything except directories
 rio('adir').skipdirs(/^\./) { |drio| ... } # iterate through directories, skipping dot directories

Grande Directory Entry Rejection Method

No aguments rejects all entries.

Behaves like entries, except that matching entries are excluded.

See also entries, skip

Grande File Exclude Method

If no args are provided selects anything but files.

 ario.skipfiles do |el|
   el.file?     #=> false
 end

If args are provided, sets the rio to select files as with files, but the arguments are used to determine which files will not be processed

If a block is given behaves like ario.skipfiles(*args).each(&block)

See files, skip

 rio('adir').skipfiles { |ent| ... } # iterate through everything except files
 rio('adir').skipfiles('*~') { |frio| ... } # iterate through files, skipping those ending with a tilde