archive/ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2025-08-24 05:25:34 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

* io.c: Edited documentation for IO and File open and new and

Browse source 
Kernel#open for consistency and clarity.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@35914 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain 2012-06-05 00:37:08 +00:00
parent 07e222d720
commit e1b230d557
2 changed files with 187 additions and 174 deletions
Download patch file Download diff file Expand all files Collapse all files

5
ChangeLog
View file

@ -1,3 +1,8 @@
Tue Jun 5 09:25:10 2012 Eric Hodel <drbrain@segment7.net>
* io.c: Edited documentation for IO and File open and new and
Kernel#open for consistency and clarity.
Mon Jun 4 21:53:56 2012 Nobuyoshi Nakada <nobu@ruby-lang.org> Mon Jun 4 21:53:56 2012 Nobuyoshi Nakada <nobu@ruby-lang.org>
* win32/win32.c (rb_w32_sysinit): let the system not display the * win32/win32.c (rb_w32_sysinit): let the system not display the

348
io.c
View file

@ -5933,27 +5933,29 @@ rb_open_file(int argc, VALUE *argv, VALUE io)
* *
* With no associated block, <code>File.open</code> is a synonym for * With no associated block, <code>File.open</code> is a synonym for
* File.new. If the optional code block is given, it will * File.new. If the optional code block is given, it will
* be passed the opened +file+ as an argument, and the File object will * be passed the opened +file+ as an argument and the File object will
* automatically be closed when the block terminates. In this instance, * automatically be closed when the block terminates. The value of the block
* <code>File.open</code> returns the value of the block. * will be returned from <code>File.open</code>.
* *
* See IO.new for a list of values for the +opt+ parameter. * If a file is being created, its initial permissions may be set using the
* +perm+ parameter. See File.new for further discussion.
*
* See IO.new for a description of the +mode+ and +opt+ parameters.
*/ */
/* /*
* Document-method: IO::open * Document-method: IO::open
* *
* call-seq: * call-seq:
* IO.open(fd, mode_string="r" [, opt]) -> io * IO.open(fd, mode="r" [, opt]) -> io
* IO.open(fd, mode_string="r" [, opt]) {|io| block } -> obj * IO.open(fd, mode="r" [, opt]) { |io| block } -> obj
* *
* With no associated block, <code>IO.open</code> is a synonym for IO.new. If * With no associated block, <code>IO.open</code> is a synonym for IO.new. If
* the optional code block is given, it will be passed +io+ as an * the optional code block is given, it will be passed +io+ as an argument,
* argument, and the IO object will automatically be closed when the block * and the IO object will automatically be closed when the block terminates.
* terminates. In this instance, IO.open returns the value of the block. * In this instance, IO.open returns the value of the block.
*
* See IO.new for a description of values for the +opt+ parameter.
* *
* See IO.new for a description of the +fd+, +mode+ and +opt+ parameters.
*/ */
static VALUE static VALUE
@ -5976,7 +5978,6 @@ rb_io_s_open(int argc, VALUE *argv, VALUE klass)
* <code>Fixnum</code>. * <code>Fixnum</code>.
* *
* IO.sysopen("testfile") #=> 3 * IO.sysopen("testfile") #=> 3
*
*/ */
static VALUE static VALUE
@ -6024,72 +6025,58 @@ check_pipe_command(VALUE filename_or_command)
/* /*
* call-seq: * call-seq:
* open(path [, mode_enc [, perm]] [, opt]) -> io or nil * open(path [, mode [, perm]] [, opt]) -> io or nil
* open(path [, mode_enc [, perm]] [, opt]) {|io| block } -> obj * open(path [, mode [, perm]] [, opt]) {|io| block } -> obj
* *
* Creates an <code>IO</code> object connected to the given stream, * Creates an IO object connected to the given stream, file, or subprocess.
* file, or subprocess.
* *
* If <i>path</i> does not start with a pipe character * If +path+ does not start with a pipe character (<code>|</code>), treat it
* (``<code>|</code>''), treat it as the name of a file to open using * as the name of a file to open using the specified mode (defaulting to
* the specified mode (defaulting to ``<code>r</code>''). * "r").
* *
* The mode_enc is * The +mode+ is either a string or an integer. If it is an integer, it
* either a string or an integer. If it is an integer, it must be * must be bitwise-or of open(2) flags, such as File::RDWR or File::EXCL. If
* bitwise-or of open(2) flags, such as File::RDWR or File::EXCL. * it is a string, it is either "fmode", "fmode:ext_enc", or
* If it is a string, it is either "mode", "mode:ext_enc", or * "fmode:ext_enc:int_enc".
* "mode:ext_enc:int_enc".
* The mode is one of the following:
* *
* r: read (default) * See the documentation of IO.new for full documentation of the +mode+ string
* w: write * directives.
* a: append
* *
* The mode can be followed by "b" (means binary-mode), or "+" * If a file is being created, its initial permissions may be set using the
* (means both reading and writing allowed) or both. * +perm+ parameter. See File.new and the open(2) and chmod(2) man pages for
* If ext_enc (external encoding) is specified, * a description of permissions.
* read string will be tagged by the encoding in reading,
* and output string will be converted
* to the specified encoding in writing.
* If ext_enc starts with 'BOM|', check whether the input has a BOM. If
* there is a BOM, strip it and set external encoding as
* what the BOM tells. If there is no BOM, use ext_enc without 'BOM|'.
* If two encoding names,
* ext_enc and int_enc (external encoding and internal encoding),
* are specified, the read string is converted from ext_enc
* to int_enc then tagged with the int_enc in read mode,
* and in write mode, the output string will be
* converted from int_enc to ext_enc before writing.
* *
* If a file is being created, its initial permissions may be * If a block is specified, it will be invoked with the IO object as a
* set using the integer third parameter. * parameter, and the IO will be automatically closed when the block
* terminates. The call returns the value of the block.
* *
* If a block is specified, it will be invoked with the * If +path+ starts with a pipe character (<code>"|"</code>), a subprocess is
* <code>File</code> object as a parameter, and the file will be * created, connected to the caller by a pair of pipes. The returned IO
* automatically closed when the block terminates. The call * object may be used to write to the standard input and read from the
* returns the value of the block. * standard output of this subprocess.
* *
* If <i>path</i> starts with a pipe character, a subprocess is * If the command following the pipe is a single minus sign
* created, connected to the caller by a pair of pipes. The returned * (<code>"|-"</code>), Ruby forks, and this subprocess is connected to the
* <code>IO</code> object may be used to write to the standard input * parent. If the command is not <code>"-"</code>, the subprocess runs the
* and read from the standard output of this subprocess. If the command * command.
* following the ``<code>|</code>'' is a single minus sign, Ruby forks, *
* and this subprocess is connected to the parent. In the subprocess, * When the subprocess is ruby (opened via <code>"|-"</code>), the +open+
* the <code>open</code> call returns <code>nil</code>. If the command * call returns +nil+. If a block is associated with the open call, that
* is not ``<code>-</code>'', the subprocess runs the command. If a * block will run twice --- once in the parent and once in the child.
* block is associated with an <code>open("|-")</code> call, that block *
* will be run twice---once in the parent and once in the child. The * The block parameter will be an IO object in the parent and +nil+ in the
* block parameter will be an <code>IO</code> object in the parent and * child. The parent's +IO+ object will be connected to the child's $stdin
* <code>nil</code> in the child. The parent's <code>IO</code> object * and $stdout. The subprocess will be terminated at the end of the block.
* will be connected to the child's <code>$stdin</code> and *
* <code>$stdout</code>. The subprocess will be terminated at the end * === Examples
* of the block. *
* Reading from "testfile":
* *
* open("testfile") do |f| * open("testfile") do |f|
* print f.gets * print f.gets
* end * end
* *
* <em>produces:</em> * Produces:
* *
* This is line one * This is line one
* *
@ -6099,7 +6086,7 @@ check_pipe_command(VALUE filename_or_command)
* print cmd.gets * print cmd.gets
* cmd.close * cmd.close
* *
* <em>produces:</em> * Produces:
* *
* Wed Apr 9 08:56:31 CDT 2003 * Wed Apr 9 08:56:31 CDT 2003
* *
@ -6113,21 +6100,23 @@ check_pipe_command(VALUE filename_or_command)
* puts "Got: #{f.gets}" * puts "Got: #{f.gets}"
* end * end
* *
* <em>produces:</em> * Produces:
* *
* Got: in Child * Got: in Child
* *
* Open a subprocess using a block to receive the I/O object: * Open a subprocess using a block to receive the IO object:
* *
* open("|-") do |f| * open "|-" do |f|
* if f == nil * if f then
* puts "in Child" * # parent process
* else
* puts "Got: #{f.gets}" * puts "Got: #{f.gets}"
* else
* # child process
* puts "in Child"
* end * end
* end * end
* *
* <em>produces:</em> * Produces:
* *
* Got: in Child * Got: in Child
*/ */
@ -6910,59 +6899,116 @@ rb_io_stdio_file(rb_io_t *fptr)
* call-seq: * call-seq:
* IO.new(fd [, mode] [, opt]) -> io * IO.new(fd [, mode] [, opt]) -> io
* *
* Returns a new IO object (a stream) for the given IO object or integer file * Returns a new IO object (a stream) for the given integer file descriptor
* descriptor and mode string. See also IO.sysopen and IO.for_fd. * +fd+ and +mode+ string. +opt+ may be used to specify parts of +mode+ in a
* more readable fashion. See also IO.sysopen and IO.for_fd.
* *
* === Parameters * IO.new is called by various File and IO opening methods such as IO::open,
* Kernel#open, and File::open.
* *
* fd:: numeric file descriptor or IO object * === Open Mode
* mode:: file mode. a string or an integer
* opt:: hash for specifying +mode+ by name.
* *
* ==== Mode * When +mode+ is an integer it must be combination of the modes defined in
* File::Constants (+File::RDONLY+, +File::WRONLY | File::CREAT+). See the
* open(2) man page for more information.
* *
* When mode is an integer it must be combination of the modes defined in * When +mode+ is a string it must be in one of the following forms:
* File::Constants.
* *
* When mode is a string it must be in one of the following forms: * fmode
* - "fmode", * fmode ":" ext_enc
* - "fmode:extern", * fmode ":" ext_enc ":" int_enc
* - "fmode:extern:intern". * fmode ":" "BOM|UTF-*"
* <code>extern</code> is the external encoding name for the IO.
* <code>intern</code> is the internal encoding.
* <code>fmode</code> must be a file open mode string. See the description of
* class IO for mode string directives.
* *
* When the mode of original IO is read only, the mode cannot be changed to * +fmode+ is an IO open mode string, +ext_enc+ is the external encoding for
* be writable. Similarly, the mode cannot be changed from write only to * the IO and +int_enc+ is the internal encoding.
* readable. *
* ==== IO Open Mode
*
* Ruby allows the following open modes:
*
* "r" :: Read-only, starts at beginning of file (default mode).
*
* "r+" :: Read-write, starts at beginning of file.
*
* "w" :: Write-only, truncates existing file
* to zero length or creates a new file for writing.
*
* "w+" :: Read-write, truncates existing file to zero length
* or creates a new file for reading and writing.
*
* "a" :: Write-only, starts at end of file if file exists,
* otherwise creates a new file for writing.
*
* "a+" :: Read-write, starts at end of file if file exists,
* otherwise creates a new file for reading and
* writing.
*
* "b" :: Binary file mode (may appear with
* any of the key letters listed above).
* Suppresses EOL <-> CRLF conversion on Windows. And
* sets external encoding to ASCII-8BIT unless explicitly
* specified.
*
* "t" :: Text file mode (may appear with
* any of the key letters listed above except "b").
*
* When the open mode of original IO is read only, the mode cannot be
* changed to be writable. Similarly, the open mode cannot be changed from
* write only to readable.
* *
* When such a change is attempted the error is raised in different locations * When such a change is attempted the error is raised in different locations
* according to the platform. * according to the platform.
* *
* ==== Options * === IO Encoding
* +opt+ can have the following keys *
* When +ext_enc+ is specified, strings read will be tagged by the encoding
* when reading, and strings output will be converted to the specified
* encoding when writing.
*
* When +ext_enc+ and +int_enc+ are specified read strings will be converted
* from +ext_enc+ to +int_enc+ upon input, and written strings will be
* converted from +int_enc+ to +ext_enc+ upon output. See Encoding for
* further details of transcoding on input and output.
*
* If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, ruby checks for
* a Unicode BOM in the input document to help determine the encoding. For
* UTF-16 encodings the file open mode must be binary. When present, the BOM
* is stripped and the external encoding from the BOM is used. When the BOM
* is missing the given Unicode encoding is used as +ext_enc+. (The BOM-set
* encoding option is case insensitive, so "bom|utf-8" is also valid.)
*
* === Options
*
* +opt+ can be used instead of +mode+ for improved readability. The
* following keys are supported:
*
* :mode :: * :mode ::
* Same as +mode+ parameter * Same as +mode+ parameter
* :external_encoding :: *
* :\external_encoding ::
* External encoding for the IO. "-" is a synonym for the default external * External encoding for the IO. "-" is a synonym for the default external
* encoding. * encoding.
* :internal_encoding :: *
* :\internal_encoding ::
* Internal encoding for the IO. "-" is a synonym for the default internal * Internal encoding for the IO. "-" is a synonym for the default internal
* encoding. * encoding.
* *
* If the value is nil no conversion occurs. * If the value is nil no conversion occurs.
*
* :encoding :: * :encoding ::
* Specifies external and internal encodings as "extern:intern". * Specifies external and internal encodings as "extern:intern".
*
* :textmode :: * :textmode ::
* If the value is truth value, same as "t" in argument +mode+. * If the value is truth value, same as "t" in argument +mode+.
*
* :binmode :: * :binmode ::
* If the value is truth value, same as "b" in argument +mode+. * If the value is truth value, same as "b" in argument +mode+.
*
* :autoclose :: * :autoclose ::
* If the value is +false+, the +fd+ will be kept open after this IO * If the value is +false+, the +fd+ will be kept open after this IO
* instance gets finalized. * instance gets finalized.
* *
* Also +opt+ can have same keys in String#encode for controlling conversion * Also, +opt+ can have same keys in String#encode for controlling conversion
* between the external encoding and the internal encoding. * between the external encoding and the internal encoding.
* *
* === Example 1 * === Example 1
@ -6972,7 +7018,7 @@ rb_io_stdio_file(rb_io_t *fptr)
* $stderr.puts "Hello" * $stderr.puts "Hello"
* a.puts "World" * a.puts "World"
* *
* <em>produces:</em> * Produces:
* *
* Hello * Hello
* World * World
@ -7059,20 +7105,14 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io)
* File.new(filename, mode="r" [, opt]) -> file * File.new(filename, mode="r" [, opt]) -> file
* File.new(filename [, mode [, perm]] [, opt]) -> file * File.new(filename [, mode [, perm]] [, opt]) -> file
* *
* Opens the file named by +filename+ according to +mode+ (default is "r") * Opens the file named by +filename+ according to the given +mode+ and
* and returns a new <code>File</code> object. * returns a new File object.
* *
* === Parameters * See IO.new for a description of +mode+ and +opt+.
* *
* See the description of class IO for a description of +mode+. The file * If a file is being created, permission bits may be given in +perm+. These
* mode may optionally be specified as a Fixnum by +or+-ing together the * mode and permission bits are platform dependent; on Unix systems, see
* flags (O_RDONLY etc, again described under +IO+). * open(2) and chmod(2) man pages for details.
*
* Optional permission bits may be given in +perm+. These mode and
* permission bits are platform dependent; on Unix systems, see
* <code>open(2)</code> for details.
*
* Optional +opt+ parameter is same as in IO.open.
* *
* === Examples * === Examples
* *
@ -11177,91 +11217,59 @@ argf_write(VALUE argf, VALUE str)
*/ */
/* /*
* Class <code>IO</code> is the basis for all input and output in Ruby. * The IO class is the basis for all input and output in Ruby.
* An I/O stream may be <em>duplexed</em> (that is, bidirectional), and * An I/O stream may be <em>duplexed</em> (that is, bidirectional), and
* so may use more than one native operating system stream. * so may use more than one native operating system stream.
* *
* Many of the examples in this section use class <code>File</code>, * Many of the examples in this section use the File class, the only standard
* the only standard subclass of <code>IO</code>. The two classes are * subclass of IO. The two classes are closely associated. Like the File
* closely associated. * class, the Socket library subclasses from IO (such as TCPSocket or
* UDPSocket).
* *
* As used in this section, <em>portname</em> may take any of the * The Kernel#open method can create an IO (or File) object for these types
* following forms. * of arguments:
* *
* * A plain string represents a filename suitable for the underlying * * A plain string represents a filename suitable for the underlying
* operating system. * operating system.
* *
* * A string starting with ``<code>|</code>'' indicates a subprocess. * * A string starting with <code>"|"</code> indicates a subprocess.
* The remainder of the string following the ``<code>|</code>'' is * The remainder of the string following the <code>"|"</code> is
* invoked as a process with appropriate input/output channels * invoked as a process with appropriate input/output channels
* connected to it. * connected to it.
* *
* * A string equal to ``<code>|-</code>'' will create another Ruby * * A string equal to <code>"|-"</code> will create another Ruby
* instance as a subprocess. * instance as a subprocess.
* *
* The IO may be opened with different file modes (read-only, write-only) and
* encodings for proper conversion. See IO.new for these options. See
* Kernel#open for details of the various command formats described above.
*
* IO.popen, the Open3 library, or Process#spawn may also be used to
* communicate with subprocesses through an IO.
*
* Ruby will convert pathnames between different operating system * Ruby will convert pathnames between different operating system
* conventions if possible. For instance, on a Windows system the * conventions if possible. For instance, on a Windows system the
* filename ``<code>/gumby/ruby/test.rb</code>'' will be opened as * filename <code>"/gumby/ruby/test.rb"</code> will be opened as
* ``<code>\gumby\ruby\test.rb</code>''. When specifying a * <code>"\gumby\ruby\test.rb"</code>. When specifying a Windows-style
* Windows-style filename in a Ruby string, remember to escape the * filename in a Ruby string, remember to escape the backslashes:
* backslashes:
* *
* "c:\\gumby\\ruby\\test.rb" * "c:\\gumby\\ruby\\test.rb"
* *
* Our examples here will use the Unix-style forward slashes; * Our examples here will use the Unix-style forward slashes;
* <code>File::SEPARATOR</code> can be used to get the * File::ALT_SEPARATOR can be used to get the platform-specific separator
* platform-specific separator character. * character.
*
* I/O ports may be opened in any one of several different modes, which
* are shown in this section as <em>mode</em>. The mode may
* either be a Fixnum or a String. If numeric, it should be
* one of the operating system specific constants (O_RDONLY,
* O_WRONLY, O_RDWR, O_APPEND and so on). See man open(2) for
* more information.
*
* If the mode is given as a String, it must be one of the
* values listed in the following table.
*
* Mode | Meaning
* -----+--------------------------------------------------------
* "r" | Read-only, starts at beginning of file (default mode).
* -----+--------------------------------------------------------
* "r+" | Read-write, starts at beginning of file.
* -----+--------------------------------------------------------
* "w" | Write-only, truncates existing file
* | to zero length or creates a new file for writing.
* -----+--------------------------------------------------------
* "w+" | Read-write, truncates existing file to zero length
* | or creates a new file for reading and writing.
* -----+--------------------------------------------------------
* "a" | Write-only, starts at end of file if file exists,
* | otherwise creates a new file for writing.
* -----+--------------------------------------------------------
* "a+" | Read-write, starts at end of file if file exists,
* | otherwise creates a new file for reading and
* | writing.
* -----+--------------------------------------------------------
* "b" | Binary file mode (may appear with
* | any of the key letters listed above).
* | Suppresses EOL <-> CRLF conversion on Windows. And
* | sets external encoding to ASCII-8BIT unless explicitly
* | specified.
* -----+--------------------------------------------------------
* "t" | Text file mode (may appear with
* | any of the key letters listed above except "b").
*
* *
* The global constant ARGF (also accessible as $<) provides an * The global constant ARGF (also accessible as $<) provides an
* IO-like stream which allows access to all files mentioned on the * IO-like stream which allows access to all files mentioned on the
* command line (or STDIN if no files are mentioned). ARGF provides * command line (or STDIN if no files are mentioned). ARGF#path and its alias
* the methods <code>#path</code> and <code>#filename</code> to access * ARGF#filename are provided to access the name of the file currently being
* the name of the file currently being read. * read.
* *
* == io/console * == io/console
* *
* The io/console extension provides methods for interacting with the * The io/console extension provides methods for interacting with the
* console. The console can be accessed from <code>IO.console</code> or * console. The console can be accessed from IO.console or the standard
* the standard input/output/error IO objects. * input/output/error IO objects.
* *
* Requiring io/console adds the following methods: * Requiring io/console adds the following methods:
* *