Skip to content
This repository has been archived by the owner on Oct 13, 2020. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
first round of explanations
  • Loading branch information
mislav committed Aug 22, 2010
1 parent 9f930ee commit 4eaa790
Show file tree
Hide file tree
Showing 22 changed files with 84 additions and 3 deletions.
14 changes: 14 additions & 0 deletions explanations/attr_accessor.md
@@ -0,0 +1,14 @@
## Attribute accessor

This method is used to expose instance variables (which otherwise can't be accessed from outside the instance) by generating "accessor" methods. Two simple methods are generated; one for reading that returns the instance variable of the same name, the other for writing that assigns a new value to the instance variable. For instance, if `attr_accessor :programming_language` was used in a "Person" class, it would expose the attribute on all its instances:

person.programming_language
#=> nil

person.programming_language = "Ruby"
person.programming_language
#=> "Ruby"

# attribute value is stored in "@programming_language"
# instance variable on the "person" object

3 changes: 3 additions & 0 deletions explanations/attr_reader.md
@@ -0,0 +1,3 @@
## Attribute reader

This method is used to expose instance variables (which otherwise can't be accessed from outside the instance) by generating a "reader" method. The generated method simply returns the value of an instance variable of the same name.
3 changes: 3 additions & 0 deletions explanations/attr_writer.md
@@ -0,0 +1,3 @@
## Attribute writer

This method is used to easily enable writing to instance variables (which otherwise can't be accessed from outside the instance) by generating a "writer" method. The generated method takes a single argument and writes the given value to the instance variable of the same name.
2 changes: 1 addition & 1 deletion explanations/class.md
@@ -1,3 +1,3 @@
## Class definition

A class definition.
The `class` keyword defines a named class. Classes are objects which group together methods that will be properties of objects instantiated from the class. Every object in Ruby is an instance of a class; e.g. numbers are instances of the "Numeric" class and strings of the "String" class. The same way they are created, classes can be reopened and new methods can be added to them; when that happens, newly added methods are instantly available on all existing objects of that class.
2 changes: 1 addition & 1 deletion explanations/class_inheritance.md
@@ -1,3 +1,3 @@
## Class inheritance

Some inheritance right here.
A class can inherit from another class; this is denoted by the `<` sign. The new class becomes a "subclass" of its parent "superclass" and inherits all methods from the parent class. In the new class, new methods can be added and inherited methods overridden; nothing of this will affect the superclass.
3 changes: 3 additions & 0 deletions explanations/class_initializer.md
@@ -0,0 +1,3 @@
## Class initializer

The "initialize" method, if defined, is the method that always gets invoked automatically on each new instance of the class. It is used to initialize instance variables and process given arguments, if any. For example, if a "person" object is instantiated with `Person.new("Ruby")`, the "initialize" method would get called with a single argument with a value of "Ruby". By default, all arguments that `new` was called with are forwarded to the "initialize" method of the new instance.
3 changes: 3 additions & 0 deletions explanations/class_method.md
@@ -0,0 +1,3 @@
## Class method

A *class method*, denoted by the "self." prefix on its name, is a method that can be called directly on a class or module without needing to create an instance of that class. This is opposed to regular *instance methods* which are only available on instances of a class. Class methods are used to implement behavior that this class is responsible for, but which isn't tied to any particular instance.
3 changes: 3 additions & 0 deletions explanations/class_self.md
@@ -0,0 +1,3 @@
## Singleton class access

This construct is a way to enter the scope of the current singleton class, otherwise known as "metaclass". The concept of a singleton class is somewhat advanced; accessing it is often referred to as "metaprogramming". In simple terms, every class and module in Ruby has its singleton class, and defining instance methods on the singleton class actually defines *class* methods on the corresponding class/module. The `class << self` construct is most commonly used to define class methods without having to use the "self." prefix which would otherwise be required.
5 changes: 5 additions & 0 deletions explanations/constant.md
@@ -0,0 +1,5 @@
## Constant

A *constant* is a pointer to an object, just like a variable. Their names start with an uppercase letter, and they are often all in uppercase. The difference from a variable is that a constant shouldn't be reassigned to another object; Ruby will allow it but issue an "already initialized constant" warning. Constants are usually used to hold bits of hardcoded data used in a namespace, e.g. `HTTPVersion = "1.1"` can be found in "Net::HTTP" and is used internally when communicating over HTTP.

Another thing that might not be immediately obvious is that names of classes and modules are constants, too; they start with an uppercase letter. These are regular constants which point to an object that represents the class or module. For instance, there are three constants in the expression "Net::HTTP::HTTPVersion": the first one points to the "Net" module, the second one to the "HTTP" class inside the first module, and the third one points to the string "1.1" (as mentioned above).
3 changes: 3 additions & 0 deletions explanations/include.md
@@ -0,0 +1,3 @@
## Module include

The `include` method allows a module to be included in a class or another module. The module being included is commonly referred to as "mixin", because its methods are being *mixed-in* with existing methods in the current class/module. Multiple modules can be included in the same object, and even if new methods are defined in the included model afterwards, these methods will immediately be available in every object where this module was mixed-in.
5 changes: 5 additions & 0 deletions explanations/method.md
@@ -0,0 +1,5 @@
## Method definition

A method is a function defined and available on an object. A method is a block of code that can receive zero or more arguments, execute and return a value. Most commonly, methods are defined inside classes and modules; they define properties that all instances of the same class share. The code inside a method has access to *instance variables* of the current object.

Unless an explicit `return` statement is used, all methods return the value of their last expression when they run. If the method is defined with a list of arguments, the caller has to pass the required number of arguments when calling the method.
3 changes: 3 additions & 0 deletions explanations/method_bang.md
@@ -0,0 +1,3 @@
## "Bang" method

A method that ends with an exclamation point (`!`) is otherwise known as a "bang" method. These methods are like any other methods, but since the exclamation point distinguishes them from other method calls, they are are most commonly used for destructive operations that either change the receiving object or trigger an irreversible operation. Sometimes a regular method will have its "bang" counterpart; for instance a lot methods on Array objects have counterparts with an exclamation point in the name, indicating the second method *changes* the array object instead of returning a new one; e.g. `array.reverse` returns a new array which is the reversed copy of the original, while `array.reverse!` changes the original array without making a copy.
7 changes: 7 additions & 0 deletions explanations/method_block.md
@@ -0,0 +1,7 @@
## Block method argument

Every method in Ruby can take a "block", and this method indicates it explicitly by declaring a named block argument. This special argument is denoted by the `&` sign before its name, must come at the last place in the arguments list, and can only be one per method. The "block" argument is always optional; if not given it will be nil.

A "block" in Ruby is simply some Ruby code grouped together, delimited by `do ... end` keywords or, alternatively, curly brackets (`{ ... }`) following a method call. Like methods, blocks can receive arguments; the argument list is specified with pipe symbols (e.g. `|a, b, c|`) at the beginning of the block.

At execution time, the method can check if it received the block. This is done with a special language construct `block_given?`. The block can be invoked with its `call` method, e.g. `block.call(1, 2, 3)`. The values supplied will be values for block arguments, if any.
3 changes: 3 additions & 0 deletions explanations/method_default_arguments.md
@@ -0,0 +1,3 @@
## Default argument values

A method can be defined with default argument values, denoted by assignment syntax in the list of arguments. Arguments with default values must come *after* regular arguments and are commonly referred to as "optional arguments".
3 changes: 3 additions & 0 deletions explanations/method_predicate.md
@@ -0,0 +1,3 @@
## "Predicate" method

A method that ends with a question mark (`?`) is otherwise known as a "predicate" method. These methods are like any other methods, but since they look like questions they are commonly implemented so that they return `true` or `false`. This is useful in conditional expressions, e.g. `if size.zero? and file.closed?`.
3 changes: 3 additions & 0 deletions explanations/method_setter.md
@@ -0,0 +1,3 @@
## "Setter" method

A method that ends with an equal sign (`=`) is otherwise known as a "setter" method. Defining setter methods (or using `attr_writer`/`attr_accessor` to generate them) is the only way to enable assignment-like syntax for properties of the class. A setter method must take an argument. For example, the setter method "name=" on a "Person" class can be invoked in two styles: `person.name=("Ruby")` or `person.name = "Ruby"`. The syntaxes both perform the same function but the second one is preferred since it looks like regular variable assignment.
3 changes: 3 additions & 0 deletions explanations/module.md
@@ -0,0 +1,3 @@
## Module definition

A module groups together method definitions, constants, classes and other modules. Modules can be *included* by classes and other modules to import the original module's methods; this behaves similar to class inheritance but is not limited to a single include. Modules are also often used to group together other classes and modules which effectively provides a *namespace* for them; for instance "Net" is a module from Ruby standard library that serves as a namespace for `Net::HTTP` and related classes.
7 changes: 7 additions & 0 deletions explanations/require.md
@@ -0,0 +1,7 @@
## `require` method

The `require` method loads external code. It scans the `$LOAD_PATH` array of filesystem paths and loads the first matching file found in one of the paths. The method will never load a ruby script on the same path more than once, and the ".rb" file extension is usually omitted.

By default, the "load path" array includes the standard library of the current ruby installation, but the `require` method can also be used to load 3rd-party libraries through package managers such as [RubyGems][].

[rubygems]: http://rubygems.org
3 changes: 3 additions & 0 deletions explanations/variable_class.md
@@ -0,0 +1,3 @@
## Class variable

A class variable is a pointer to an object and is global inside a class, its subclasses and all their instances. They start with a double `@@` character. These variables are used to carry class configuration that is shared both in its instances and the class itself.
3 changes: 3 additions & 0 deletions explanations/variable_instance.md
@@ -0,0 +1,3 @@
## Instance variable

An instance variable is a pointer to an object and is available only inside a single object (an "instance"). They start with a single `@` character. These variables are used to carry object state, which differentiates one instance from another. An instance variable can be accessed before it is even assigned; its default value will be nil. However, in verbose mode the ruby interpreter will issue a warning about accessing a variable that is not declared. Instance variables are often initialized in the "initialize" method in a class.
3 changes: 3 additions & 0 deletions explanations/variable_local.md
@@ -0,0 +1,3 @@
## Local variable

A local variable is a pointer to an object and is available only in the local scope. Variables don't have to be declared upfront and can hold values of any type.
3 changes: 2 additions & 1 deletion fixtures/min.rb
@@ -1,2 +1,3 @@
a = 1
b = a + 2
@b = a + 2
@@c = "foo"

0 comments on commit 4eaa790

Please sign in to comment.