YAMLの復習

YAMLのノードには3種類(kind)がある：

• Scalar (Unicodeの文字列として表現できるもの)
• Sequence (配列みたいなもの)
• Mapping (連想配列やHashみたいなもの)

それぞれのkindはいくつかのstyleで出力できる。

• Scalar：
  1. Plain (1行)

        1  Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
     
  2. Single Quote (1行)

        1  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '
     
  3. Double Quote (1行)

        1  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
     
  4. Block Literal (改行がそのまま残る)

        1  --- |
        2   Lorem ipsum dolor sit amet,
        3   consectetur adipiscing elit.  
        4   Pellentesque tincidunt molestie est.
        5   Vestibulum ante odio, euismod ac,
        6   sagittis et, tempus ut, lorem. 
        7   Praesent consectetur tempor ipsum.
        8   Nulla facilisi. 
     
  5. Block Folding (改行が空白になる)

        1  --- >
        2   Lorem ipsum dolor sit amet,
        3   consectetur adipiscing elit.  
        4   Pellentesque tincidunt molestie est.
        5   Vestibulum ante odio, euismod ac,
        6   sagittis et, tempus ut, lorem. 
        7   Praesent consectetur tempor ipsum.
        8   Nulla facilisi. 
     
• Sequence
  1. デフォルト

        1   - one
        2   - two
        3   - three
     
  2. inline

        1   [1, 2, 3]
     
• Mapping
  1. デフォルト

        1   height: 170
        2   weight: 60
     
  2. inline

        1   { height: 170, weight: 60}
     

で、

YAML::dumpでオブジェクトをダンプしたい時、styleを統一する場合もある。が、YAML::dumpにはstyleを指定する機能はない。そこで、to_yaml_styleをオブジェクトに定義すればよい、という裏技(非ドキュメントメソッド)を紹介したい。このメソッドの返り値がそのオブジェクトのstyleになる。

例えば：

   1  class String
   2   def to_yaml_style
   3    return :quote2
   4   end
   5  end

をすれば、YAML::dumpのすべての文字列がダブルクオートに囲まれる。

Rubyでのスタイルは以下：

   1  :plain # クオートなし
   2  :quote1 # シングルクオート
   3  :quote2 # ダブルクオート
   4  :literal # Block Literal
   5  :fold # Block Folding
   6  :inline # Inline (Sequence, Mapping)
   7  nil # デフォルト (Sequence, Mapping)

ちなみに、これを調べた切っ掛けはHashをYAML::dumpした時にvalueの方にクオートがあったりなかったりしたからです。つまりこれ：

   1   name: "鈴木"
   2   height: 170
   3   weight: 60

をこれにする：

   1   name: "鈴木"
   2   height: "170"
   3   weight: "60"

monkeypatch的な解決方法：

   1  class Hash
   2    def to_yaml_with_quoted_strings(*args)
   3      class << self
   4        unless method_defined?(:each_with_quoted_strings)
   5          def each_with_quoted_strings
   6            each_with_normal_strings do |k,v|
   7              if String === v && !v.frozen?
   8                def v.to_yaml_style; return :quote2; end
   9              end
  10              yield k, v
  11            end
  12          end
  13            alias_method :each_with_normal_strings, :each
  14            alias_method :each, :each_with_quoted_strings
  15        end
  16      end
  17      return to_yaml_with_normal_strings(*args)
  18    end
  19    alias_method :to_yaml_with_normal_strings, :to_yaml
  20    alias_method :to_yaml, :to_yaml_with_quoted_strings
  21  end

gist

参考

• YAMLの仕様
• _why on to_yaml_style@ruby-talk:178321
• syck on github
  • syck.h styleの定義
  • rubyext.c styleのRubyマッピング

rdocのデフォルトのテンプレートが非常にダサくて、なかなか使いづらい。mislavのhannaを使えば、こんなにスタイリッシュになる：

おまけとして、簡単なメソッド検索もできます。また、テンプレート自体はhamlで書いていて、なかなか読みやすい。「スケールできる」ことが売りらしいけど、まぁ意味不明な自慢だよね。

インストール

1. rdoc 2.3.0をインストールする。現在のhannaはまだ最新rdocの2.4.xに対応していないからご注意ください。

      1  sudo gem install rdoc -v 2.3
      2  <<-- 
      3  2. githubをgemのsourceに追加
      4  shell-unix-generic>>
      5  gem source add http://gems.github.com
   
2. インストール

      1  gem install mislav-hanna
   
3. インストール済みのgemのrdocをhannaにする

      1  hanna --gems
   
4. これからインストールするgemのrdocもhannaにするため、.gemrcに以下の一行を追加する

      1  rdoc: --inline-source --line-numbers --format=html --template=hanna
   

ちなみに、今使っている.gemrcはこんな感じ：

   1  --- 
   2  :benchmark: false
   3  :update_sources: true
   4  :sources: 
   5  - http://gems.rubyforge.org/
   6  - http://gems.github.com
   7  :bulk_threshold: 1000
   8  :backtrace: false
   9  :verbose: true
  10  rdoc: --inline-source --line-numbers --format=html --template=hanna

もっと凄いドキュメント検索：sdoc

railsapiで使っているsdocというやつもある。これの検索機能がなかなかすばらしい。ただし、今のところは単体のプロジェクトでしか使えなくて、gemからtemplateとして指定することができないみたい。また、githubへのリンクもgithubを使っていないプロジェクトにとってはちょっと魅力が薄れる。にもかかわらず、とても魅力的だな。

   1  gem install voloko-sdoc --source http://gems.github.com

rdocは2.3ではなく、2.4が必要のようです。

   1  gem install rdoc -v 2.4

適当なプロジェクトで実行：

   1  cd <project>
   2  sdoc -N .

で、できあがり

参考

• mislav's hanna on github
• Offline Gem Server Rdocs
• Labnotes> Buildr: how we generate the documentation, Web site and PDF
• voloko's sdoc on github