summaryrefslogtreecommitdiff
path: root/doc/syntax
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-04 23:39:48 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-04 23:39:48 +0000
commit1da85070b0be2aa81ab68adf96ec10c99ba2baf1 (patch)
treec4656711d0f757dbb82dc5513cb21b6cfdd9527d /doc/syntax
parent753f68cf20e1492cf980106027dd1f0969d546f2 (diff)
* 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
Diffstat (limited to 'doc/syntax')
-rw-r--r--doc/syntax/methods.rdoc126
1 files changed, 113 insertions, 13 deletions
diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
index 8183d48..b3233e6 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 <tt>2</tt>.
+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 <code>1 + 1</code>. 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
+<code>String#to_i</code> 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 <tt>1</tt> this method will
-return <tt>2</tt>.
+to this argument and return the value. If given +1+ this method will
+return +2+.
The parentheses around the arguments are optional: