yps 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43d89afcf4628612d4c00e6d902eb95bd92757e755b79297c72d73eac901ad53
-  data.tar.gz: e55453abcb53201a61704a790966ea0f7765e75e40856cf91f0365acd355a729
+  metadata.gz: 0aaa3d8a3ac39f8b0890701d45db64be1d9bbdad6d95d67bdf5a0bd4cac4c841
+  data.tar.gz: 9ef25972d03876b137661e62d366641c2392fd47465f6628ab2c1c99f685be65
 SHA512:
-  metadata.gz: 29070662eff8e6b0d3210d444e88466b6c8fed647c0ca9742d1b4ca5196a195b90740d154836d8439eec89117fbcbfd99f1a67bab6d627c18508a7add5e754d1
-  data.tar.gz: aa948cb48fac9b1b83b306c093fa8df9c573b676928a00848fd7e8c03a012fab040f2829b2e2ac584ee103ff3018be9e22c2f34645e985606a67a3731bd45bc6
+  metadata.gz: 64f564d9d9e5509cccf28cbcb274f8bb2bab852b5e00d87954c11564cf22b20e9b24073a11b78a7ac6fa5d3a2255830245b42ac3b30cde8005c5441d28684048
+  data.tar.gz: 75f09a3bf9c5eab84240c14fd0a28d2386f3c58aa31a33b2cd4add9244a6e6184e64368aa65dfb27eefb1150e2d3d46c4cec1fddd6002356f5e45caed2975cae

data/README.md

@@ -7,7 +7,7 @@
 
 # YPS: YAML Positioning System
 
-YPS is a gem to parse YAML and add position information (file name, line and column) to each parsed elements.
+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
@@ -26,12 +26,33 @@ 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).
+You can use the methods below to load YAML content into Ruby objects with position information (file name, line, and column).
 
-* `YPS.safe_load`/`YPS.load`
-    * Load the given YAML string into Ruby objects with position information.
-* `YPS.safe_load_file`/`YPS.load_file`
-    * Load the YAML code read from the given file path into Ruby objects with position information.
+* Load the given YAML string into Ruby objects with position information
+    * `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.
@@ -57,14 +78,66 @@ yaml['children'].each do |child|
     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.
+
+```ruby
+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](https://taichi-ishitani.github.io/yps/).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/taichi-ishitani/yps.
 
 * [Issue Tracker](https://github.com/taichi-ishitani/yps/issues)
-* [Pull Requesst](https://github.com/taichi-ishitani/yps/pulls)
+* [Pull Request](https://github.com/taichi-ishitani/yps/pulls)
 * [Discussion](https://github.com/taichi-ishitani/yps/discussions)
 
 ## Copyright & License

data/lib/yps/parser.rb

@@ -25,6 +25,10 @@ module YPS # :nodoc: all
   end
 
   class Parser < Psych::Parser
+    def self.parse(yaml, filename, &)
+      new(&).parse(yaml, filename)
+    end
+
     def initialize(&)
       super(Handler.new(&))
     end

data/lib/yps/version.rb

@@ -2,5 +2,5 @@
 
 module YPS
   # The version of YPS
-  VERSION = '0.1.0'
+  VERSION = '1.0.0'
 end

data/lib/yps/visitor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module YPS # :nodoc: all
+  module Visitor
+    using NodeExtension
+
+    module Common
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        scanner, class_loader, unwrapped_classes, value_class,
+        symbolize_names:, freeze:
+      )
+        super(scanner, class_loader, symbolize_names:, freeze:)
+        @unwrapped_classes = unwrapped_classes
+        @value_class = value_class
+      end
+
+      def accept(node)
+        object = super
+        if unwrap?(object, node)
+          object
+        else
+          create_wrapped_object(object, node)
+        end
+      end
+
+      private
+
+      def create_wrapped_object(object, node)
+        pos = Position.new(node.filename, node.start_line + 1, node.start_column + 1)
+        obj = @value_class.new(object, pos)
+        @freeze && obj.freeze || obj
+      end
+
+      def unwrap?(object, node)
+        node.document? ||
+          node.mapping_key? ||
+          @unwrapped_classes.any? { |klass| object.instance_of?(klass) }
+      end
+    end
+
+    class ToRuby < Psych::Visitors::ToRuby
+      include Common
+    end
+
+    class NoAliasRuby < Psych::Visitors::NoAliasRuby
+      include Common
+    end
+
+    def self.create( # rubocop:disable Metrics/ParameterLists
+      permitted_classes, permitted_symbols, unwrapped_classes,
+      aliases, symbolize_names, freeze, strict_integer, value_class
+    )
+      class_loader = Psych::ClassLoader::Restricted.new(
+        permitted_classes.map(&:to_s), permitted_symbols.map(&:to_s)
+      )
+      scanner =
+        if RUBY_VERSION >= '3.2.0'
+          Psych::ScalarScanner.new(class_loader, strict_integer:)
+        else
+          Psych::ScalarScanner.new(class_loader)
+        end
+      (aliases && ToRuby || NoAliasRuby)
+        .new(scanner, class_loader, unwrapped_classes, value_class, symbolize_names:, freeze:)
+    end
+  end
+end

data/lib/yps.rb

@@ -7,7 +7,7 @@ require_relative 'yps/version'
 require_relative 'yps/value'
 require_relative 'yps/node_extension'
 require_relative 'yps/parser'
-require_relative 'yps/visitors'
+require_relative 'yps/visitor'
 
 ##
 # = YPS: YAML Positioning Sysmte
@@ -22,6 +22,8 @@ module YPS
     # Safely load the YAML string in +yaml+ and add position information (file name line and column)
     # to each parsed objects except for hash keys.
     #
+    # Load the 1st documetns only if the given YAML contains multiple documents.
+    #
     # Parsed objects will be wrapped by YPS::Value class to add the accessor returning the position information.
     # You can use the +value_class+ to specify your own wrapper class.
     #
@@ -35,6 +37,9 @@ module YPS
     #   Array containing additional classes allowed to be loaded.
     # +permitted_symbols+::
     #   Array containing Symbols allowed to be loaded. By default, any symbol can be loaded.
+    # +unwrapped_classes+::
+    #   Array containing classes whose objects are not wrapped with the wrapper class.
+    #   By default, all objects are wrapped.
     # +aliases+::
     #   Aliases can be used if set to true. By default, aliases are not allowed.
     # +filename+::
@@ -55,31 +60,20 @@ module YPS
     # See also Psych.safe_load[https://docs.ruby-lang.org/en/master/Psych.html#method-c-safe_load].
     def safe_load( # rubocop:disable Metrics/ParameterLists
       yaml,
-      permitted_classes: [], permitted_symbols: [], aliases: false,
-      filename: nil, fallback: nil, symbolize_names: false, freeze: false,
-      strict_integer: false, value_class: Value
+      permitted_classes: [], permitted_symbols: [], unwrapped_classes: [],
+      aliases: false, filename: nil, fallback: nil, symbolize_names: false,
+      freeze: false, strict_integer: false, value_class: Value
     )
-      result = parse(yaml, filename)
-      return fallback unless result
-
-      class_loader =
-        Psych::ClassLoader::Restricted.new(
-          permitted_classes.map(&:to_s), permitted_symbols.map(&:to_s)
-        )
-      scanner =
-        if RUBY_VERSION >= '3.2.0'
-          Psych::ScalarScanner.new(class_loader, strict_integer:)
-        else
-          Psych::ScalarScanner.new(class_loader)
-        end
-      visitor =
-        if aliases
-          Visitors::ToRuby.new(scanner, class_loader, value_class, symbolize_names:, freeze:)
-        else
-          Visitors::NoAliasRuby.new(scanner, class_loader, value_class, symbolize_names:, freeze:)
-        end
+      Parser.parse(yaml, filename) do |node|
+        visitor =
+          Visitor.create(
+            permitted_classes, permitted_symbols, unwrapped_classes,
+            aliases, symbolize_names, freeze, strict_integer, value_class
+          )
+        return visitor.accept(node)
+      end
 
-      visitor.accept(result)
+      fallback
     end
 
     ##
@@ -95,9 +89,7 @@ module YPS
     #
     # See also YPS.safe_load
     def safe_load_file(filename, **kwargs)
-      File.open(filename, 'r:bom|utf-8') do |f|
-        safe_load(f, filename:, **kwargs)
-      end
+      open_file(filename) { |f| safe_load(f, filename:, **kwargs) }
     end
 
     ##
@@ -105,19 +97,67 @@ module YPS
     #
     # See also YPS.load
     def load_file(filename, **kwargs)
-      File.open(filename, 'r:bom|utf-8') do |f|
-        load(f, filename:, **kwargs)
+      open_file(filename) { |f| load(f, filename:, **kwargs) }
+    end
+
+    DEFAULT_VALUE = Object.new.freeze
+    private_constant :DEFAULT_VALUE
+
+    ##
+    # Similar to +YPS.safe_load+, but load all documents given in +yaml+ and return them as a list.
+    #
+    # See also YPS.safe_load
+    def safe_load_stream( # rubocop:disable Metrics/ParameterLists
+      yaml,
+      permitted_classes: [], permitted_symbols: [], unwrapped_classes: [],
+      aliases: false, filename: nil, fallback: DEFAULT_VALUE, symbolize_names: false,
+      freeze: false, strict_integer: false, value_class: Value
+    )
+      visitor = nil
+      results = []
+      Parser.parse(yaml, filename) do |node|
+        visitor ||=
+          Visitor.create(
+            permitted_classes, permitted_symbols, unwrapped_classes,
+            aliases, symbolize_names, freeze, strict_integer, value_class
+          )
+        results << visitor.accept(node)
       end
+      return fallback if results.empty? && !fallback.equal?(DEFAULT_VALUE)
+
+      results
     end
 
-    private
+    ##
+    # Similar to +YPS.safe_load_sream+, but Symbol is allowed to be loaded by default.
+    #
+    # See also YPS.safe_load_stream
+    def load_stream(yaml, permitted_classes: [Symbol], **kwargs)
+      safe_load_stream(yaml, permitted_classes:, **kwargs)
+    end
 
-    def parse(yaml, filename)
-      Parser
-        .new { |node| return node }
-        .parse(yaml, filename)
+    ##
+    # Similar to +YPS.safe_load_stream+,
+    # but the YAML string is read from the file specified by the +filename+ argument.
+    #
+    # See also YPS.safe_load_stream
+    def safe_load_stream_file(filename, **kwargs)
+      open_file(filename) { |f| safe_load_stream(f, filename:, **kwargs) }
+    end
+
+    ##
+    # Similar to +YPS.load_stream+,
+    # but the YAML string is read from the file specified by the +filename+ argument.
+    #
+    # See also YPS.load_stream
+    def load_stream_file(filename, **kwargs)
+      open_file(filename) { |f| load_stream(f, filename:, **kwargs) }
+    end
+
+    private
 
-      false
+    def open_file(filename, &)
+      File.open(filename, 'r:bom|utf-8', &)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yps
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Taichi Ishitani
@@ -29,14 +29,17 @@ files:
 - lib/yps/parser.rb
 - lib/yps/value.rb
 - lib/yps/version.rb
-- lib/yps/visitors.rb
+- lib/yps/visitor.rb
 homepage: https://github.com/taichi-ishitani/yps
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/taichi-ishitani/yps/issues
+  changelog_uri: https://github.com/taichi-ishitani/yps/releases
+  documentation_uri: https://taichi-ishitani.github.io/yps/
   homepage_uri: https://github.com/taichi-ishitani/yps
-  source_code_uri: https://github.com/taichi-ishitani/yps
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/taichi-ishitani/yps
 rdoc_options:
 - "--main"
 - README.md
@@ -57,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: 'YPS: YAML Positioning System'
 test_files: []

data/lib/yps/visitors.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module YPS # :nodoc: all
-  module Visitors
-    using NodeExtension
-
-    module Common
-      def initialize(scanner, class_loader, value_class, symbolize_names:, freeze:)
-        super(scanner, class_loader, symbolize_names:, freeze:)
-        @value_class = value_class
-      end
-
-      def accept(node)
-        object = super
-        create_wrapped_object(object, node)
-      end
-
-      private
-
-      def create_wrapped_object(object, node)
-        return object if node.document? || node.mapping_key?
-
-        pos = Position.new(node.filename, node.start_line + 1, node.start_column + 1)
-        obj = @value_class.new(object, pos)
-        @freeze && obj.freeze || obj
-      end
-    end
-
-    class ToRuby < Psych::Visitors::ToRuby
-      include Common
-    end
-
-    class NoAliasRuby < Psych::Visitors::NoAliasRuby
-      include Common
-    end
-  end
-end