はじめに
Rubyを勉強したり書いていると、「このクラスにはどんなメソッドが使えるんだ？」や「いろんな記事を見ながら頑張ってメソッド作ったのに標準ライブラリのメソッドで一発だったじゃん！！」といった具合でクラスごとやライブラリごとに使えるメソッドを知りたくなる機会は多いかと思います。 そんな時にRubyにはリファレンスマニュアルなるものが存在するのでとても役に立ちます。
ただ私自身毎回思うのが、リファレンスってちょっと分かり辛い...。めちゃくちゃありがたい情報の宝庫なんだけど、どこをどう見たらいいのか分からずかなり戸惑いました。
なので、初心者の方も中級以上の方もリファレンスの読み方や記法に戸惑った際にこの記事を参考にして頂けるように分かりやすさ重視でやさしく書いていきます。
Rubyリファレンスマニュアルってどんなサイト？
リファレンスマニュアルは、辞書的に使うことの出来る説明書のことを指します。
まずは見てみないことには始まらないですね。
オブジェクト指向スクリプト言語 Ruby リファレンスマニュアル (Ruby 2.5.0)
上記のサイトを右クリックして新しいタブで開くを選択して見てください。
そうするとあら不思議、この記事と並行して見ていけますね。
目次が並んでいるかと思います。
この中で注目したいのが一番下にあるこのマニュアルのヘルプ (Ruby 2.5.0) というところ。
そう、実は親切に解説記事まで載せてくれてるんです。私の出る幕はなさそうですね。と、言いたいところですがこのマニュアルだけだとまだ良くわからないところが出てくるので引用しながら更に噛み砕いて読み方を学んでいきましょう。
マニュアルのヘルプをもっとやさしく読み解く
検索
検索の仕方が記載されています。メソッド名とクラス名が英字だと検索が出来るみたいですね。ただ、
右上に検索窓があります
とあるのですが、私は検索窓が見当たりませんでした。 検索窓の在り処をご存知の方がいらっしゃったら教えていただきたいです。
記号の説明
ここではリファレンスマニュアルで出てくる独自の記法を説明しています。
実際に1つずつ追ってみていきましょう。
size -> Integer の「-> Integer」って何?
size メソッドは整数を返すという意味です。
この表現が理解できているとかなりリファレンスが読みやすくなります。
ここではIntegerが例として挙げられてます。実際にはここがStringだったりHashだったりします。つまり -> の右には、返り値の種類が置かれます。
Kernel.#require の .# って何?
「.#」はモジュール関数であることを表します。「Kernel.#require」は 「Kernel のモジュール関数である require 」という意味です。
わからない言葉が多いですよね。
まず、カーネルモジュールとは...?というところをこれまた公式ドキュメントでみていきます。module Kernel (Ruby 2.4.0)
modele Kernel
全てのクラスから参照できるメソッドを定義しているモジュール。 Object クラスはこのモジュールをインクルードしています。
どこからでも使えるメソッドを定義してるところみたいな認識で良さそうです。
そして次に出てくる目次に先程のモジュール関数が出てきます。つまりモジュール関数というのは、どこからでも使えるメソッドの一種ということになります。
話しは戻って、
Kernel.#require の .# って何?
の .#はモジュール関数、つまり、どこからでも使えるメソッドの一種であることを示していたのですね。 Kernel.#require の場合「requireはモジュール関数のひとつだよ」というのを表していることがわかります。
String#size の # って何?
「#」はインスタンスメソッドであることを表します。
これはそのままですが、インスタンスメソッドなので、この場合sizeメソッドはStringクラスをインスタンス化したら使うことのできるインスタンスメソッドで有ることを示します。
Dir.chdir の . って何?
「.」はクラスメソッドであることを表します。
上のインスタンスメソッドに対してクラスメソッドを示します。クラス本体から呼び出せます。 特異メソッドとも呼ばれて、リファレンスマニュアルにもその表現がよく出てくるので覚えておきましょう。
p a #=> 1 の #=> って何?
「#=>」は標準出力に出力されるということを表しています。 「p a #=> 1 」は「p a」を実行すると標準出力に「1」が出力される という意味です。
これはわかりやすいなと感じたのであまり付け足すこともないのですが、標準出力って何？？という方は以下のサイトが参考になります。
参考サイト: 標準出力とは｜「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典
返り値の詳細
記号の説明で一番目にでてきた -> の右側には返り値が置かれるということでした。では返り値にどんな種類があるのか、、というところをここで紹介しています。
- 真偽値を返す場合は「bool」です
真偽値はtrueかfalseのことですね。 -> boolとあったらtrueかfalseが返ってくるんだなと見ましょう。
- 返り値が不定の場合は、「-> ()」です
返り値がわからない際に使われようですが、出現率低めです。
- 任意の型を返す場合は 「object」 です
返り値が左辺による場合などは-> object と表現されます。
- 配列を返す場合は 「[クラス名]」 か 「Array」 です
nesting -> [Class, Module] こんな感じで[]内のオブジェクトが配列に入って返ってきます。
- 代入式の場合には省略されます
代入式の場合は返り値を明記する必要はないので省略されます。
これで基本の読み方はOKです。それでは実際にリファレンスマニュアルを読んでいきましょう。
実際にリファレンスマニュアルを読んでみる
リファレンスマニュアルを読む際、どこを見たら良いのか？とまず悩んでしまいがちですが、組み込みライブラリと標準添付ライブラリを見ていくと大体知りたいライブラリやメソッドが出てくるかと思います。
今回は、例として使用頻度の高いArrayクラスの中から見ていきます。( 組み込みライブラリ >Array )
見出し
- クラスの要約
- 各メソッドの目次
- 特異メソッド(クラスメソッド)
- インスタンスメソッド
となっています。
ここで挙げられるメソッドというのは、 「Arrayクラスのオブジェクトに対して使えるメソッド一覧」 です。
まずは特異メソッド(クラスメソッド)の中にあるnewを更に見ていきましょう。
メソッドの詳細
newをクリックすると
new(size = 0, val = nil) -> Array
の行まで飛びます。
-> Array
とあるので、newの返り値はArrayクラスを示していることが分かりますね。
また、マニュアルのヘルプには出てこなかった、
(size = 0, val = nil)
という表現が出てきました。
これは、newメソッドの引数として設定できる初期値を表しています。
new(size = 0, val = nil)
つまりnewの第一引数は初期値が0のsize、第二引数には初期値がnilのvalueがセットされていることがわかります。
続いての
長さ size の配列を生成し、各要素を val で初期化して返します。
要素毎に val が複製されるわけではないことに注意してください。 全要素が同じオブジェクト val を参照します。 後述の例では、配列の各要素は全て同一の文字列を指します。
は、メソッドの説明文となっています。ここをしっかり理解することでこのメソッドで何が出来るのかを把握できます。
[PARAM] size:
配列の長さを数値で指定します。
[PARAM] val:
配列の要素の値を指定します。
[PARAM]は、引数について詳しく説明しています。引数に何を入れたらいいかなどはここを見れば分かりそうですね。
さぁ、ここまで来たら実際にどう使われるのか知りたくなってきます。そこで登場するのが例文です。
例:
ary = Array.new(3, "foo")
p ary #=> ["foo", "foo", "foo"]
ary[0].capitalize!
p ary #=> ["Foo", "Foo", "Foo"] (各要素は同一のオブジェクトである)
このように実際に引数もセットして実行時の返り値まで書かれています。
ary[0].capitalize!
は、引数にセットしたvalueが同一のオブジェクトであることを表すために用意されています。
これは、
(各要素は同一のオブジェクトである)
を見ると読み取れますね。
ここまででArrayクラスのnewメソッドに引数としてsizeとvalを渡したら、sizeで指定した個数分valが格納されたArrayクラスが返り値となることは掴めました。
もっと深く知りたい
もっとそのメソッド自身や、関連するメソッドを調べたい時はここから先もやってみることをおすすめします。
new(size = 0, val = nil) -> Array
の右側には、[permalink][rdoc]というリンクがあります。
最初にこの[permalink]というリンクについてです。
ここではArrayクラスで使えるnewメソッド一覧を表示してくれます。 どんな違いがあるのかを見ておくと、やりたい処理がある時に参考になりそうですね。
次に[rdoc]です。そもそもRDocとは?という方多いのではないでしょうか。
こちらに書いてあるとおり、
RDoc は Ruby のドキュメント生成を行うためのライブラリ
なので、[rdoc]を開くとRubyのソースデータから生成されたドキュメントが表示されます。
これでメソッドをソースコードベースで更に深く知ることが出来ますね。
まとめ
Rubyのリファレンスマニュアルが読み取れるようになれば、Googleで検索してメソッドの使い方をイチから探したりするよりずっと早く正確な情報がゲット出来ます。
RubyやRailsを書く上で幸せになれること間違い無しなのでこの記事を参考にリファレンスマニュアルを積極的に活用していきましょう。