Module: RIO

To create the documentation for Rio run the command

 ruby build_doc.rb

from the distribution directory.

Methods

cwd rio root

Classes and Modules

Module RIO::Doc
Module RIO::IF
Class RIO::Rio

Public Instance methods

cwd(*args) {|self| ...}

Create a Rio as with RIO#rio which refers to the current working directory

  wd = RIO.cwd

If passed arguments they are treated as if

  rio(RIO.cwd,*args)

had been called

rio(*args) {|self| ...}

Rio Constructor

For purposes of discussion, we divide Rios into two catagories, those that have a path and those that don’t.

Creating a Rio that has a path

To create a Rio that has a path the arguments to rio may be:

a string representing the entire path. The separator used for Rios is as specified in RFC1738 (’/’).
```
 rio('adir/afile')
```
a string representing a fully qualified file URL as per RFC1738
```
 rio('file:///atopleveldir/adir/afile')
```
a URI object representing a file or generic URL
```
 rio(URI('adir/afile'))
```
the components of a path as separate arguments
```
 rio('adir','afile')
```
the components of a path as an array of separate arguments
```
 rio(%w/adir afile/)
```

another Rio

 another_rio = rio('adir/afile')
 rio(another_rio)

any object whose to_s method returns one of the above
```
 rio(Pathname.new('apath'))
```

any combination of the above either as separate arguments or as elements of an array,

 another_rio = rio('dir1/dir2')
 auri = URI('dir4/dir5)
 rio(another_rio,'dir3',auri,'dir6/dir7')

Creating a Rio that refers to a web page

To create a Rio that refers to a web page the arguments to rio may be:

a string representing a fully qualified http URL
```
 rio('http://ruby-doc.org/index.html')
```

a URI object representing a http URL

 rio(URI('http://ruby-doc.org/index.html'))

either of the above with additional path elements

 rio('http://www.ruby-doc.org/','core','classes/Object.html')

Creating a Rio that refers to a file or directory on a FTP server

To create a Rio that refers to a file on a FTP server the arguments to rio may be:

a string representing a fully qualified ftp URL

 rio('ftp://user:password@ftp.example.com/afile.tar.gz')

a URI object representing a ftp URL

 rio(URI('ftp://ftp.example.com/afile.tar.gz'))

either of the above with additional path elements

 rio('ftp://ftp.gnu.org/pub/gnu','emacs','windows','README')

Creating Rios that do not have a path

To create a Rio without a path, the first argument to rio is usually either a single character or a symbol.

Creating a Rio that refers to a clone of your programs stdin or stdout.

rio(?-) (mnemonic: ’-’ is used by some Unix programs to specify stdin or stdout in place of a file)

rio(:stdio)

Just as a Rio that refers to a file, does not know whether that file will be opened for reading or writing until an I/O operation is specified, a stdio: Rio does not know whether it will connect to stdin or stdout until an I/O operation is specified.

Currently :stdin and :stdout are allowed as synonyms for :stdio. This allows one to write

 rio(:stdout).puts("Hello :stdout")

which is reasonable. It also allows one to write

 rio(:stdin).puts("Hello :stdin")

which is not reasonable and will be disallowed in future releases.

Creating a Rio that refers to a clone of your programs stderr.

rio(?=) (mnemonic: ’-’ refers to fileno 1, so ’=’ refers to fileno 2)

rio(:stderr)

Creating a Rio that refers to an arbitrary IO object.

 an_io = ::File.new('afile')
 rio(an_io)

Creating a Rio that refers to a file descriptor

rio(?#,file_descriptor) (mnemonic: a file descriptor is a number ’#’)

rio(:fd,file_descriptor)

 an_io = ::File.new('afile')
 fnum = an_io.fileno
 rio(?#,fnum)

Creating a Rio that refers to a StringIO object

rio(?") (mnemonic: ’"’ surrounds strings)

rio(:string)

rio(:strio)

rio(:stringio)

create a Rio that refers to a string that it creates
```
 rio(?")
```
create a Rio that refers to a string of your choosing
```
 astring = ""
 rio(?",astring)
```

Creating a Rio that refers to a temporary object

To create a temporary object that will become a file (Tempfile) or a temporary directory, depending on how it is used.

rio(??) (mnemonic: ’?’ you don’t know its name)

rio(:temp)

The following are also supported, to specify file or directory

rio(:tempfile)

rio(:tempdir)

 rio(??)
 rio(??,basename='rio',tmpdir=Dir::tmpdir)

To create a temporary object that will become a file or a directory, depending on how you use it:

 rio(??)
 rio(??,basename='rio',tmpdir=Dir::tmpdir)

To force it to become a file

 rio(??).file

or just write to it.

To force it to become a directory:

 rio(??).mkdir

 rio(??).chdir

Creating a Rio that refers to an arbitrary TCPSocket

rio(‘tcp:’,hostname,port)

rio(‘tcp://hostname:port’)

rio(:tcp,hostname,port)

Creating a Rio that runs an external program and connects to its stdin and stdout

rio(?-,cmd) (mnemonic: ’-’ is used by some Unix programs to specify stdin or stdout in place of a file)

rio(?`,cmd) (mnemonic: ’`’ (backtick) runs an external program in ruby)

rio(:cmdio,cmd)

This is Rio’s interface to IO#popen

Creating a Rio that acts like /dev/null

rio(nil)

rio(:null)

This rio behaves like the Unix file /dev/null, but does depend on it - and thus will work on non-Unix systems. Reading behaves as if reading from an empty file, and writing to it discards anything written.

Creating a Rio Pipe

A Rio Pipe is a sequence of Rios that are run with the output of each being copied to the input of the next.

rio(?|, ario, …) (mnemonic: ’|’ is the Unix pipe operator)

rio(:cmdpipe, ario, …)