summaryrefslogtreecommitdiff
path: root/doc/syntax
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-12-17 02:26:15 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-12-17 02:26:15 +0000
commit29fd59347576ed1ef8fa18534b595b320a939db1 (patch)
tree74b3ad2b3fff9f6212cacfecc1a4e4b6debc31c7 /doc/syntax
parent810008293fd8ce3a9d3d62dcf2f2229b98c2bd49 (diff)
* doc/syntax.rdoc: Added syntax guide table of contents
* doc/syntax/exceptions.rdoc: Syntax guide for exceptions * doc/syntax/literals.rdoc: Syntax guide for literals * doc/syntax/methods.rdoc: Syntax guide for methods git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38419 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'doc/syntax')
-rw-r--r--doc/syntax/exceptions.rdoc79
-rw-r--r--doc/syntax/literals.rdoc283
-rw-r--r--doc/syntax/methods.rdoc130
3 files changed, 492 insertions, 0 deletions
diff --git a/doc/syntax/exceptions.rdoc b/doc/syntax/exceptions.rdoc
new file mode 100644
index 0000000..390eb86
--- /dev/null
+++ b/doc/syntax/exceptions.rdoc
@@ -0,0 +1,79 @@
+= Exception Handling
+
+Exceptions are rescued in a +begin+/+end+ block:
+
+ begin
+ # code that might raise
+ rescue
+ # handle exception
+ end
+
+If you are inside a method you do not need to use +begin+ or +end+ unless you
+wish to limit the scope of rescued exceptions:
+
+ def my_method
+ # ...
+ rescue
+ # ...
+ end
+
+The same is true for a +class+ or +module+.
+
+You can assign the exception to a local variable by using <tt>=>
+variable_name</tt> at the end of the +rescue+ line:
+
+ begin
+ # ...
+ rescue => exception
+ warn exception.message
+ raise # re-raise the current exception
+ end
+
+By default StandardError and its subclasses are rescued. You can rescue a
+specific set of exception classes (and their subclasses) by listing them after
++rescue+:
+
+ begin
+ # ...
+ rescue ArgumentError, NameError
+ # handle ArgumentError or NameError
+ end
+
+You may rescue different types of exceptions in different ways:
+
+ begin
+ # ...
+ rescue ArgumentError
+ # handle ArgumentError
+ rescue NameError
+ # handle NameError
+ rescue
+ # handle any StandardError
+ end
+
+The exception is matched to the rescue section starting at the top, and matches
+only once. If an ArgumentError is raised in the begin section it will not be
+handled in the StandardError section.
+
+To always run some code whether an exception was raised or not, use +ensure+:
+
+ begin
+ # ...
+ rescue
+ # ...
+ ensure
+ # this always runs
+ end
+
+You may also run some code when an exception is not raised:
+
+ begin
+ # ...
+ rescue
+ # ...
+ else
+ # this runs only when no exception was raised
+ ensure
+ # ...
+ end
+
diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc
new file mode 100644
index 0000000..9b54d39
--- /dev/null
+++ b/doc/syntax/literals.rdoc
@@ -0,0 +1,283 @@
+= Literals
+
+Literals create objects you can use in your program. Literals include:
+
+* Booleans and nil
+* Numbers
+* Strings
+* Symbols
+* Arrays
+* Hashes
+* Ranges
+* Regular Expressions
+* Procs
+
+== Booleans and nil
+
++nil+ and +false+ are both false values. +nil+ is sometimes used to indicate
+"no value" or "unknown" but evaluates to +false+ in conditional expressions.
+
++true+ is a true value. All objects except +nil+ and +false+ evaluate to a
+true value in conditional expressions.
+
+(There are also the constants +TRUE+, +FALSE+ and +NIL+, but the lowercase
+literal forms are preferred.)
+
+== Numbers
+
+You can write integers of any size as follows:
+
+ 1234
+ 1_234
+
+These numbers have the same value, 1,234. The underscore may be used to
+enhance readability for humans. You may place an underscore anywhere in the
+number.
+
+Floating point numbers may be written as follows:
+
+ 12.34
+ 1234e-2
+ 1.234E1
+
+These numbers have the same value, 12.34. You may use underscores in floating
+point numbers as well.
+
+You can also write numbers in hexadecimal, octal or binary formats. For
+hexadecimal numbers use a prefix of <tt>0x</tt>, for octal numbers use a
+prefix of <tt>0</tt>, for binary numbers use a prefix of <tt>0b</tt>. The
+alphabetic component of the number is not case-sensitive. Examples:
+
+ 0xaa
+ 0xAa
+ 0xAA
+ 0Xaa
+ 0XAa
+ 0XaA
+
+ 0252
+
+ 0b10101010
+ 0B10101010
+
+All these numbers have the same decimal value, 170. Like integers and floats
+you may use an underscore for readability.
+
+== Strings
+
+The most common way of writing strings is using <tt>"</tt>:
+
+ "This is a string".
+
+The string may be many lines long.
+
+Any internal <tt>"</tt> must be escaped:
+
+ "This string has a quote: \". As you can see, it is escaped"
+
+Double-quote strings allow escaped characters such as <tt>\n</tt> for newline,
+<tt>\t</tt> for tab, etc.
+
+Double-quote strings allow interpolation of other values using
+<tt>#{...}</tt>:
+
+ "One plus one is two: #{1 + 1}"
+
+Any expression may be placed inside the interpolated section, but it's best to
+keep the expression small for readability.
+
+Interpolation may be disabled by escaping the "#" character or using
+single-quote strings:
+
+ '#{1 + 1}' #=> "\#{1 + 1}"
+
+In addition to disabling interpolation, single-quoted strings also disable all
+escape sequences except for the single-quote (<tt>\'</tt>).
+
+You may also create strings using <tt>%</tt>:
+
+ %(1 + 1 is #{1 + 1}) #=> "1 + 1 is 2"
+
+There are two different types of <tt>%</tt> strings <tt>%q(...)</tt> behaves
+like a single-quote string (no interpolation or character escaping) while
+<tt>%Q</tt> behaves as a double-quote string. See Percent Strings below for
+more discussion of the syntax of percent strings.
+
+=== Here Documents
+
+If you are writing a large block of text you may use a "here document" or
+"heredoc":
+
+ expected_result = <<HEREDOC
+ This would contain specially formatted text.
+
+ That might span many lines
+ HEREDOC
+
+The heredoc starts on the line following <tt><<HEREDOC</tt> and ends with the
+next line that starts with <tt>HEREDOC</tt>. The result includes the ending
+newline.
+
+You may use any identifier with a heredoc, but all-uppercase identifiers are
+typically used.
+
+You may indent the ending identifier if you place a "-" after <tt><<</tt>:
+
+ def test_something
+ expected_result = <<-INDENTED_HEREDOC
+ This would contain specially formatted text.
+
+ That might span many lines
+ INDENTED_HEREDOC
+
+ # ...
+ end
+
+Note that the while the closing identifier may be indented, the content is
+always treated as if it is flush left. If you indent the content those spaces
+will appear in the output.
+
+A heredoc allows interpolation and escaped characters. You may disable
+interpolation and escaping by surrounding the opening identifier with single
+quotes:
+
+ expected_result = <<-'EXPECTED'
+ One plus one is #{1 + 1}
+ EXPECTED
+
+ p expected_result # prints: "One plus one is \#{1 + 1}\n"
+
+To call a method on a heredoc place it after the opening identifier:
+
+ expected_result = <<-EXPECTED.chomp
+ One plus one is #{1 + 1}
+ EXPECTED
+
+You may open multiple heredocs on the same line, but this can be difficult to
+read:
+
+ puts(<<-ONE, <<-TWO)
+ content for heredoc one
+ ONE
+ content for heredoc two
+ TWO
+
+== Symbols
+
+A Symbol represents a name inside the ruby interpreter. See Symbol for more
+details on what symbols are and when ruby creates them internally.
+
+You may reference a symbol using a colon: <tt>:my_symbol</tt>.
+
+You may also create symbols by interpolation:
+
+ :"my_symbol1"
+ :"my_symbol#{1 + 1}"
+
+Note that symbols are never garbage collected so be careful when referencing
+symbols using interpolation.
+
+Like strings, a single-quote may be used to disable interpolation:
+
+ :"my_symbol#{1 + 1}" #=> :"my_symbol\#{1 + 1}"
+
+When creating a Hash there is a special syntax for referencing a Symbol as
+well.
+
+== Arrays
+
+An array is created using the objects between <tt>[</tt> and <tt>]</tt>:
+
+ [1, 2, 3]
+
+You may place expressions inside the array:
+
+ [1, 1 + 1, 1 + 2]
+ [1, [1 + 1, [1 + 2]]]
+
+See Array for the methods you may use with an array.
+
+== Hashes
+
+A hash is created using key-value pairs between <tt>{</tt> and <tt>}</tt>:
+
+ { "a" => 1, "b" => 2 }
+
+Both the key and value may be any object.
+
+You can create a hash using symbol keys with the following syntax:
+
+ { a: 1, b: 2 }
+
+This same syntax is used for keyword arguments for a method.
+
+See Hash for the methods you may use with a hash.
+
+== Ranges
+
+A range represents an interval of values. The range may include or exclude
+its ending value.
+
+ (1..2) # includes its ending value
+ (1...2) # excludes its ending value
+
+You may create a range of any object. See the Range documentation for details
+on the methods you need to implement.
+
+== Regular Expressions
+
+A regular expression is created using "/":
+
+ /my regular expression/
+
+The regular expression may be followed by flags which adjust the matching
+behavior of the regular expression. The "i" flag makes the regular expression
+case-insensitive:
+
+ /my regular expression/i
+
+Interpolation may be used inside regular expressions along with escaped
+characters. Note that a regular expression may require additional escaped
+characters than a string.
+
+See Regexp for a description of the syntax of regular expressions.
+
+== Procs
+
+A proc can be created with <tt>-></tt>:
+
+ -> { 1 + 1 }
+
+Calling the above proc will give a result of <tt>2</tt>.
+
+You can require arguments for the proc as follows:
+
+ ->(v) { 1 + v }
+
+This proc will add one to its argument.
+
+== Percent Strings
+
+Besides <tt>%(...)</tt> which creates a String, The <tt>%</tt> may create
+other types of object. As with strings, an uppercase letter allows
+interpolation and escaped characters while a lowercase letter disables them.
+
+These are the types of percent strings in ruby:
+
+<tt>%i</tt> :: Array of Symbols
+<tt>%q</tt> :: String
+<tt>%r</tt> :: Regular Expression
+<tt>%s</tt> :: Symbol
+<tt>%w</tt> :: Array of Strings
+<tt>%x</tt> :: Backtick (capture subshell result)
+
+For the two array forms of percent string, if you wish to include a space in
+one of the array entries you must escape it with a "\\" character:
+
+ %w[one one-hundred\ one]
+ #=> ["one", "one-hundred one"]
+
+If you are using "(", "[", "{", "<" you must close it with ")", "]", "}", ">"
+respectively. You may use most other non-alphanumeric characters for percent
+string delimiters such as "%", "|", "^", etc.
+
diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
new file mode 100644
index 0000000..c207649
--- /dev/null
+++ b/doc/syntax/methods.rdoc
@@ -0,0 +1,130 @@
+= Methods
+
+Methods implement the functionality of your program. Here is a simple method
+definition:
+
+ def one_plus_one
+ 1 + 1
+ end
+
+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>.
+
+== Arguments
+
+A method may accept arguments. The argument list follows the method name:
+
+ def add_one(value)
+ value + 1
+ end
+
+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>.
+
+The parentheses around the arguments are optional:
+
+ def add_one value
+ value + 1
+ end
+
+Multiple arguments are separated by a comma:
+
+ def add_values(a, b)
+ a + b
+ end
+
+When called, the arguments must be provided in the exact order. In other
+words, the arguments are positional.
+
+=== Default Values
+
+Arguments may have default values:
+
+ def add_values(a, b = 1)
+ a + b
+ end
+
+The default value does not need to appear first, but the must be grouped
+together. This is ok:
+
+ def add_values(a = 1, b = 2, c)
+ a + b + c
+ end
+
+This will raise a SyntaxError:
+
+ def add_values(a = 1, b, c = 1)
+ a + b + c
+ end
+
+=== Keyword Arguments
+
+Keyword arguments are similar to positional arguments with default values:
+
+ def add_values first: 1, second: 2
+ first + second
+ end
+
+When calling a method with keyword arguments the arguments may appear in any
+order. If an unknown keyword argument is sent by the caller an ArgumentError
+is raised.
+
+When mixing keyword arguments and positional arguments, all positional
+arguments must appear before any keyword arguments.
+
+=== Array/Hash Argument
+
+Prefixing an argument with "*" causes any remaining arguments to be converted
+to an Array:
+
+ def gather_arguments(*arguments)
+ p arguments
+ end
+
+ gather_arguments 1, 2, 3 # prints [1, 2, 3]
+
+The array argument must be the last positional argument, it must appear before
+any keyword arguments.
+
+The array argument will capture a Hash as the last entry if a hash was sent by
+the caller after all positional arguments.
+
+ gather_arguments 1, a: 2 # prints [1, {:a=>2}]
+
+However, this only occurs if the method does not declare any keyword arguments.
+
+ def gather_arguments_keyword(*positional, keyword: nil)
+ p positinal: positional, keyword: keyword
+ end
+
+ gather_arguments_keyword 1, 2, three: 3
+ #=> raises: unknown keyword: three (ArgumentError)
+
+== Exception Handling
+
+Methods have an implied exception handling block so you do not need to use
++begin+ or +end+ to handle exceptions. This:
+
+ def my_method
+ begin
+ # code that may raise an exception
+ rescue
+ # handle exception
+ end
+ end
+
+May be written as:
+
+ def my_method
+ # code that may raise an exception
+ rescue
+ # handle exception
+ end
+
+If you wish to rescue an exception for only part of your method use +begin+ and
++end+. For more details see the page on {Exception
+Handling}[rdoc-ref:doc/syntax/exceptions.rdoc].
+