ruby-changes:26764
From: drbrain <ko1@a...>
Date: Tue, 15 Jan 2013 08:57:59 +0900 (JST)
Subject: [ruby-changes:26764] drbrain:r38816 (trunk): * doc/syntax/calling_methods.rdoc: Added document describing method
drbrain 2013-01-15 08:56:47 +0900 (Tue, 15 Jan 2013) New Revision: 38816 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38816 Log: * doc/syntax/calling_methods.rdoc: Added document describing method calls. Added files: trunk/doc/syntax/calling_methods.rdoc Modified files: trunk/ChangeLog Index: doc/syntax/calling_methods.rdoc =================================================================== --- doc/syntax/calling_methods.rdoc (revision 0) +++ doc/syntax/calling_methods.rdoc (revision 38816) @@ -0,0 +1,148 @@ https://github.com/ruby/ruby/blob/trunk/doc/syntax/calling_methods.rdoc#L1 += Calling Methods + +Calling a method sends a message to an object so it can perform some work. + +In ruby you send a message to an object like this: + + my_method() + +Note that the parenthesis are optional: + + my_method + +Except when there is difference between using and omitting parentheses, this +document uses parenthesis when arguments are present to avoid confusion. + +== Receiver + ++self+ is the default receiver. If you don't specify any receiver +self+ will +be used. To specify a receiver use <code>.</code>: + + my_object.my_method + +This sends the +my_method+ message to +my_object+. Any object can be a +receiver but depending on the method's visibility sending a message may raise a +NoMethodError. + +== Positional Arguments + +The positional arguments for the message follow the method name: + + my_method(argument1) + +Multiple arguments are separated by a <code>,</code>: + + my_method(argument1, argument2) + +In many cases parenthesis are not necessary when sending a message: + + my_method argument1, argument2 + +However, parenthesis are necessary to avoid ambiguity. This will raise a +SyntaxError because ruby does not know which method argument3 should be sent +to: + + method_one argument1, method_two argument2, argument3 + +== Keyword Arguments + +Keyword arguments follow any positional arguments and are separated by commas +like positional arguments: + + my_method(positional1, keyword1: value1, keyword2: value2) + +Any keyword arguments not given will use the default value from the method +definition. If a keyword argument is given that the method did not list an +ArgumentError will be raised. + +== Block Argument + +The block argument is always last when sending a message to a method. A block +is sent to a method using <code>do ... end</code> or <code>{ ... }</code>: + + my_method do + # ... + end + +or: + + my_method { + # ... + end + +<code>do end</code> has lower precedence than <code>{ }</code> so: + + method_1 method_2 { + # ... + end + +Sends the block to +method_2+ while: + + method_1 method_2 do + # ... + end + +Sends the block to +method_1+. Note that in the first case if parentheses are +used the block is sent to +method_1+. + +A block will accept arguments from the method it was sent to. Arguments are +defined similar to the way a method defines arguments. The block's arguments +go in <code>| ... |</code> following the opening <code>do</code> or +<code>{</code>: + + my_method do |argument1, argument2| + # ... + end + +== Array to Arguments Conversion + +Given the following method: + + def my_method(argument1, argument2) + end + +You can turn an Array into an Argument list with <code>*</code> (or splat) +operator: + + arguments = [1, 2, 3] + my_method(*arguments) + +or: + + arguments = [2, 3] + my_method(1, *arguments) + +Both are equivalent to: + + my_method(1, 2, 3) + +If the method accepts keyword arguments the splat operator will convert a hash +at the end of the array into keyword arguments. + +If the number of objects in the Array do not match the number of arguments for +the method an ArgumentError will be raised. + +If the splat operator comes first in the call, parentheses must be used to +avoid a warning. + +== Proc to Block Conversion + +Given a method that use a block: + + def my_method + yield self + end + +You can convert a proc or lambda to a block argument with the <code>&</code> +operator: + + argument = proc { |a| puts "#{a.inspect} was yielded" } + + my_method(&argument) + +If the splat operator comes first in the call, parenthesis must be used to +avoid a warning. + +Unlike the splat operator described above the <code>&</code> has no commonly +recognized name. + Property changes on: doc/syntax/calling_methods.rdoc ___________________________________________________________________ Added: svn:eol-style + LF Index: ChangeLog =================================================================== --- ChangeLog (revision 38815) +++ ChangeLog (revision 38816) @@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Tue Jan 15 08:56:37 2013 Eric Hodel <drbrain@s...> + + * doc/syntax/calling_methods.rdoc: Added document describing method + calls. + Tue Jan 15 07:39:21 2013 Eric Hodel <drbrain@s...> * lib/rdoc/top_level.rb: Fixed extension trimming for page names in -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/