summaryrefslogtreecommitdiff
path: root/doc/syntax
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-15 04:33:28 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-15 04:33:28 +0000
commit68b072bfbabdcd78b4d7980c15ab83163ecbacd3 (patch)
tree3dfa99c599b64a1d73a54714fd5e38a62caa2989 /doc/syntax
parent108f3acbe41ec2de5164109ee80377fe31951e08 (diff)
* doc/syntax/methods.rdoc (Method Names): Added method names including
operator methods. * doc/syntax/methods.rdoc (Return Values): Added note that assignment methods ignore return values. * doc/syntax/precedence.rdoc: Added document describing precedence. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38825 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'doc/syntax')
-rw-r--r--doc/syntax/methods.rdoc83
-rw-r--r--doc/syntax/precedence.rdoc60
2 files changed, 142 insertions, 1 deletions
diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
index a86576c..15f1ef0 100644
--- a/doc/syntax/methods.rdoc
+++ b/doc/syntax/methods.rdoc
@@ -11,7 +11,79 @@ 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+.
-== Return values
+== Method Names
+
+Method names may be one of the operators or must start a letter or a character
+with the eight bit set. Typically method names are US-ASCII compatible since
+the keys to type them exist on all keyboards.
+
+(Ruby programs must be written in a US-ASCII-compatible character set. In
+such character sets if the eight bit is set it indicates an extended
+character. Ruby allows method names and other identifiers to contain such
+characters.)
+
+Method names may contain letters, numbers, an <code>_</code> (underscore or
+low line) or a character with the eight bit set.
+
+Method names may end with a <code>!</code> (bang or exclamation mark), a
+<code>?</code> (question mark) or <code>=</code> equals sign.
+
+In the ruby core library when a method ends with a bang it indicates there is
+a non-bang method that has does not modify the receiver. This is typically
+true for the standard library but does not hold true for other ruby libraries.
+
+Methods that end with a question mark do not always return just +true+ or
++false+. Often they will may return an object to indicate a true value (or
+"truthy" value).
+
+Methods that end with an equals sign indicate an assignment method. For
+assignment methods the return value is ignored, the arguments are returned
+instead.
+
+These are method names for the various ruby operators. Each of these
+operators accept only one argument. Following the operator is the typical
+use or name of the operator. Creating an alternate meaning for the operator
+may lead to confusion as the user expects plus to add things, minus to
+subtract things, etc. Additionally, you cannot alter the precedence of the
+operators.
+
+<code>+</code> :: add
+<code>-</code> :: subtract
+<code>*</code> :: multiply
+<code>**</code> :: power
+<code>/</code> :: divide
+<code>%</code> :: modulus division, String#%
+<code>&</code> :: AND
+<code>^</code> :: XOR (exclusive OR)
+<code>>></code> :: right-shift
+<code><<</code> :: left-shift, append
+<code>==</code> :: equal
+<code>!=</code> :: not equal
+<code>===</code> :: case equality. See Object#===
+<code>=~</code> :: pattern match. (Not just for regular expressions)
+<code>!~</code> :: does not match
+<code><=></code> :: comparison aka spaceship operator. See Comparable
+<code><</code> :: less-than
+<code><=</code> :: less-than or equal
+<code>></code> :: greater-than
+<code>>=</code> :: greater-than or equal
+
+To define unary methods minus, plus, tilde and not (<code>!</code>) follow the
+operator with an <code>@</code> as in <code>+@</code> or <code>!@<code>:
+
+ class C
+ def -@
+ puts "you inverted this object"
+ end
+ end
+
+ obj = C.new
+
+ -obj # prints "you inverted this object"
+
+Unary methods accept zero arguments.
+
+== 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
@@ -30,6 +102,15 @@ evaluated.
1 + 1 # this expression is never evaluated
end
+Note that for assignment methods the return value will always be ignored.
+Instead the argument will be returned:
+
+ def a=(value)
+ return 1 + value
+ end
+
+ p(a = 5) # prints 5
+
== Scope
The standard syntax to define a method:
diff --git a/doc/syntax/precedence.rdoc b/doc/syntax/precedence.rdoc
new file mode 100644
index 0000000..515626c
--- /dev/null
+++ b/doc/syntax/precedence.rdoc
@@ -0,0 +1,60 @@
+= Precedence
+
+From highest to lowest, this is the precedence table for ruby. High precedence
+operations happen before low precedence operations.
+
+ !, ~, unary +
+
+ **
+
+ unary -
+
+ *, /, %
+
+ +, -
+
+ <<, >>
+
+ &
+
+ |, ^
+
+ >, >=, <, <=
+
+ <=>, ==, ===, !=, =~, !~
+
+ &&
+
+ ||
+
+ .., ...
+
+ ?, :
+
+ modifier-rescue
+
+ =, +=, -=, etc.
+
+ defined?
+
+ not
+
+ or, and
+
+ modifier-if, modifier-unless, modifier-while, modifier-until
+
+ { } blocks
+
+Unary <code>+</code> and unary <code>-</code> are for <code>+1</code>,
+<code>-1</code> or <code>-(a + b)</code>.
+
+Modifier-if, modifier-unless, etc. are for the modifier versions of those
+keywords. For example, this is a modifier-unless expression:
+
+ a += 1 unless a.zero?
+
+<code>{ ... }</code> blocks have priority below all listed operations, but
+<code>do ... end</code> blocks have lower priority.
+
+All other words in the precedence table above are keywords.
+