RubyでYAMLを拡張する方法と、外部ファイルのincludeに対応させる実例

設定ファイルとしてYAMLを扱うことが多いため、yamlを便利に扱うために[yaml_vault](https://github.com/joker1007/yaml_vault)と[yaml_master](https://github.com/joker1007/yaml_master)というgemを作っている。

yaml_vaultはYAMLの特定キーを暗号化・複合化するためのgemで、yaml_masterはmasterファイルとして指定されたyamlから一部のキーだけを切り出して別ファイルに書き出したり、まとめて設定ファイルを生成したりするためのgemだ。

そして、最近この二つのgemを改修するためにRubyのYAML生成処理を調べたので、その知見をまとめておく。

yaml_vaultは元々の動作では暗号化したり複合化したりすると、YAMLのエイリアス記法が展開されてしまうという動作上の限界があった。

こういうのが

```yaml
default: &default
  adapter: mysql
  encoding: utf8mb4
  username root

production
  <<: *default
  password: secretpass
```

こうなる

```yaml
default: &default
  adapter: mysql
  encoding: utf8mb4
  username root

production:
  adapter: mysql
  encoding: utf8mb4
  username root
  password: <encrypted string>
```

また、yaml_masterは外部ファイルをincludeするための仕組みを実装していたのだが、それだとエイリアス記法が共有できないという限界があった。


```yaml
yaml_master:
  db: db.yml

default: &default
  adapter: mysql
  encoding: utf8mb4
  username root

data
  !include production.yml
```

```yaml
# production.yml

production:
  <<: *default
  password: secretpass
```

こういう書き方をするとアンカーが見つからなくてエラーになる。

この二つの問題を解決するには、YAMLのASTを構築する段階で既に必要な処理が終わってる状態を作る必要がある。

RubyのYAMLライブラリはpsychというバックエンドライブラリが実際の処理をしている。今回、AST構築処理を弄るためにどこに処理を差し込めばいいかを調べた。


psychは`Psych::Parser`というクラスがYAMLのトークナイズをしてハンドラクラスのイベントハンドラメソッドを呼び出す。例えば処理対象がsequenceだったら`start_sequence`と`end_sequence`を呼ぶ。
`Psych::TreeBuilder < Psych::Handler`というクラスはイベントハンドラメソッドで、`Psych::Nodes::<NodeType>`クラスのインスタンスを生成し、YAMLのASTを構築する。

`Psych::TreeBuilder`の実装は以下の様になっている。

```rb
# frozen_string_literal: false
require 'psych/handler'

module Psych
  ###
  # This class works in conjunction with Psych::Parser to build an in-memory
  # parse tree that represents a YAML document.
  #
  # == Example
  #
  #   parser = Psych::Parser.new Psych::TreeBuilder.new
  #   parser.parse('--- foo')
  #   tree = parser.handler.root
  #
  # See Psych::Handler for documentation on the event methods used in this
  # class.
  class TreeBuilder < Psych::Handler
    # Returns the root node for the built tree
    attr_reader :root

    # Create a new TreeBuilder instance
    def initialize
      @stack = []
      @last  = nil
      @root  = nil
    end

    %w{
      Sequence
      Mapping
    }.each do |node|
      class_eval %{
        def start_#{node.downcase}(anchor, tag, implicit, style)
          n = Nodes::#{node}.new(anchor, tag, implicit, style)
          @last.children << n
          push n
        end

        def end_#{node.downcase}
          pop
        end
      }
    end

    ###
    # Handles start_document events with +version+, +tag_directives+,
    # and +implicit+ styling.
    #
    # See Psych::Handler#start_document
    def start_document version, tag_directives, implicit
      n = Nodes::Document.new version, tag_directives, implicit
      @last.children << n
      push n
    end

    ###
    # Handles end_document events with +version+, +tag_directives+,
    # and +implicit+ styling.
    #
    # See Psych::Handler#start_document
    def end_document implicit_end = !streaming?
      @last.implicit_end = implicit_end
      pop
    end

    def start_stream encoding
      @root = Nodes::Stream.new(encoding)
      push @root
    end

    def end_stream
      pop
    end

    def scalar value, anchor, tag, plain, quoted, style
      s = Nodes::Scalar.new(value,anchor,tag,plain,quoted,style)
      @last.children << s
      s
    end

    def alias anchor
      @last.children << Nodes::Alias.new(anchor)
    end

    private
    def push value
      @stack.push value
      @last = value
    end

    def pop
      x = @stack.pop
      @last = @stack.last
      x
    end
  end
end
```

使う時はこんな感じ。

```rb
YAML::Parser.new(YAML::TreeBuilder.new).parse(yaml)
```

処理スタックを積みながら、ノードを生成しているだけなので簡単な作りになっている。
このクラスを継承して独自の処理を挟み込むことで、ASTを構築する段階で任意のフィルター処理を実行できる。

yaml_vaultではこの様な実装をしている。

```rb
require 'yaml'

module YamlVault
  class YAMLTreeBuilder < YAML::TreeBuilder
    def initialize(target_paths, cryptor, mode)
      super()

      @path_stack = []
      @target_paths = target_paths
      @cryptor = cryptor
      @mode = mode
    end

    def start_document(*)
      result = super
      @path_stack.push "$"
      result
    end

    def end_document(*)
      @path_stack.pop
      super
    end

    def start_mapping(*)
      if YAML::Nodes::Sequence === @last
        current_path = @last.children.size
        @path_stack << current_path
      end

      super
    end

    def end_mapping(*)
      @path_stack.pop
      super
    end

    def start_sequence(*)
      if YAML::Nodes::Sequence === @last
        current_path = @last.children.size
        @path_stack << current_path
      end

      super
    end

    def end_sequence(*)
      @path_stack.pop
      super
    end

    def scalar(value, anchor, tag, plain, quoted, style)
      result = super

      case @last
      when YAML::Nodes::Sequence
        current_path = @last.children.size - 1
        @path_stack << current_path
      when YAML::Nodes::Mapping
        if @last.children.size.odd?
          @path_stack << value
          return result
        end
      end

      if match_path?
        if @mode == :encrypt
          if tag
            result.value = @cryptor.encrypt("#{tag} #{value}")
            result.tag = nil
            result.plain = true
          else
            result.value = @cryptor.encrypt(value)
          end
        else
          decrypted_value = @cryptor.decrypt(value).to_s
          if decrypted_value =~ /\A(!.*?)\s+(.*)\z/
            result.tag = $1
            result.plain = false
            result.value = $2
          else
            result.value = decrypted_value
          end
        end
      end

      @path_stack.pop

      result
    end

    def alias(anchor)
      @path_stack.pop
      super
    end

    private

    def match_path?
      @target_paths.any? do |target_path|
        target_path.each_with_index.all? do |path, i|
          if path == "*"
            true
          else
            if path.is_a?(Regexp)
              path.match(@path_stack[i])
            else
              path == @path_stack[i]
            end
          end
        end
      end
    end
  end
end
```

各イベントの処理を上書きして、独自のパススタックを積み、終端であるスカラー値まで到達したら、対象のキーパスを確認して暗号化・複合化の処理を行い、値を差し替える。
この時、`value`はまだRubyオブジェクトに変換する前なので文字列のままになっている。

こうやって生成したASTは`Psych::Nodes::Stream#to_yaml`メソッドを呼ぶことで、ほぼ元のフォーマットを維持したままYAMLとして出力することができる。(流石に空行とかは消えるし、インデントスタイルもちょっと変わる場合がある)

また、YAMLはタグと呼ばれる機能がある。例えば`!ruby/range 1..10`の様に書くことができる。RubyのYAMLパーサーは、このタグを利用してYAMLが直接サポートしないオブジェクトをYAMLに埋め込むことができる。この例だとパース後にRubyオブジェクトに変換する際に`1..10`のRangeオブジェクトとして受け取ることができる。
上記実装例の`scalar`メソッドには`tag="!ruby/range"` `value="1..10"`という値が渡ってくる。

その他、YAMLの書式のバリエーションによって、`plain`, `quoted`, `style`の値が変わる。どういう書式がどの値になるかは、実際に何かのYAMLをパースさせて`pp`で確認するのが楽だろう。

このタグを利用してyaml_masterの外部ファイルinclude機能も実装できた。

```rb
require 'yaml'
require 'pathname'

class YamlMaster::YAMLTreeBuilder < YAML::TreeBuilder
  def initialize(master_path, properties, parser)
    super()
    @master_path = master_path
    @parser = parser
  end

  def scalar(value, anchor, tag, plain, quoted, style)
    case tag
    if "!include"
      ensure_tag_argument(tag, value)

      path = Pathname(value)
      path = path.absolute? ? path : @master_path.dirname.join(path)
      tree = YAML.parse(File.read(path))
      @last.children << tree.children[0]
    else
      super
    end
  end

  private

  def ensure_tag_argument(tag, value)
    if value.empty?
      mark = @parser.mark
      $stderr.puts "tag format error"
      $stderr.puts "#{tag} requires 1 argument at #{mark.line}:#{mark.column}"
      exit 1
    end
  end
end
```

`!include`タグが見つかったら、`value`になっている値をファイル名として読み込んだ後`YAML.parse`をしてインクルード対象のASTを取得する。その後、スカラ値の代わりにそのAST自体を処理中のノードの子として突っ込む。

こうすることで、`!include foo.yaml`と書いた箇所は、そのままYAMLを記述した場合と完全に同じになる。
結果、ファイルを分割しながら、ベースのファイルにあるエイリアスを共有することができた。
ただし、そうやって書いたファイルは単独では読み込めなくなる。

上記の実装例は見易くするために色々省略をしているが、これを利用すればERBを使わなくても環境変数で値を置き換えたり、外部のテキストファイルから内容を読み込んで差し込む、といった機能が実現できる。

あんまり独自機能をYAMLに足してしまうと、他人に分かりにくくなるので、程々にしておいた方が良いものではあるが、`TreeBuilder`を弄ることで割と簡単にYAMLのパース結果を弄れるということを覚えておくと、役に立つかもしれない。