From 1da85070b0be2aa81ab68adf96ec10c99ba2baf1 Mon Sep 17 00:00:00 2001 From: drbrain Date: Fri, 4 Jan 2013 23:39:48 +0000 Subject: [PATCH] * doc/syntax/methods.rdoc: Added return values and scope sections, slightly modified from the original patch. Fixes #227 from github by Dave Brown. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38700 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 6 ++ doc/syntax/methods.rdoc | 126 +++++++++++++++++++++++++++++++++++----- 2 files changed, 119 insertions(+), 13 deletions(-) diff --git a/ChangeLog b/ChangeLog index c685405c4b..0a67b7e5f3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Sat Jan 5 08:38:27 2013 Eric Hodel + + * doc/syntax/methods.rdoc: Added return values and scope sections, + slightly modified from the original patch. Fixes #227 from github by + Dave Brown. + Sat Jan 5 08:21:41 2013 KOSAKI Motohiro * io.c (rb_cloexec_fcntl_dupfd): improve #ifdef condition. diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc index 8183d48612..b3233e647a 100644 --- a/doc/syntax/methods.rdoc +++ b/doc/syntax/methods.rdoc @@ -9,11 +9,64 @@ definition: A method definition consists of the +def+ keyword, a method name, the body of the method, then the +end+ keyword. When called the method will execute the -body of the method. This method returns 2. +body of the method. This method returns +2+. -A method may be defined on another object. You may define a "class -method" (a method that is called on the class, not an instance of the class) -like this: +== Return values + +By default, a method returns the last expression that was evaluated in the body +of the method. In the example above, the last (and only) expression evaluated +was the simple sum 1 + 1. The +return+ keyword can be used to +make it explicit that a method returns a value. + + def one_plus_one + return 1 + 1 + end + +It can also be used to make a method return before the last expression is +evaluated. + + def two_plus_two + return 2 + 2 + 1 + 1 # this expression is never evaluated + end + +== Scope + +The standard syntax to define a method: + + def my_method + # ... + end + +add the method to a class. You can define an instance method on a specific +class with the +class+ keyword: + + class C + def my_method + # ... + end + end + +In many languages, the +class+ keyword lets the compiler know that you're +creating a class. This is true in Ruby, too, the first time you use the +_class_ keyword: when it sees that you're _opening_ a class for +the first time, it creates it. When you open a class that already exists, Ruby +enables to you _extend_ it with new methods. You can even extend core +classes: + + class String + def hello + "Hello, world!" + end + end + + "".hello # returns "Hello, world!" + +However, This is somewhat risky due to namespace pollution so this ability is +best used sparingly. + +A method may be defined on another object. You may define a "class method" (a +method that is defined on the class, not an instance of the class) like this: class C def self.my_method @@ -21,16 +74,63 @@ like this: end end -You may also define methods this way on any object: +or a more concrete example: - string = "my string" - def string.my_method - # ... + class String + def self.hello + "Hello, world!" + end end -This is called a "singleton method". +my_method+ will only exist on this -string instance. Other strings will not have +my_method+. You may also -override existing methods on just one object this way. + String.hello # returns "Hello, world!" + +However, this is simply a special case of a greater syntactical power in Ruby, +the ability to add methods to any object. Classes are objects, so adding +class methods is simply adding methods to the Class object. + +The syntax for adding a method to an object is as follows: + + greeting = "Hello" + + def greeting.broaden + self + ", world!" + end + + greeting.broaden # returns "Hello, world!" + +_self_ is a keyword referring to the current object under consideration +by the compiler, which might make the use of +self+ in defining a class +method above a little clearer. Indeed, the example of adding a +hello+ +method to the class +String+ can be rewritten thus: + + def String.hello + "Hello, world!" + end + +A method defined like this is called a "singleton method". +broaden+ will only +exist on the string instance +greeting+. Other strings will not have +broaden+. + +== Overriding + +When Ruby encounters the +def+ keyword, it doesn't consider it an error if the +method already exists: it simply redefines it. This is called +_overriding_. Rather like extending core classes, this is a potentially +dangerous ability, and should be used sparingly because it can cause unexpected +results. For example, consider this irb session: + + >> "43".to_i + => 43 + >> class String + >> def to_i + >> 42 + >> end + >> end + => nil + >> "43".to_i + => 42 + +This will effectively sabotage any code which makes use of the method +String#to_i to parse numbers from strings. == Arguments @@ -42,8 +142,8 @@ A method may accept arguments. The argument list follows the method name: When called, the user of the +add_one+ method must provide an argument. The argument is a local variable in the method body. The method will then add one -to this argument and return the value. If given 1 this method will -return 2. +to this argument and return the value. If given +1+ this method will +return +2+. The parentheses around the arguments are optional: