diff options
| -rw-r--r-- | doc/keywords.rdoc | 4 | ||||
| -rw-r--r-- | doc/syntax.rdoc | 2 | ||||
| -rw-r--r-- | doc/syntax/comments.rdoc | 37 | ||||
| -rw-r--r-- | doc/syntax/exceptions.rdoc | 9 | ||||
| -rw-r--r-- | enumerator.c | 8 | ||||
| -rw-r--r-- | proc.c | 16 | ||||
| -rw-r--r-- | process.c | 16 | ||||
| -rw-r--r-- | string.c | 51 |
8 files changed, 118 insertions, 25 deletions
diff --git a/doc/keywords.rdoc b/doc/keywords.rdoc index b2f72da272..a74126823d 100644 --- a/doc/keywords.rdoc +++ b/doc/keywords.rdoc @@ -115,7 +115,9 @@ retry:: handling}[rdoc-ref:syntax/exceptions.rdoc] return:: - Exits a method. See {methods}[rdoc-ref:syntax/methods.rdoc] + Exits a method. See {methods}[rdoc-ref:syntax/methods.rdoc]. + If met in top-level scope, immediately stops interpretation of + the current file. self:: The object the current method is attached to. See diff --git a/doc/syntax.rdoc b/doc/syntax.rdoc index fe0f98ce4c..2463c12a63 100644 --- a/doc/syntax.rdoc +++ b/doc/syntax.rdoc @@ -32,3 +32,5 @@ Refinements[rdoc-ref:syntax/refinements.rdoc] :: Miscellaneous[rdoc-ref:syntax/miscellaneous.rdoc] :: +alias+, +undef+, +BEGIN+, +END+ +Comments[rdoc-ref:syntax/comments.rdoc] :: + Line and block code comments diff --git a/doc/syntax/comments.rdoc b/doc/syntax/comments.rdoc new file mode 100644 index 0000000000..a07dd41494 --- /dev/null +++ b/doc/syntax/comments.rdoc @@ -0,0 +1,37 @@ += Code Comments + +Ruby has two types of comments: inline and block. + +Inline comments start with the <code>#</code> character and continue until the +end of the line: + + # On a separate line + class Foo # or at the end of the line + # can be indented + def bar + end + end + +Block comments start with <code>=begin</code> and end with <code>=end</code>. +Each should start on a separate line. + + =begin + This is + commented out + =end + + class Foo + end + + =begin some_tag + this works, too + =end + +<code>=begin</code> and <code>=end</code> can not be indented, so this is a +syntax error: + + class Foo + =begin + Will not work + =end + end diff --git a/doc/syntax/exceptions.rdoc b/doc/syntax/exceptions.rdoc index a2e75616fb..7fd58c83e8 100644 --- a/doc/syntax/exceptions.rdoc +++ b/doc/syntax/exceptions.rdoc @@ -17,7 +17,14 @@ wish to limit the scope of rescued exceptions: # ... end -The same is true for a +class+ or +module+. +The same is true for, +class+, +module+, and +block+: + + [0, 1, 2].map do |i| + 10 / i + rescue ZeroDivisionError + nil + end + #=> [nil, 10, 5] You can assign the exception to a local variable by using <tt>=> variable_name</tt> at the end of the +rescue+ line: diff --git a/enumerator.c b/enumerator.c index 18d06bb3e9..eee3a34e6b 100644 --- a/enumerator.c +++ b/enumerator.c @@ -295,7 +295,8 @@ proc_entry_ptr(VALUE proc_entry) * obj.enum_for(method = :each, *args){|*args| block} -> enum * * Creates a new Enumerator which will enumerate by calling +method+ on - * +obj+, passing +args+ if any. + * +obj+, passing +args+ if any. What was _yielded_ by method becomes + * values of enumerator. * * If a block is given, it will be used to calculate the size of * the enumerator without the need to iterate it (see Enumerator#size). @@ -314,6 +315,11 @@ proc_entry_ptr(VALUE proc_entry) * a = [1, 2, 3] * some_method(a.to_enum) * + * # String#split in block form is more memory-effective: + * very_large_string.to_enum(:split, "|") { |chunk| return chunk if chunk.include?('DATE') } + * # This could be rewritten more idiomatically with to_enum: + * very_large_string.to_enum(:split, "|").lazy.grep(/DATE/).first + * * It is typical to call to_enum when defining methods for * a generic Enumerable, in case no block is passed. * @@ -3291,6 +3291,8 @@ static VALUE rb_proc_compose_to_right(VALUE self, VALUE g); * f = proc {|x| x * x } * g = proc {|x| x + x } * p (f << g).call(2) #=> 16 + * + * See Proc#>> for detailed explanations. */ static VALUE proc_compose_to_left(VALUE self, VALUE g) @@ -3330,6 +3332,20 @@ rb_proc_compose_to_left(VALUE self, VALUE g) * f = proc {|x| x * x } * g = proc {|x| x + x } * p (f >> g).call(2) #=> 8 + * + * <i>g</i> could be other Proc, or Method, or any other object responding to + * +call+ method: + * + * class Parser + * def self.call(text) + * # ...some complicated parsing logic... + * end + * end + * + * pipeline = File.method(:read) >> Parser >> proc { |data| puts "data size: #{data.count}" } + * pipeline.call('data.json') + * + * See also Method#>> and Method#<<. */ static VALUE proc_compose_to_right(VALUE self, VALUE g) @@ -416,7 +416,19 @@ parent_redirect_close(int fd) /* * Document-module: Process * - * Module to handle processes. + * The module contains several groups of functionality for handling OS processes: + * + * * Low-level property introspection and management of current process, like + * Process.argv0, Process.pid; + * * Low-level introspection of other processes, like Process.getpgid, Process.getpriority; + * * Management of the current process: Process.abort, Process.exit, Process.daemon etc. + * (for convenience, most of those are also available as a global functions, + * and module functions of Kernel); + * * Creation and management of child processes: Process.fork, Process.spawn and + * related methods; + * * Management of low-level system clock: Process.times and Process.clock_gettime, + * which could be important for proper benchmarking and other elapsed + * time measurement tasks. */ static VALUE @@ -5127,7 +5139,7 @@ proc_getpriority(VALUE obj, VALUE which, VALUE who) * call-seq: * Process.setpriority(kind, integer, priority) -> 0 * - * See Process#getpriority. + * See Process.getpriority. * * Process.setpriority(Process::PRIO_USER, 0, 19) #=> 0 * Process.setpriority(Process::PRIO_PROCESS, 0, 19) #=> 0 @@ -8374,8 +8374,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary) /* * call-seq: - * str.each_line(separator=$/ [, getline_args]) {|substr| block } -> str - * str.each_line(separator=$/ [, getline_args]) -> an_enumerator + * str.each_line(separator=$/, chomp: false) {|substr| block } -> str + * str.each_line(separator=$/, chomp: false) -> an_enumerator * * Splits <i>str</i> using the supplied parameter as the record * separator (<code>$/</code> by default), passing each substring in @@ -8383,30 +8383,40 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary) * supplied, the string is split into paragraphs delimited by * multiple successive newlines. * - * See IO.readlines for details about getline_args. + * If +chomp+ is +true+, +separator+ will be removed from the end of each + * line. * * If no block is given, an enumerator is returned instead. * - * print "Example one\n" * "hello\nworld".each_line {|s| p s} - * print "Example two\n" + * # prints: + * # "hello\n" + * # "world" + * * "hello\nworld".each_line('l') {|s| p s} - * print "Example three\n" + * # prints: + * # "hel" + * # "l" + * # "o\nworl" + * # "d" + * * "hello\n\n\nworld".each_line('') {|s| p s} + * # prints + * # "hello\n\n" + * # "world" * - * <em>produces:</em> + * "hello\nworld".each_line(chomp: true) {|s| p s} + * # prints: + * # "hello" + * # "world" + * + * "hello\nworld".each_line('l', chomp: true) {|s| p s} + * # prints: + * # "he" + * # "" + * # "o\nwor" + * # "d" * - * Example one - * "hello\n" - * "world" - * Example two - * "hel" - * "l" - * "o\nworl" - * "d" - * Example three - * "hello\n\n" - * "world" */ static VALUE @@ -8418,13 +8428,14 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str) /* * call-seq: - * str.lines(separator=$/ [, getline_args]) -> an_array + * str.lines(separator=$/, chomp: false) -> an_array * * Returns an array of lines in <i>str</i> split using the supplied * record separator (<code>$/</code> by default). This is a * shorthand for <code>str.each_line(separator, getline_args).to_a</code>. * - * See IO.readlines for details about getline_args. + * If +chomp+ is +true+, +separator+ will be removed from the end of each + * line. * * "hello\nworld\n".lines #=> ["hello\n", "world\n"] * "hello world".lines(' ') #=> ["hello ", " ", "world"] |