module RIO
Public Class Methods
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 RFC1738rio('file:///atopleveldir/adir/afile')
-
a
URI
object representing afile
or genericURL
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 aboverio(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
URLrio('http://ruby-doc.org/index.html')
-
a
URI
object representing ahttp
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
URLrio('ftp://user:password@ftp.example.com/afile.tar.gz')
-
a
URI
object representing aftp
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 createsrio(?")
-
create a
Rio
that refers to a string of your choosingastring = "" 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
or
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 not 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, ...)
See also IF::Grande#|
# File lib/rio/constructor.rb, line 210 def rio(*args,&block) # :yields: self Rio.rio(*args,&block) end
Private Instance Methods
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 RFC1738rio('file:///atopleveldir/adir/afile')
-
a
URI
object representing afile
or genericURL
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 aboverio(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
URLrio('http://ruby-doc.org/index.html')
-
a
URI
object representing ahttp
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
URLrio('ftp://user:password@ftp.example.com/afile.tar.gz')
-
a
URI
object representing aftp
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 createsrio(?")
-
create a
Rio
that refers to a string of your choosingastring = "" 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
or
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 not 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, ...)
See also IF::Grande#|
# File lib/rio/constructor.rb, line 210 def rio(*args,&block) # :yields: self Rio.rio(*args,&block) end