Ruby documentation for a complete beginner

Question

Ruby 2.1.5

I've just started learning Ruby.

Could you help me get to know how to work with documentation. This is my example:

some_array = [1, 2, 3, 4, 5]
some_array.each {|value| puts value * 3 }

Frankly speaking I'm an absolute full before I have found explanation in the documentation. I'd like to find everything. For example I can't catch the idea of what is inside the curly braces.

What I understand is that we have a foreach loop here. But I can't catch almost anything else. I'd like to read in the documentation something about: 1. Arrays. 2. each method. 3. Why after each I need {} 4. What is value, why for the first time I need || and then I just use value.

Well, when I answer these questions, I will know how to use the documentation. Now I don't know even where the documentaion is. Could you help me? If yes, could you give me some links and tell me: look here, here, here and here.

Thank you in advance.

Why not getting a book about ruby and reading it instead of trying to figure out what some random code means? A book will give you context and follow through small examples before throwing something like that. — Maurício Linhares, Dec 17 '14 at 16:26
I'm really reading a book. The example is from there. But almost any book is written like this: let's do like that and get something like this. I always need documentation to understand the example. — Michael, Dec 17 '14 at 16:31
If the book shows you this example and doesn´t provide any context to understand it, find another book. — Maurício Linhares, Dec 17 '14 at 16:32

score 0 · Answer 1 · answered Dec 17 '14 at 16:45

I can't catch the idea of what is inside the curly braces.

What's inside of the curly braces is a piece of code that the method each will automatically execute for each element in the array.

The each method in the array class automatically will call this piece of code. Here is an example that should help you understand how this works:

class Demo

  def initialize(values)
    @values = values
  end

  def traditional_loop
    for i in [0..@values.length-1] 
      puts @values[i]
    end
  end

  def loop_with_block
    for i in [0..@values.length-1] 
      yield @values[i]
    end
  end

end

some_array = [1, 2, 3]
d = Demo.new(some_array)
d.traditional_loop

d.loop_with_block {|x| puts x}

The code in traditional_loop is how you do loops in most languages. You just iterate inside an array with a for statement. However, this code forces you to put the logic to execute on each element inside the class (notice the puts statement inside this method)

The code in loop_with_block uses yield instead to execute an arbitrary piece of code on each element of the array. When this code calls yield @values[i] you can interpret it as "execute the particular piece of that was passed to me (the code inside the curly braces) and pass it the value of the current element in the array"

This is more or less what the default each method does for arrays.

You might want to read on Ruby blocks to get a better idea on how this works since it is very pervasive in Ruby.

Well, the question was more about documentation. – Michael Dec 17 '14 at 16:53 — Michael, Dec 17 '14 at 16:53

score 0 · Accepted Answer · edited Jun 20 '20 at 09:12

We can find documentation of Ruby's Array class here: http://www.ruby-doc.org/core-2.1.5/Array.html including it's each instance method: http://www.ruby-doc.org/core-2.1.5/Array.html#method-i-each

There we see:

each { |item| block } → ary

Calls the given block once for each element in self, passing that element as a parameter.

Which is a good hint that we want to learn more about "blocks" (the chunk of code wrapped in those {}s) so we could look at a related question like Best explanation of Ruby blocks? or look for related documentation like http://docs.ruby-doc.com/docs/ProgrammingRuby/html/tut_containers.html

score 0 · Answer 3 · answered Dec 17 '14 at 17:10

You are asking about extremely basic features of Ruby syntax and semantics. There is documentation of Ruby's syntax and semantics in the ISO/IEC 30170:2012 Ruby Language Specification, but before you fork over 200 bucks for the official documentation, may I urge you to reconsider and just read one of the hundreds of free basic Ruby tutorials instead? If you must, the information you are looking for is in section 11.3.3 for the semantics and 6.4 for a short overview.

The documentation on sites such as Ruby-Doc and RDoc.Info documents the side-effects and return values and behaviors of the methods in the Ruby core and standard library, but they don't really explain what a return value or an argument or a method is or how to call a method. That knowledge is assumed to exist.

Ruby documentation for a complete beginner

3 Answers3