Getting Help

Getting Help#

Ri, the build-in documentation#

Ruby package contains the full API reference. It is available with ri command line. You might think about it as the man in Ruby world. This reference is available not only for the Ruby core, but for the installed gems as well (if the Gem provides it). You can search the documentation for classes and methods:

  • ri Class - then you are searching for general information on the specified class
  • ri method - find out all methods with the given name, in all classes (it might generate a long output)
  • ri Class#method - for instance methods in a given class
  • ri Class::method - to search for class methods in specified class
  • ri Class.method - for both class and instance methods (instance and class methods to be discussed later)

For example, to find out about String class:

$ ri String

= String < Object
------------------------------------------------------------------------------
= Includes:
Comparable (from ruby core)

(from ruby core)
------------------------------------------------------------------------------
A String object holds and manipulates an arbitrary sequence of bytes,
typically representing characters. String objects may be created using
String::new or as literals.

Because of aliasing issues, users of strings should be aware of the methods
that modify the contents of a String object.  Typically, methods with names
ending in ``!'' modify their receiver, while those without a ``!'' return a
new String.  However, there are exceptions, such as String#[]=.
------------------------------------------------------------------------------
= Class methods:

  new, try_convert

= Instance methods:

  %, *, +, <<, <=>, ==, ===, =~, [], []=, ascii_only?, b, block_scanf, bytes,
  bytesize, byteslice, capitalize, capitalize!, casecmp, center, chars, chomp,
  chomp!, chop, chop!, chr, clear, codepoints, concat, count, crypt, delete,
  delete!, downcase, downcase!, dump, each_byte, each_char, each_codepoint,
  each_line, empty?, encode, encode!, encoding, end_with?, eql?, ext,
  force_encoding, getbyte, gsub, gsub!, hash, hex, include?, index,
  initialize_copy, insert, inspect, intern, iseuc, isjis, issjis, isutf8,
  kconv, length, lines, ljust, lstrip, lstrip!, match, next, next!, oct, ord,
  partition, pathmap, pathmap_explode, pathmap_partial, pathmap_replace,
  prepend, replace, reverse, reverse!, rindex, rjust, rpartition, rstrip,
  rstrip!, scan, scanf, setbyte, shellescape, shellsplit, size, slice, slice!,
  split, squeeze, squeeze!, start_with?, strip, strip!, sub, sub!, succ,
  succ!, sum, swapcase, swapcase!, to_c, to_d, to_f, to_i, to_r, to_s, to_str,
  to_sym, toeuc, tojis, tolocale, tosjis, toutf16, toutf32, toutf8, tr, tr!,
  tr_s, tr_s!, unpack, upcase, upcase!, upto, valid_encoding?

It contains handy information: third line shows from which class Sting inherits, 5-6 line describes all includes (includes and inheritance are to be discussed later), then the general description of the object and class and instance methods. Notice there is a method called count, which we will use in a further examples.

When searching for a documentation for a specific method, for example count, you can use ri count command line, but you will see all of the object which implements this methods. The output below is truncated to show only few methods, but it may be very long if you have a lot of Gems installed:

$ ri count
= .count
(from ruby core)
=== Implementation from Array
------------------------------------------------------------------------------
  ary.count                   -> int
  ary.count(obj)              -> int
  ary.count { |item| block }  -> int

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

Returns the number of elements.

If an argument is given, counts the number of elements which equal obj using
===.

If a block is given, counts the number of elements for which the block returns
a true value.

  ary = [1, 2, 4, 2]
  ary.count                  #=> 4
  ary.count(2)               #=> 2
  ary.count { |x| x%2 == 0 } #=> 3

(from ruby core)

=== Implementation from Enumerable
------------------------------------------------------------------------------
  enum.count                 -> int
  enum.count(item)           -> int
  enum.count { |obj| block } -> int

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

Returns the number of items in enum through enumeration. If an argument is
given, the number of items in enum that are equal to item are counted.  If a
block is given, it counts the number of elements yielding a true value.

  ary = [1, 2, 4, 2]
  ary.count               #=> 4
  ary.count(2)            #=> 2
  ary.count{ |x| x%2==0 } #=> 3


(from ruby core)
=== Implementation from GC
------------------------------------------------------------------------------
  GC.count -> Integer

count is implemented in many classes, such as Array (4th line), Enumerable (line number 27) or GC (46). Much better is to specify the class, which ri should search. To do it, use ri String#count or ri String.count:

$ ri String#count

(from ruby core)
------------------------------------------------------------------------
  count(*selectors) -> integer

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

Returns the total number of characters in self that are specified by the given selectors (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):

  a = "hello world"
  a.count "lo"                   #=> 5
  a.count "lo", "o"              #=> 2
  a.count "hello", "^l"          #=> 4
  a.count "ej-m"                 #=> 4

  "hello^world".count "\\^aeiou" #=> 4
  "hello-world".count "a\\-eo"   #=> 4

  c = "hello world\\r\\n"
  c.count "\\"                   #=> 2
  c.count "\\A"                  #=> 0
  c.count "X-\\w"                #=> 3

Line 5 describes that this method comes from Ruby core, not from the outside Gem. 7th line shows the syntax of the method - str.count means it is invoked on the string object, next in parenthesis there are the parameters of the method - ([other_str]+) means it takes one or more “other string” parameters. Finally, -> integer means that the method returns a number (an object of class Integer).

After the description there are examples of invoking the method. Usually the example is followed by the #=> sequence (the hash sign and a default output prompt in irb) and the output value. So, in this case, a.count “lo” #=> 5 means that a.count “lo” should return number 5. Note, not every example line is covered by the return value - this is because some return values are meaningless in this case. And because of the hash # sign, Ruby treats the output given in the examples as a comment, so you can easy copy and paste this examples directly to irb, to check and play with it:

$ irb
irb(main):001:0> a = "hello world"
=> "hello world"
irb(main):002:0> a.count "lo"                   #=> 5
=> 5

The Web#

There is a number of Ruby resources on the Web. The central site for the documentation is ruby-lang.org - https://www.ruby-lang.org/en/documentation/. Ruby core API reference is on the ruby-doc.org - http://www.ruby-doc.org/core-2.0.0/ (note there are similar pages for the other Ruby version, for example http://www.ruby-doc.org/core-1.9.3/ for Ruby 1.9.3). On this page, you can filter the classes and methods to find out interesting documentation. For example, our String#class method is here: http://www.ruby-doc.org/core-2.0.0/String.html#method-i-count.

Another sites worth know is RubyDoc http://www.rubydoc.info - the hudge warehouse with documentation of Ruby Gems, the ApiDock - http://apidock.com/ruby - contains the API documentation with comments, which sometimes explains more than the raw API reference, and - last but not least - StackOverflow, the ultimate Questions and Answers site, where you can find and lot of explanations of how Ruby works. For example, here http://stackoverflow.com/questions/5305638/stringcount-options you can find a detailed explanation on String#count method.