U:RDoc::TopLevel[ iI" syntax/calling_methods.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[ÏS:RDoc::Markup::Heading: leveli: textI"Calling Methods;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"OCalling a method sends a message to an object so it can perform some work.;T@ o; ;[I"7In ruby you send a message to an object like this:;T@ o:RDoc::Markup::Verbatim;[I"my_method() ;T: @format0o; ;[I",Note that the parenthesis are optional:;T@ o;;[I"my_method ;T;0o; ;[I"RExcept when there is difference between using and omitting parentheses, this ;TI"Mdocument uses parenthesis when arguments are present to avoid confusion.;T@ o; ;[I"SThis section only covers calling methods. See also the {syntax documentation ;TI"8on defining methods}[rdoc-ref:syntax/methods.rdoc].;T@ S; ; i; I" Receiver;T@ o; ;[I"T+self+ is the default receiver. If you don't specify any receiver +self+ will ;TI"8be used. To specify a receiver use .:;T@ o;;[I"my_object.my_method ;T;0o; ;[I"MThis sends the +my_method+ message to +my_object+. Any object can be a ;TI"Ureceiver but depending on the method's visibility sending a message may raise a ;TI"NoMethodError.;T@ o; ;[I"RYou may use &. to designate a receiver, then +my_method+ is not ;TI"Tinvoked and the result is +nil+ when the receiver is +nil+. In that case, the ;TI"0arguments of +my_method+ are not evaluated.;T@ o; ;[I"RYou may also use :: to designate a receiver, but this is rarely ;TI"Qused due to the potential for confusion with :: for namespaces.;T@ S; ; i; I"Arguments;T@ o; ;[ I"OThere are three types of arguments when sending a message, the positional ;TI"Sarguments, keyword (or named) arguments and the block argument. Each message ;TI"Psent may use one, two or all types of arguments, but the arguments must be ;TI"supplied in this order.;T@ o; ;[I"PAll arguments in ruby are passed by reference and are not lazily evaluated.;T@ o; ;[I"4Each argument is separated by a ,:;T@ o;;[I"my_method(1, '2', :three) ;T;0o; ;[I"5Arguments may be an expression, a hash argument:;T@ o;;[I"'key' => value ;T;0o; ;[I"or a keyword argument:;T@ o;;[I"key: value ;T;0o; ;[I"MHash and keyword arguments must be contiguous and must appear after all ;TI",positional arguments, but may be mixed:;T@ o;;[I")my_method('a' => 1, b: 2, 'c' => 3) ;T;0S; ; i; I"Positional Arguments;T@ o; ;[I"EThe positional arguments for the message follow the method name:;T@ o;;[I"%my_method(argument1, argument2) ;T;0o; ;[I"IIn many cases, parenthesis are not necessary when sending a message:;T@ o;;[I"$my_method argument1, argument2 ;T;0o; ;[I"OHowever, parenthesis are necessary to avoid ambiguity. This will raise a ;TI"RSyntaxError because ruby does not know which method argument3 should be sent ;TI"to:;T@ o;;[I";method_one argument1, method_two argument2, argument3 ;T;0o; ;[I"LIf the method definition has a *argument extra positional ;TI"Harguments will be assigned to +argument+ in the method as an Array.;T@ o; ;[I"OIf the method definition doesn't include keyword arguments the keyword or ;TI"Lhash-type arguments are assigned as a single hash to the last argument:;T@ o;;[ I"def my_method(options) ;TI" p options ;TI" end ;TI" ;TI"9my_method('a' => 1, b: 2) # prints: {'a'=>1, :b=>2} ;T;0o; ;[I"LIf too many positional arguments are given, an ArgumentError is raised.;T@ S; ; i; I"!Default Positional Arguments;T@ o; ;[I"QWhen the method defines default arguments you do not need to supply all the ;TI"Parguments to the method. Ruby will fill in the missing arguments in-order.;T@ o; ;[I"QFirst we'll cover the simple case where the default arguments appear on the ;TI""right. Consider this method:;T@ o;;[I"'def my_method(a, b, c = 3, d = 4) ;TI" p [a, b, c, d] ;TI" end ;T;0o; ;[I"QHere +c+ and +d+ have default values which ruby will apply for you. If you ;TI",send only two arguments to this method:;T@ o;;[I"my_method(1, 2) ;T;0o; ;[I"7You will see ruby print [1, 2, 3, 4].;T@ o; ;[I"!If you send three arguments:;T@ o;;[I"my_method(1, 2, 5) ;T;0o; ;[I"6You will see ruby print [1, 2, 5, 4];T@ o; ;[I"[1, 2, 3, 4].;T@ o; ;[I"!If you send three arguments:;T@ o;;[I"my_method(1, 5, 6) ;T;0o; ;[I"7You will see ruby print [1, 5, 3, 6].;T@ o; ;[I"ODescribing this in words gets complicated and confusing. I'll describe it ;TI"%in variables and values instead.;T@ o; ;[ I"QFirst 1 is assigned to +a+, then 6 is assigned to ;TI"F+d+. This leaves only the arguments with default values. Since ;TI"Q5 has not been assigned to a value yet, it is given to +b+ and ;TI"2+c+ uses its default value of 3.;T@ S; ; i; I"Keyword Arguments;T@ o; ;[I"SKeyword arguments follow any positional arguments and are separated by commas ;TI"like positional arguments:;T@ o;;[I"@my_method(positional1, keyword1: value1, keyword2: value2) ;T;0o; ;[I"PAny keyword arguments not given will use the default value from the method ;TI"Qdefinition. If a keyword argument is given that the method did not list an ;TI""ArgumentError will be raised.;T@ S; ; i; I"Block Argument;T@ o; ;[I"MThe block argument sends a closure from the calling scope to the method.;T@ o; ;[I"TThe block argument is always last when sending a message to a method. A block ;TI"Ois sent to a method using do ... end or { ... }:;T@ o;;[I"my_method do ;TI" # ... ;TI" end ;T;0o; ;[I"or:;T@ o;;[I"my_method { ;TI" # ... ;TI"} ;T;0o; ;[I"Gdo end has lower precedence than { } so:;T@ o;;[I"method_1 method_2 { ;TI" # ... ;TI"} ;T;0o; ;[I")Sends the block to +method_2+ while:;T@ o;;[I"method_1 method_2 do ;TI" # ... ;TI" end ;T;0o; ;[I"TSends the block to +method_1+. Note that in the first case if parentheses are ;TI"*used the block is sent to +method_1+.;T@ o; ;[ I"RA block will accept arguments from the method it was sent to. Arguments are ;TI"Sdefined similar to the way a method defines arguments. The block's arguments ;TI"Igo in | ... | following the opening do or ;TI"{:;T@ o;;[I")my_method do |argument1, argument2| ;TI" # ... ;TI" end ;T;0S; ; i ; I"Block Local Arguments;T@ o; ;[I"SYou may also declare block-local arguments to a block using ; in ;TI"Mthe block arguments list. Assigning to a block-local argument will not ;TI"Foverride local arguments outside the block in the caller's scope:;T@ o;;[I"def my_method ;TI" yield self ;TI" end ;TI" ;TI"place = "world" ;TI" ;TI"my_method do |obj; place| ;TI" place = "block" ;TI", puts "hello #{obj} this is #{place}" ;TI" end ;TI" ;TI"puts "place is: #{place}" ;T;0o; ;[I"This prints:;T@ o;;[I"hello main this is block ;TI"place is world ;T;0o; ;[I"NSo the +place+ variable in the block is not the same +place+ variable as ;TI"Poutside the block. Removing ; place from the block arguments ;TI"gives this result:;T@ o;;[I"hello main this is block ;TI"place is block ;T;0S; ; i; I""Array to Arguments Conversion;T@ o; ;[I" Given the following method:;T@ o;;[I"4def my_method(argument1, argument2, argument3) ;TI" end ;T;0o; ;[I"PYou can turn an Array into an argument list with * (or splat) ;TI"operator:;T@ o;;[I"arguments = [1, 2, 3] ;TI"my_method(*arguments) ;T;0o; ;[I"or:;T@ o;;[I"arguments = [2, 3] ;TI"my_method(1, *arguments) ;T;0o; ;[I"Both are equivalent to:;T@ o;;[I"my_method(1, 2, 3) ;T;0o; ;[I"PIf the method accepts keyword arguments, the splat operator will convert a ;TI"9hash at the end of the array into keyword arguments:;T@ o;;[ I"def my_method(a, b, c: 3) ;TI" end ;TI" ;TI""arguments = [1, 2, { c: 4 }] ;TI"my_method(*arguments) ;T;0o; ;[I"RYou may also use the ** (described next) to convert a Hash into ;TI"keyword arguments.;T@ o; ;[I"TIf the number of objects in the Array do not match the number of arguments for ;TI"1the method, an ArgumentError will be raised.;T@ o; ;[I"PIf the splat operator comes first in the call, parentheses must be used to ;TI"avoid a warning.;T@ S; ; i; I")Hash to Keyword Arguments Conversion;T@ o; ;[I" Given the following method:;T@ o;;[I"2def my_method(first: 1, second: 2, third: 3) ;TI" end ;T;0o; ;[I"RYou can turn a Hash into keyword arguments with the ** operator:;T@ o;;[I"3arguments = { first: 3, second: 4, third: 5 } ;TI"my_method(**arguments) ;T;0o; ;[I"or:;T@ o;;[I")arguments = { first: 3, second: 4 } ;TI"&my_method(third: 5, **arguments) ;T;0o; ;[I"Both are equivalent to:;T@ o;;[I".my_method(first: 3, second: 4, third: 5) ;T;0o; ;[I"OIf the method definition uses ** to gather arbitrary keyword ;TI"*:;T@ o;;[ I"def my_method(*a, **kw) ;TI"$ p arguments: a, keywords: kw ;TI" end ;TI" ;TI"(my_method(1, 2, '3' => 4, five: 6) ;T;0o; ;[I" Prints:;T@ o;;[I";{:arguments=>[1, 2, {"3"=>4}], :keywords=>{:five=>6}} ;T;0o; ;[I"TUnlike the splat operator described above, the ** operator has no ;TI"commonly recognized name.;T@ S; ; i; I"Proc to Block Conversion;T@ o; ;[I"%Given a method that use a block:;T@ o;;[I"def my_method ;TI" yield self ;TI" end ;T;0o; ;[I"RYou can convert a proc or lambda to a block argument with the & ;TI"operator:;T@ o;;[I"=argument = proc { |a| puts "#{a.inspect} was yielded" } ;TI" ;TI"my_method(&argument) ;T;0o; ;[I"PIf the splat operator comes first in the call, parenthesis must be used to ;TI"avoid a warning.;T@ o; ;[I"SUnlike the splat operator described above, the & operator has no ;TI"commonly recognized name.;T@ S; ; i; I"Method Lookup;T@ o; ;[I"TWhen you send a message, Ruby looks up the method that matches the name of the ;TI"Tmessage for the receiver. Methods are stored in classes and modules so method ;TI"4lookup walks these, not the objects themselves.;T@ o; ;[I"OHere is the order of method lookup for the receiver's class or module +R+:;T@ o:RDoc::Markup::List: @type: BULLET: @items[o:RDoc::Markup::ListItem: @label0;[o; ;[I"2The prepended modules of +R+ in reverse order;To;;0;[o; ;[I"!For a matching method in +R+;To;;0;[o; ;[I"1The included modules of +R+ in reverse order;T@ o; ;[I"QIf +R+ is a class with a superclass, this is repeated with +R+'s superclass ;TI"until a method is found.;T@ o; ;[I"/Once a match is found method lookup stops.;T@ o; ;[I"KIf no match is found this repeats from the beginning, but looking for ;TI"S+method_missing+. The default +method_missing+ is BasicObject#method_missing ;TI"+which raises a NameError when invoked.;T@ o; ;[I"UIf refinements (an experimental feature) are active, the method lookup changes. ;TI"OSee the {refinements documentation}[rdoc-ref:syntax/refinements.rdoc] for ;TI" details.;T: @file@:0@omit_headings_from_table_of_contents_below0