From e1b230d557bbf27641e94f037c3d1a125215c74c Mon Sep 17 00:00:00 2001 From: drbrain Date: Tue, 5 Jun 2012 00:37:08 +0000 Subject: * io.c: Edited documentation for IO and File open and new and Kernel#open for consistency and clarity. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@35914 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 5 + io.c | 368 ++++++++++++++++++++++++++++++++------------------------------ 2 files changed, 193 insertions(+), 180 deletions(-) diff --git a/ChangeLog b/ChangeLog index 38756748d4..44aebed34f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Jun 5 09:25:10 2012 Eric Hodel + + * 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 * win32/win32.c (rb_w32_sysinit): let the system not display the diff --git a/io.c b/io.c index bd9043bcdc..90e2657b3d 100644 --- a/io.c +++ b/io.c @@ -5933,27 +5933,29 @@ rb_open_file(int argc, VALUE *argv, VALUE io) * * With no associated block, File.open is a synonym for * File.new. If the optional code block is given, it will - * be passed the opened +file+ as an argument, and the File object will - * automatically be closed when the block terminates. In this instance, - * File.open returns the value of the block. + * be passed the opened +file+ as an argument and the File object will + * automatically be closed when the block terminates. The value of the block + * will be returned from File.open. * - * 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 * * call-seq: - * IO.open(fd, mode_string="r" [, opt]) -> io - * IO.open(fd, mode_string="r" [, opt]) {|io| block } -> obj - * - * With no associated block, IO.open is a synonym for IO.new. If - * the optional code block is given, it will be passed +io+ as an - * argument, and the IO object will automatically be closed when the block - * terminates. In this instance, IO.open returns the value of the block. + * IO.open(fd, mode="r" [, opt]) -> io + * IO.open(fd, mode="r" [, opt]) { |io| block } -> obj * - * See IO.new for a description of values for the +opt+ parameter. + * With no associated block, IO.open is a synonym for IO.new. If + * the optional code block is given, it will be passed +io+ as an argument, + * and the IO object will automatically be closed when the block terminates. + * In this instance, IO.open returns the value of the block. * + * See IO.new for a description of the +fd+, +mode+ and +opt+ parameters. */ static VALUE @@ -5976,7 +5978,6 @@ rb_io_s_open(int argc, VALUE *argv, VALUE klass) * Fixnum. * * IO.sysopen("testfile") #=> 3 - * */ static VALUE @@ -6024,72 +6025,58 @@ check_pipe_command(VALUE filename_or_command) /* * call-seq: - * open(path [, mode_enc [, perm]] [, opt]) -> io or nil - * open(path [, mode_enc [, perm]] [, opt]) {|io| block } -> obj - * - * Creates an IO object connected to the given stream, - * file, or subprocess. - * - * If path does not start with a pipe character - * (``|''), treat it as the name of a file to open using - * the specified mode (defaulting to ``r''). - * - * The mode_enc is - * either a string or an integer. If it is an integer, it must be - * bitwise-or of open(2) flags, such as File::RDWR or File::EXCL. - * If it is a string, it is either "mode", "mode:ext_enc", or - * "mode:ext_enc:int_enc". - * The mode is one of the following: - * - * r: read (default) - * w: write - * a: append - * - * The mode can be followed by "b" (means binary-mode), or "+" - * (means both reading and writing allowed) or both. - * If ext_enc (external encoding) is specified, - * 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 - * set using the integer third parameter. - * - * If a block is specified, it will be invoked with the - * File object as a parameter, and the file will be - * automatically closed when the block terminates. The call - * returns the value of the block. + * open(path [, mode [, perm]] [, opt]) -> io or nil + * open(path [, mode [, perm]] [, opt]) {|io| block } -> obj + * + * Creates an IO object connected to the given stream, file, or subprocess. + * + * If +path+ does not start with a pipe character (|), treat it + * as the name of a file to open using the specified mode (defaulting to + * "r"). + * + * The +mode+ is either a string or an integer. If it is an integer, it + * must be bitwise-or of open(2) flags, such as File::RDWR or File::EXCL. If + * it is a string, it is either "fmode", "fmode:ext_enc", or + * "fmode:ext_enc:int_enc". + * + * See the documentation of IO.new for full documentation of the +mode+ string + * directives. + * + * If a file is being created, its initial permissions may be set using the + * +perm+ parameter. See File.new and the open(2) and chmod(2) man pages for + * a description of permissions. + * + * If a block is specified, it will be invoked with the IO object as a + * parameter, and the IO will be automatically closed when the block + * terminates. The call returns the value of the block. + * + * If +path+ starts with a pipe character ("|"), a subprocess is + * created, connected to the caller by a pair of pipes. The returned IO + * object may be used to write to the standard input and read from the + * standard output of this subprocess. + * + * If the command following the pipe is a single minus sign + * ("|-"), Ruby forks, and this subprocess is connected to the + * parent. If the command is not "-", the subprocess runs the + * command. + * + * When the subprocess is ruby (opened via "|-"), the +open+ + * call returns +nil+. If a block is associated with the open call, that + * block will run twice --- once in the parent and once in the child. + * + * The block parameter will be an IO object in the parent and +nil+ in the + * child. The parent's +IO+ object will be connected to the child's $stdin + * and $stdout. The subprocess will be terminated at the end of the block. * - * If path starts with a pipe character, a subprocess is - * created, connected to the caller by a pair of pipes. The returned - * IO object may be used to write to the standard input - * and read from the standard output of this subprocess. If the command - * following the ``|'' is a single minus sign, Ruby forks, - * and this subprocess is connected to the parent. In the subprocess, - * the open call returns nil. If the command - * is not ``-'', the subprocess runs the command. If a - * block is associated with an open("|-") call, that block - * will be run twice---once in the parent and once in the child. The - * block parameter will be an IO object in the parent and - * nil in the child. The parent's IO object - * will be connected to the child's $stdin and - * $stdout. The subprocess will be terminated at the end - * of the block. + * === Examples + * + * Reading from "testfile": * * open("testfile") do |f| * print f.gets * end * - * produces: + * Produces: * * This is line one * @@ -6099,7 +6086,7 @@ check_pipe_command(VALUE filename_or_command) * print cmd.gets * cmd.close * - * produces: + * Produces: * * Wed Apr 9 08:56:31 CDT 2003 * @@ -6113,21 +6100,23 @@ check_pipe_command(VALUE filename_or_command) * puts "Got: #{f.gets}" * end * - * produces: + * Produces: * * 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| - * if f == nil - * puts "in Child" - * else + * open "|-" do |f| + * if f then + * # parent process * puts "Got: #{f.gets}" + * else + * # child process + * puts "in Child" * end * end * - * produces: + * Produces: * * Got: in Child */ @@ -6910,59 +6899,116 @@ rb_io_stdio_file(rb_io_t *fptr) * call-seq: * IO.new(fd [, mode] [, opt]) -> io * - * Returns a new IO object (a stream) for the given IO object or integer file - * descriptor and mode string. See also IO.sysopen and IO.for_fd. + * Returns a new IO object (a stream) for the given integer file descriptor + * +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. + * + * === Open 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 a string it must be in one of the following forms: * - * fd:: numeric file descriptor or IO object - * mode:: file mode. a string or an integer - * opt:: hash for specifying +mode+ by name. + * fmode + * fmode ":" ext_enc + * fmode ":" ext_enc ":" int_enc + * fmode ":" "BOM|UTF-*" * - * ==== Mode + * +fmode+ is an IO open mode string, +ext_enc+ is the external encoding for + * the IO and +int_enc+ is the internal encoding. * - * When mode is an integer it must be combination of the modes defined in - * File::Constants. + * ==== IO Open Mode * - * When mode is a string it must be in one of the following forms: - * - "fmode", - * - "fmode:extern", - * - "fmode:extern:intern". - * extern is the external encoding name for the IO. - * intern is the internal encoding. - * fmode must be a file open mode string. See the description of - * class IO for mode string directives. + * Ruby allows the following open modes: * - * When the mode of original IO is read only, the mode cannot be changed to - * be writable. Similarly, the mode cannot be changed from write only to - * readable. + * "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 * according to the platform. * - * ==== Options - * +opt+ can have the following keys + * === IO Encoding + * + * 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 :: * Same as +mode+ parameter - * :external_encoding :: + * + * :\external_encoding :: * External encoding for the IO. "-" is a synonym for the default external * encoding. - * :internal_encoding :: + * + * :\internal_encoding :: * Internal encoding for the IO. "-" is a synonym for the default internal * encoding. * * If the value is nil no conversion occurs. + * * :encoding :: * Specifies external and internal encodings as "extern:intern". + * * :textmode :: * If the value is truth value, same as "t" in argument +mode+. + * * :binmode :: * If the value is truth value, same as "b" in argument +mode+. + * * :autoclose :: * If the value is +false+, the +fd+ will be kept open after this IO * 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. * * === Example 1 @@ -6972,7 +7018,7 @@ rb_io_stdio_file(rb_io_t *fptr) * $stderr.puts "Hello" * a.puts "World" * - * produces: + * Produces: * * Hello * 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 [, perm]] [, opt]) -> file * - * Opens the file named by +filename+ according to +mode+ (default is "r") - * and returns a new File object. + * Opens the file named by +filename+ according to the given +mode+ and + * returns a new File object. * - * === Parameters - * - * See the description of class IO for a description of +mode+. The file - * mode may optionally be specified as a Fixnum by +or+-ing together the - * flags (O_RDONLY etc, again described under +IO+). - * - * Optional permission bits may be given in +perm+. These mode and - * permission bits are platform dependent; on Unix systems, see - * open(2) for details. + * See IO.new for a description of +mode+ and +opt+. * - * Optional +opt+ parameter is same as in IO.open. + * If a file is being created, permission bits may be given in +perm+. These + * mode and permission bits are platform dependent; on Unix systems, see + * open(2) and chmod(2) man pages for details. * * === Examples * @@ -11177,91 +11217,59 @@ argf_write(VALUE argf, VALUE str) */ /* - * Class IO 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 duplexed (that is, bidirectional), and * so may use more than one native operating system stream. * - * Many of the examples in this section use class File, - * the only standard subclass of IO. The two classes are - * closely associated. + * Many of the examples in this section use the File class, the only standard + * subclass of IO. The two classes are closely associated. Like the File + * class, the Socket library subclasses from IO (such as TCPSocket or + * UDPSocket). * - * As used in this section, portname may take any of the - * following forms. + * The Kernel#open method can create an IO (or File) object for these types + * of arguments: * * * A plain string represents a filename suitable for the underlying * operating system. * - * * A string starting with ``|'' indicates a subprocess. - * The remainder of the string following the ``|'' is + * * A string starting with "|" indicates a subprocess. + * The remainder of the string following the "|" is * invoked as a process with appropriate input/output channels * connected to it. * - * * A string equal to ``|-'' will create another Ruby + * * A string equal to "|-" will create another Ruby * 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 - * conventions if possible. For instance, on a Windows system the - * filename ``/gumby/ruby/test.rb'' will be opened as - * ``\gumby\ruby\test.rb''. When specifying a - * Windows-style filename in a Ruby string, remember to escape the - * backslashes: + * conventions if possible. For instance, on a Windows system the + * filename "/gumby/ruby/test.rb" will be opened as + * "\gumby\ruby\test.rb". When specifying a Windows-style + * filename in a Ruby string, remember to escape the backslashes: * - * "c:\\gumby\\ruby\\test.rb" + * "c:\\gumby\\ruby\\test.rb" * * Our examples here will use the Unix-style forward slashes; - * File::SEPARATOR can be used to get the - * platform-specific separator character. - * - * I/O ports may be opened in any one of several different modes, which - * are shown in this section as mode. 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"). - * + * File::ALT_SEPARATOR can be used to get the platform-specific separator + * character. * * The global constant ARGF (also accessible as $<) provides an * IO-like stream which allows access to all files mentioned on the - * command line (or STDIN if no files are mentioned). ARGF provides - * the methods #path and #filename to access - * the name of the file currently being read. + * command line (or STDIN if no files are mentioned). ARGF#path and its alias + * ARGF#filename are provided to access the name of the file currently being + * read. * * == io/console * * The io/console extension provides methods for interacting with the - * console. The console can be accessed from IO.console or - * the standard input/output/error IO objects. + * console. The console can be accessed from IO.console or the standard + * input/output/error IO objects. * * Requiring io/console adds the following methods: * -- cgit v1.2.3