YPS: YAML Positioning System

YPS is a gem that parses YAML and adds position information (file name, line, and column) to each parsed element. 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 YAML content into Ruby objects with position information (file name, line, and column).

• Load the given YAML string into Ruby objects with position information

  • YPS.safe_load

  • YPS.load

  • YPS.safe_load_stream

  • YPS.load_stream

  • YPS.safe_load

  • YPS.load

  • YPS.safe_load_stream

  • YPS.load_stream

• Load the YAML read from the given file path into Ruby objects with position information

  • YPS.safe_load_file

  • YPS.load_file

  • YPS.safe_load_stream_file

  • YPS.load_stream_file

For YAML that contains multiple documents, the following methods load only the first document.

• YPS.safe_load

• YPS.load

• YPS.safe_load_file

• YPS.load_file

In contrast, the following methods load all documents and return them as a list.

• YPS.safe_load_stream

• YPS.load_stream

• YPS.safe_load_stream_file

• YPS.load_stream_file

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

Handling of false and nil values

By default, all objects, including false and nil, are wrapped in a wrapper class. Note that wrapped false and nil values will not be treated as falsy. You can use the unwrapped_classes option to avoid this situation. Objects belonging to classes specified by this option are returned unwrapped but will not have access to their position information.

yaml = YPS.load(<<~'YAML')
- false
- null
YAML

# output
# false
# nil
puts (yaml[0] || 'foo').inspect
puts (yaml[1] || 'bar').inspect

yaml = YPS.load(<<~'YAML', unwrapped_classes: [FalseClass, NilClass])
- false
- null
YAML

# output
# "foo"
# "bar"
puts (yaml[0] || 'foo').inspect
puts (yaml[1] || 'bar').inspect

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.

• Issue Tracker

• Pull Request

• Discussion

Copyright & License

Copyright © 2025 Taichi Ishitani. YPS is licensed under the terms of the MIT License, see LICENSE.txt for further details.

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.