yps 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcd62aefae6b26fa2093fc9c156c016a52a60d9c8d8d91898901031cfc283580
-  data.tar.gz: 51d5d6b8ffa294355bbdf66d6d382931db6f8e8737bd014653bde7f5b1e87421
+  metadata.gz: 0aaa3d8a3ac39f8b0890701d45db64be1d9bbdad6d95d67bdf5a0bd4cac4c841
+  data.tar.gz: 9ef25972d03876b137661e62d366641c2392fd47465f6628ab2c1c99f685be65
 SHA512:
-  metadata.gz: 9dfe215b77ff8502f76ffe904bd7bf350fd0f38c1ff6ba75ed97feba8cb2600d19830dcf4912fcbc97d7ada69d2cc365971acde95052760ebcf94fa957da8399
-  data.tar.gz: b48ee98f7435e2fa1991b1a607833ee873a841d96b8056c74256103a32206e4e943979df9fc6d4a4365764f6fff092f9cc9ad7b51ae9036ee2ecb3977c03c1b3
+  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,25 +26,32 @@ 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`/`YPS.safe_load_stram`/`YPS.load_stream`
-    * Load the given YAML string into Ruby objects with position information.
-* `YPS.safe_load_file`/`YPS.load_file`/`YPS.safe_load_stram_file`/`YPS.load_stream_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`
 
-For a YAML code that contains multiple documents, folowing methods load the 1st document only.
+* 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`
 
-On the other hand, following methods load all given documents and return them as a list.
+In contrast, the following methods load all documents and return them as a list.
 
-* `YPS.safe_load_stram`
+* `YPS.safe_load_stream`
 * `YPS.load_stream`
-* `YPS.safe_load_stram_file`
+* `YPS.safe_load_stream_file`
 * `YPS.load_stream_file`
 
 Parsed objects, except for hash keys, have their own position information.
@@ -92,12 +99,45 @@ yaml.each do |list|
 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/version.rb

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

data/lib/yps/visitor.rb

@@ -5,25 +5,37 @@ module YPS # :nodoc: all
     using NodeExtension
 
     module Common
-      def initialize(scanner, class_loader, value_class, symbolize_names:, freeze:)
+      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
-        create_wrapped_object(object, node)
+        if unwrap?(object, node)
+          object
+        else
+          create_wrapped_object(object, node)
+        end
       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
+
+      def unwrap?(object, node)
+        node.document? ||
+          node.mapping_key? ||
+          @unwrapped_classes.any? { |klass| object.instance_of?(klass) }
+      end
     end
 
     class ToRuby < Psych::Visitors::ToRuby
@@ -35,8 +47,8 @@ module YPS # :nodoc: all
     end
 
     def self.create( # rubocop:disable Metrics/ParameterLists
-      permitted_classes, permitted_symbols, aliases,
-      symbolize_names, freeze, strict_integer, value_class
+      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)
@@ -48,7 +60,7 @@ module YPS # :nodoc: all
           Psych::ScalarScanner.new(class_loader)
         end
       (aliases && ToRuby || NoAliasRuby)
-        .new(scanner, class_loader, value_class, symbolize_names:, freeze:)
+        .new(scanner, class_loader, unwrapped_classes, value_class, symbolize_names:, freeze:)
     end
   end
 end

data/lib/yps.rb

@@ -37,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+::
@@ -57,15 +60,15 @@ 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
     )
       Parser.parse(yaml, filename) do |node|
         visitor =
           Visitor.create(
-            permitted_classes, permitted_symbols, aliases,
-            symbolize_names, freeze, strict_integer, value_class
+            permitted_classes, permitted_symbols, unwrapped_classes,
+            aliases, symbolize_names, freeze, strict_integer, value_class
           )
         return visitor.accept(node)
       end
@@ -106,8 +109,8 @@ module YPS
     # See also YPS.safe_load
     def safe_load_stream( # rubocop:disable Metrics/ParameterLists
       yaml,
-      permitted_classes: [], permitted_symbols: [], aliases: false,
-      filename: nil, fallback: DEFAULT_VALUE, symbolize_names: false,
+      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
@@ -115,8 +118,8 @@ module YPS
       Parser.parse(yaml, filename) do |node|
         visitor ||=
           Visitor.create(
-            permitted_classes, permitted_symbols, aliases,
-            symbolize_names, freeze, strict_integer, value_class
+            permitted_classes, permitted_symbols, unwrapped_classes,
+            aliases, symbolize_names, freeze, strict_integer, value_class
           )
         results << visitor.accept(node)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yps
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Taichi Ishitani
@@ -60,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: []