YPS: YAML Positioning System¶ ↑

YPS is a gem to parse YAML and add position information (file name, line and column) to each parsed elements. This is useful for error reporting and debugging, allowing developers to precisely locate an issue within the original YAML file.

Installation¶ ↑

Install the gem and add to the application’s Gemfile by executing:

bundle add yps

If bundler is not being used to manage dependencies, install the gem by executing:

gem install yps

Usage¶ ↑

You can use the methods below to load a YAML code into Ruby objects with their position information (file name, line, and column).

YPS.safe_load/YPS.load/YPS.safe_load_stream/YPS.load_stream
- Load the given YAML string into Ruby objects with position information.
YPS.safe_load_file/YPS.load_file/YPS.safe_load_stream_file/YPS.load_stream_file
- Load the YAML code read from the given file path into Ruby objects with position information.

For a YAML code that contains multiple documents, following methods load the 1st document only.

On the other hand, following methods load all given documents and return them as a list.

Parsed objects, except for hash keys, have their own position information. You can use the position method to get position information in the original YAML of the receiver object.

require 'yps'

yaml = YPS.load(<<~'YAML')
children:
  - name: kanta
    age: 8
  - name: kaede
    age: 3
YAML

# output
# name: kanta (filename: unknown line 2 column 11)
# age: 8 (filename: unknown line 3 column 10)
# name: kaede (filename: unknown line 4 column 11)
# age: 3 (filename: unknown line 5 column 10)
yaml['children'].each do |child|
  child.each do |key, value|
    puts "#{key}: #{value} (#{value.position})"
  end
end

yaml = YPS.load_stream(<<~'YAML')
- 0
- 1
---
- foo
- bar
YAML

# output
# 0 (filename: unknown line 1 column 3)
# 1 (filename: unknown line 2 column 3)
# foo (filename: unknown line 4 column 3)
# bar (filename: unknown line 5 column 3)
yaml.each do |list|
  list.each do |item|
    puts "#{item} (#{item.position})"
  end
end

For more details about these APIs, please visit here.

Contributing¶ ↑

Bug reports and pull requests are welcome on GitHub at github.com/taichi-ishitani/yps.

Copyright & License¶ ↑

Code of Conduct¶ ↑

Everyone interacting in the YPS project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.