summaryrefslogtreecommitdiff
path: root/doc/syntax
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-14 23:56:47 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-14 23:56:47 +0000
commitc3319d991ae708b1c209b7089f0c29fe404e47d0 (patch)
tree3cbde073d8b4c2ce522df214b4e2a8f7e291ff4f /doc/syntax
parent7cd5800f1263d467fc220f2770ce190f10165f07 (diff)
* doc/syntax/calling_methods.rdoc: Added document describing method
calls. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38816 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'doc/syntax')
-rw-r--r--doc/syntax/calling_methods.rdoc148
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/syntax/calling_methods.rdoc b/doc/syntax/calling_methods.rdoc
new file mode 100644
index 0000000..b6c88cd
--- /dev/null
+++ b/doc/syntax/calling_methods.rdoc
@@ -0,0 +1,148 @@
+= 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.
+