Navigating through the official Ruby documentation

ruby-talk
1

Hi,

I have been trying to learn Ruby and so far so good I'm slowly leering
the basics. I was trying to start referring to the Docs but I'm a little
confused, I was expecting to see a list of all Ruby classes and
underneath the class name a list of all of its methods but it has more
than just methods, I don’t know if I still need more knowledge about the
language in order for me to understand the information provided in the
official Ruby Docs.

Class Name

methods

Class Name

methods

I see some methods start with a "#" some with "::" and than you have the
following sections: In Files, Class/Module Index, Parent etc. I’m
guessing this has to do with Modules vs Classes.

Can someone be so kind and go through the Ruby Docs and basically
explain how is this organized?

As I said I don't know if it’s because I don't fully understand the Ruby
syntax or I simply need some adviceon how to use this documentation.

Thanks a lot

···

--
Posted via http://www.ruby-forum.com/\.

2

Okay, let's see...

Let's take the Array docs as an example. By the way you're talking,
I'm going to take a shot in the dark and guess you're used to the Java
API documentation? :slight_smile: So you are familiar with the idea of static and
non-static methods (if not, just read on and see if it makes sense.
Otherwise ask).

In Ruby, static methods are described as "class methods". These are
methods that are not called from an instance of a class, but the class
itself. For example:

    Class.method_name(args)

Is how you would see a class method called. In the Ruby documentation,
these are prefixed with two colons ::

Non-static methods are referred to as "instance methods", and these
are called like so:

   c = Class.new
   c.some_method(args)

They're called in the instance of a class and in the Ruby
documentation these are prefixed with a hash (or pound if you're
American) #

The parent of a class is what the current class inherited from. In
Ruby, there's a hierarchy similarish to Java's. Everything inherits
from the Object class: Class: Object (Ruby 1.9.3)
(Object inherits from BasicObject for some reason, I would need to ask
someone else why this is, though, sorry :)).

If you don't understand object orientation, just say so and I'll find
you some good resources.

Modules are a really cool thing in Ruby. The "Included Modules"
section of a Ruby doc page tells you what modules the class is "mixing
in". I wrote an article about Ruby mixins, you can find it here:
http://samwho.co.uk/blog/2011/09/12/ruby-mixins/\. It gives an overview
of what you can do with Ruby modules and likens them to similar
concepts in other languages that you might be more familiar with. If
you find that it confuses you, let me know where so I can reword it.

The "Class/Module Index" section of the page just looks like a list of
all classes in Ruby's standard library so you can quickly navigate
through them.

I hope this helps demystify the Ruby docs. Feel free to ask about
anything you're unsure of :slight_smile:

···

On 10 November 2011 17:22, Fily Salas <fs_tigre@hotmail.com> wrote:

Hi,

I have been trying to learn Ruby and so far so good I'm slowly leering
the basics. I was trying to start referring to the Docs but I'm a little
confused, I was expecting to see a list of all Ruby classes and
underneath the class name a list of all of its methods but it has more
than just methods, I don’t know if I still need more knowledge about the
language in order for me to understand the information provided in the
official Ruby Docs.

Class Name

methods

Class Name

methods

I see some methods start with a "#" some with "::" and than you have the
following sections: In Files, Class/Module Index, Parent etc. I’m
guessing this has to do with Modules vs Classes.

Can someone be so kind and go through the Ruby Docs and basically
explain how is this organized?

As I said I don't know if it’s because I don't fully understand the Ruby
syntax or I simply need some adviceon how to use this documentation.

Thanks a lot

--
Posted via http://www.ruby-forum.com/\.

3

Hi,

Hi,

I have been trying to learn Ruby and so far so good I'm slowly
leering the basics. I was trying to start referring to the Docs but
I'm a little confused, I was expecting to see a list of all Ruby
classes and underneath the class name a list of all of its methods
but it has more than just methods, I don’t know if I still need
more knowledge about the language in order for me to understand the
information provided in the official Ruby Docs.

Assuming you’re refering to Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3), it’s
relatively easy. On the left side you have the "In Files" section.
This tells you the names of the files inside the Ruby sourcecode where
methods of your respective class are defined. For instance, for the
Array class at Class: Array (Ruby 1.9.3) there are
"array.c" and "pack.c" listed. This means, methods of this class are
defined inside these files. Normally this shouldn't bother you, it's
just an additional information (this can be useful in combination with
gems if you don't know which files to require). On the right side you
see the actual class/module documentation.

I see some methods start with a "#" some with "::"

Those starting with # are instance methods, those starting with :: are
class methods, i.e. methods you can call directly on the class.
Array::new therefore is the same as Array.new (although the first form
is AFAIK discouraged in actual code). The # is no valid Ruby syntax
(if you try this, you’re likely to get syntax errors as this
introduces a comment).

and than you have the following sections: In Files,

See above.

Class/Module Index

This is the list of all documented classes and modules, not just those
related to e.g. Array.

Parent

This is the parent class of the class you’re currently looking at.
Look up what inheritance means if this isn’t clear to you.

I’m guessing this has to do with Modules vs Classes.

No. Classes in Ruby are basically modules with the specific ability to
create instances of themselves (via the ::new method).

Sometimes, e.g. in the Array class, there’s also a section called
"included modules". This lists all the modules that have been added to
a class by using the Module#include method. Search for "mixins" if you
want to know more on this. Both "Included modules" and "Parent" can
list entities containing more methods than those of the class you’re
looking at. For example, arrays have a method #max, but you won’t find
this in the documentation of the Array class. It comes from the
Enumerable module.

Vale,
Marvin

···

Am 10.11.2011 18:22, schrieb Fily Salas:

4

Double WOW! for you two guys.

I'm always impress about the help I get here.

Very good information, it basically answers all of my questions.

One thing I see here is that I don't fully understand the big difference
between Classes and Modules in Ruby but
you even read my mind and added a link.

http://samwho.co.uk/blog/2011/09/12/ruby-mixins/

I was thinking that Modules were just a form of separating classes (Name
Scopes for classes). The only language
I know a little bit is Actionscript 3.0 and it uses Packages to enclose
classes but apparently in Ruby Modules
do this and more.

Thanks a lot Sam Rose

···

--------------------------------

@Marvin Gülker
No. Classes in Ruby are basically modules with the specific ability to
create instances of themselves (via the ::new method).

As I mentioned above I need to have a better understanding about modules
and classes.

For example, arrays have a method #max, but you won’t find
this in the documentation of the Array class. It comes from the Enumerable

module.
The problem I see with this (if you want to call it a problem) is that
for novice like me, there is no way to know what methods have been
inherited from the module or other classes since they are not listed
here, I could open the module or the class itself, but how do you know
what methods have been inherited to other classes.

I asked for one thing and I always end up learning other things,
awesome. YOU GUYS ARE AWESOME!

I LOVE THIS FORUM

--
Posted via http://www.ruby-forum.com/\.

5

irb(main):040:0> system "ri Array | head"
= Array < Object

···

On Fri, Nov 11, 2011 at 2:50 AM, Fily Salas <fs_tigre@hotmail.com> wrote:

The problem I see with this (if you want to call it a problem) is that
for novice like me, there is no way to know what methods have been
inherited from the module or other classes since they are not listed
here, I could open the module or the class itself, but how do you know
what methods have been inherited to other classes.

------------------------------------------------------------------------------
= Includes:
Enumerable (from ruby core)

(from ruby core)
------------------------------------------------------------------------------
Arrays are ordered, integer-indexed collections of any object. Array indexing
starts at 0, as in C or Java. A negative index is assumed to be relative to
=> true

irb(main):041:0> Array.methods.grep /methods/
=> [:instance_methods, :public_instance_methods,
:protected_instance_methods, :private_instance_methods, :methods,
:singleton_methods, :protected_methods, :private_methods,
:public_methods]

irb(main):052:0> system "ri instance_methods | head"
= .instance_methods

(from ruby core)
=== Implementation from Module
------------------------------------------------------------------------------
  mod.instance_methods(include_super=true) -> array

------------------------------------------------------------------------------

=> true

irb(main):054:0> Array.instance_methods
=> [:inspect, :to_s, :to_a, :to_ary, :frozen?, :==, :eql?, :hash, :,
:=, :at, :fetch, :first, :last, :concat, :<<, :push, :pop, :shift,
:unshift, :insert, :each, :each_index, :reverse_each, :length, :size,
:empty?, :find_index, :index, :rindex, :join, :reverse, :reverse!,
:rotate, :rotate!, :sort, :sort!, :sort_by........ <snipped>

irb(main):061:0> (Array.instance_methods - Array.instance_methods(false) ).sort
=> [:!, :!=, :!~, :===, :=~, :__id__, :__send__, :all?, :any?, :chunk,
:class, :clone, :collect_concat, :define_singleton_method, :detect,
:display, :dup, :each_cons, :each_entry, :each_slice,
:each_with_index, :each_with_object, :entries, :enum_for, :equal?,
:extend, :find, :find_all, :flat_map, :freeze, :grep, :group_by,
:initialize_clone, :initialize_dup, :inject, :instance_eval,
:instance_exec, :instance_of?, :instance_variable_defined?,
:instance_variable_get, :instance_variable_set, :instance_variables,
:is_a?, :kind_of?, :max, :max_by, :member?, .......<snipped>

6

hi Fily,

  you can think of a module as a collection of useful methods that you
can pass around (mix in) between various classes. from what i
understand modules have a lot less 'overhead' than classes as well.

  you could write a module called 'Transmission' in which you define how
to shift gears - and then mix that module into different vehicle classes
that will all share the methods defined in the module...

  module Transmission
    attr_reader :gear
    def num_of_gears=(n)
      ...
    end
    def clutch
      ...
    end
    def shift(up_or_down)
      ...
    end
    def grind_gears
      ...
    end
  end

  class Car
    include Transmission
    def initialize(n)
      num_of_gears = (n)
      ...
    end
    ...
  end

  class Motorcycle
    include Transmission
    def initialize(n)
      num_of_gears = (n)
      ...
    end
    ...
  end

  bike = Motorcycle.new(5)
  car = Car.new(4)

  bike.clutch
  bike.shift('up')

  car.clutch
  car.shift('up')

  etc....

  - j

···

--
Posted via http://www.ruby-forum.com/.

7

-----Messaggio originale-----

···

Da: jake kaiden [mailto:jakekaiden@yahoo.com]
Inviato: sabato 12 novembre 2011 16:20
A: ruby-talk ML
Oggetto: Re: Navigating through the official Ruby documentation

hi Fily,

  you can think of a module as a collection of useful methods that you can
pass around (mix in) between various classes. from what i understand
modules have a lot less 'overhead' than classes as well.

  you could write a module called 'Transmission' in which you define how to
shift gears - and then mix that module into different vehicle classes that
will all share the methods defined in the module...

  module Transmission
    attr_reader :gear
    def num_of_gears=(n)
      ...
    end
    def clutch
      ...
    end
    def shift(up_or_down)
      ...
    end
    def grind_gears
      ...
    end
  end

  class Car
    include Transmission
    def initialize(n)
      num_of_gears = (n)
      ...
    end
    ...
  end

  class Motorcycle
    include Transmission
    def initialize(n)
      num_of_gears = (n)
      ...
    end
    ...
  end

  bike = Motorcycle.new(5)
  car = Car.new(4)

  bike.clutch
  bike.shift('up')

  car.clutch
  car.shift('up')

  etc....

  - j

--
Posted via http://www.ruby-forum.com/.

--
Caselle da 1GB, trasmetti allegati fino a 3GB e in piu' IMAP, POP3 e SMTP autenticato? GRATIS solo con Email.it http://www.email.it/f

Sponsor:
Capodanno a Riccione, Pacchetto Relax: Mezza Pensione + bagno turco + solarium + massaggio. Wifi e parcheggio gratis. 2 giorni euro 199 a persona
Clicca qui: http://adv.email.it/cgi-bin/foclick.cgi?mid=11978&d=29-12