ruby-changes:9479
From: yugui <ko1@a...>
Date: Thu, 25 Dec 2008 18:54:43 +0900 (JST)
Subject: [ruby-changes:9479] Ruby:r21017 (ruby_1_9_1): merges r20946 from trunk into ruby_1_9_1.
yugui 2008-12-25 18:54:17 +0900 (Thu, 25 Dec 2008) New Revision: 21017 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=21017 Log: merges r20946 from trunk into ruby_1_9_1. * io.c: rdoc for File::open and 1.9 feature in file modes. * transcode.c: rdoc for String#encode Modified files: branches/ruby_1_9_1/ChangeLog branches/ruby_1_9_1/io.c branches/ruby_1_9_1/transcode.c Index: ruby_1_9_1/ChangeLog =================================================================== --- ruby_1_9_1/ChangeLog (revision 21016) +++ ruby_1_9_1/ChangeLog (revision 21017) @@ -1,3 +1,9 @@ +Tue Dec 23 20:28:28 2008 Yuki Sonoda (Yugui) <yugui@y...> + + * io.c: rdoc for File::open and 1.9 feature in file modes. + + * transcode.c: rdoc for String#encode + Tue Dec 23 19:51:24 2008 Nobuyoshi Nakada <nobu@r...> * win32/win32.c (rb_w32_spawn): deals with quoted commands. Index: ruby_1_9_1/io.c =================================================================== --- ruby_1_9_1/io.c (revision 21016) +++ ruby_1_9_1/io.c (revision 21017) @@ -4887,8 +4887,27 @@ return io; } + /* + * Document-method: File::open + * * call-seq: + * File.open(filename, mode="r" [, opt]) => file + * File.open(filename [, mode [, perm]] [, opt]) => file + * File.open(filename, mode="r" [, opt]) {|file| block } => obj + * File.open(filename [, mode [, perm]] [, opt]) {|file| block } => obj + * + * With no associated block, <code>open</code> is a synonym for + * <code>File.new</code>. If the optional code block is given, it will + * be passed <i>file</i> as an argument, and the File object will + * automatically be closed when the block terminates. In this instance, + * <code>File.open</code> returns the value of the block. + */ + +/* + * Document-method: IO::open + * + * call-seq: * IO.open(fd, mode_string="r" [, opt] ) => io * IO.open(fd, mode_string="r" [, opt] ) {|io| block } => obj * @@ -5788,7 +5807,49 @@ * <code>IO</code> object or integer file descriptor and mode * string. See also <code>IO#fileno</code> and * <code>IO.for_fd</code>. + * + * === Parameters + * fd:: numeric file descriptor + * mode:: file mode. a string or an integer + * opt:: hash for specifiying mode by name. * + * ==== Mode + * When <code>mode</code> is an integer it must be combination of + * the modes defined in <code>File::Constants</code>. + * + * When <code>mode</code> is a string it must be in one of the + * following forms: + * - "fmode", + * - "fmode:extern", + * - "fmode:extern:intern". + * <code>extern</code> is the external encoding name for the IO. + * <code>intern</code> is the internal encoding. + * <code>fmode</code> must be combination of the directives. See + * the description of class +IO+ for a description of the directives. + * + * ==== Options + * <code>opt</code> can have the following keys + * :mode :: + * same as <code>mode</code> parameter + * :external_encoding :: + * external encoding for the IO. "-" is a + * synonym for the default external 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 "b" in argument <code>mode</code>. + * :binmode :: + * If the value is truth value, same as "t" in argument <code>mode</code>. + * + * Also <code>opt</code> can have same keys in <code>String#encode</code> for + * controlling conversion between the external encoding and the internal encoding. + * + * === Example1 + * * puts IO.new($stdout).fileno # => 1 * * a = IO.new(2,"w") # '2' is standard error @@ -5799,6 +5860,16 @@ * * Hello * World + * + * === Example2 + * io = IO.new(2, mode: 'w:UTF-16LE', cr_newline: true) + * io.puts "Hello, World!" + * + * io = IO.new(2, mode: 'w', cr_newline: true, external_encoding: Encoding::UTF_16LE) + * io.puts "Hello, World!" + * + * both of aboves print "Hello, World!" in UTF-16LE to standard error output with + * converting EOL generated by <code>puts</code> to CR. */ static VALUE @@ -5835,23 +5906,29 @@ return io; } - /* * call-seq: * 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 - * <code>File</code> object. 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 - * <code>open(2)</code> for details. + * <code>File</code> 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 <code>open(2)</code> for details. + * + * Optional _opt_ parameter is same as in <code.IO.open</code>. + * + * === Examples + * * f = File.new("testfile", "r") * f = File.new("newfile", "w+") * f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644) @@ -5876,24 +5953,6 @@ return io; } -/* - * call-seq: - * IO.new(fd, mode_string [, opt]) => io - * - * Returns a new <code>IO</code> object (a stream) for the given - * integer file descriptor and mode string. See also - * <code>IO#fileno</code> and <code>IO.for_fd</code>. - * - * a = IO.new(2,"w") # '2' is standard error - * $stderr.puts "Hello" - * a.puts "World" - * - * <em>produces:</em> - * - * Hello - * World - */ - static VALUE rb_io_s_new(int argc, VALUE *argv, VALUE klass) { @@ -8341,8 +8400,11 @@ * | otherwise creates a new file for reading and * | writing. * -----+-------------------------------------------------------- - * "b" | (DOS/Windows only) Binary file mode (may appear with + * "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"). @@ -8405,6 +8467,11 @@ rb_cIO = rb_define_class("IO", rb_cObject); rb_include_module(rb_cIO, rb_mEnumerable); +#if 0 + /* This is necessary only for forcing rdoc handle File::open */ + rb_define_singleton_method(rb_cFile, "open", rb_io_s_open, -1); +#endif + rb_define_alloc_func(rb_cIO, io_alloc); rb_define_singleton_method(rb_cIO, "new", rb_io_s_new, -1); rb_define_singleton_method(rb_cIO, "open", rb_io_s_open, -1); Index: ruby_1_9_1/transcode.c =================================================================== --- ruby_1_9_1/transcode.c (revision 21016) +++ ruby_1_9_1/transcode.c (revision 21017) @@ -2566,10 +2566,33 @@ * to encoding +encoding+. * The second form returns a copy of <i>str</i> transcoded * from src_encoding to dst_encoding. - * The options Hash gives details for conversion. Details - * to be added. + * The options Hash gives details for conversion. * The last form returns a copy of <i>str</i> transcoded to * <code>Encoding.default_internal</code>. + * + * === options + * A hash <code>options</code> can have the following keys: + * :invalid :: + * If the value is <code>:replace</code> <code>#encode</code> replaces + * invalid characters in <code>str</code> with the replacement character. + * :undef :: + * If the value is <code>:replace</code> <code>#encode</code> replaces + * characters which are undefined in the destination character set with + * the replacement character. + * :replace :: + * sets the replacement character to the value. + * :xml :: + * The value must be <code>:text</code> or <code>:attr</code>. + * If the value is <code>:text</code> <code>#encode</code> replaces + * undefined characters with its numerical character reference. + * If the value is <code>:attr</code> <code>#encode</code> also quotes + * the replacement result. + * :cr_newline :: + * replaces EOL with CR. + * :crlf_newline :: + * replaces EOL with CR LF. + * :universal_newline :: + * replaces EOL with LF. */ static VALUE -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/