shale 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e3b4d27ab7e8cc9b4873dfa60b52bdbafe50c2885085c4ec77ac6887351aab1
-  data.tar.gz: 6ce71a10ebf53633930b6d5a92ebb5f736aab44c47d6910a25238209192a4b92
+  metadata.gz: 81b22181e1c63b2757fdd137f09a185caf894de6d43c108119c18c9260b48afd
+  data.tar.gz: 065bc2d6f8a6eec466b52574ed38846dc0b4e0315ba9b83fc0d24ed75066ef07
 SHA512:
-  metadata.gz: 23c3b182c72c0e1d5102eb667541caccfb56e836e636bd083027425a60a12ed39ffce1ab3540adc0659c6b1bcbcf5255d192bbdc2d39bfc10c762ee4bdaaaa1e
-  data.tar.gz: ef7481e6076cc8f426c1dd0fb002d984594cbf3d59743a31450e8989048ffdd6cdc8fc735e90b7529c1935d7251c6751e70f7c3734d5c3f7df4b8124cc4b8256
+  metadata.gz: 9b106ac74372bc089093ee8c12238b48505cff4d318967e2760ef2842e9a783125227177fd5f2cb47b27872adc7cbbf0686226934132b5c8f346c71b92159c8a
+  data.tar.gz: dcb0088d6f700f1654313a72156e9d1e4cd0c1b75b99a82cea17e12af96ced1407e358b1d0cc52e7e3f0a1c46cb19d702b3a49628a0da67e521a20906e006a6c

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [1.2.0] - 2024-10-31
+
+### Added
+- Allow to pass adapter specific options
+- Allow to pass `additional_properties` option to JSON Schema generator
+- Allow to pass `description` option to JSON Schema generator
+- Support for symbol type aliases in attribute mappings
+
+## [1.1.0] - 2024-02-17
+
+### Added
+- [bkjohnson] Add support for JSON Schema validation keywords (#29)
+- Add support for Ruby 3.3
+
+### Changed
+- Drop support for Ruby 2.6 and Ruby 2.7
+
+### Fixed
+- Fix Ox adapter incorrectly handling documents with XML declaration
+
 ## [1.0.0] - 2023-07-15
 
 ### Added

data/README.md

@@ -17,7 +17,7 @@ Documentation with interactive examples is available at [Shale website](https://
 
 ## Installation
 
-Shale supports Ruby (MRI) 2.6+
+Shale supports Ruby (MRI) 3.0+
 
 Add this line to your application's Gemfile:
 
@@ -65,6 +65,7 @@ $ gem install shale
 * [Using methods to extract and generate data](#using-methods-to-extract-and-generate-data)
 * [Delegating fields to child attributes](#delegating-fields-to-child-attributes)
 * [Additional options](#additional-options)
+* [Overriding attribute methods](#overriding-attribute-methods)
 * [Using custom models](#using-custom-models)
 * [Supported types](#supported-types)
 * [Writing your own type](#writing-your-own-type)
@@ -82,17 +83,17 @@ $ gem install shale
 require 'shale'
 
 class Address < Shale::Mapper
-  attribute :city, Shale::Type::String
-  attribute :street, Shale::Type::String
-  attribute :zip, Shale::Type::String
+  attribute :city, :string
+  attribute :street, :string
+  attribute :zip, :string
 end
 
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
-  attribute :age, Shale::Type::Integer
-  attribute :married, Shale::Type::Boolean, default: -> { false }
-  attribute :hobbies, Shale::Type::String, collection: true
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
+  attribute :married, :boolean, default: -> { false }
+  attribute :hobbies, :string, collection: true
   attribute :address, Address
 end
 ```
@@ -208,8 +209,8 @@ person.to_yaml
 ### Converting TOML to object
 
 To use TOML with Shale you have to set adapter you want to use.
-Out of the box Shale suports [Tomlib](https://github.com/kgiszczak/tomlib).
-It also comes with adapter for [toml-rb](https://github.com/emancu/toml-rb) if you prefer that.
+It comes with adapters for [Tomlib](https://github.com/kgiszczak/tomlib) and
+[toml-rb](https://github.com/emancu/toml-rb).
 For details see [Adapters](#adapters) section.
 
 To set it, first make sure Tomlib gem is installed:
@@ -221,8 +222,8 @@ $ gem install tomlib
 then setup adapter:
 
 ```ruby
-require 'tomlib'
-Shale.toml_adapter = Tomlib
+require 'sahle/adapter/tomlib'
+Shale.toml_adapter = Shale::Adapter::Tomlib
 
 # Alternatively if you'd like to use toml-rb, use:
 require 'shale/adapter/toml_rb'
@@ -353,6 +354,25 @@ person.to_xml
 
 ### Converting CSV to object
 
+To use CSV with Shale you have to set adapter.
+Shale comes with adapter for [csv](https://github.com/ruby/csv).
+For details see [Adapters](#adapters) section.
+
+To set it, first make sure CSV gem is installed:
+
+```
+$ gem install csv
+```
+
+then setup adapter:
+
+```ruby
+require 'shale/adapter/csv'
+Shale.csv_adapter = Shale::Adapter::CSV
+```
+
+Now you can use CSV with Shale.
+
 CSV represents a flat data structure, so you can't map properties to complex types directly,
 but you can use methods to map properties to complex types
 (see [Using methods to extract and generate data](#using-methods-to-extract-and-generate-data)
@@ -423,8 +443,8 @@ By default keys are named the same as attributes. To use custom keys use:
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 
   json do
     map 'firstName', to: :first_name
@@ -437,8 +457,8 @@ end
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 
   yaml do
     map 'firstName', to: :first_name
@@ -451,8 +471,8 @@ end
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 
   toml do
     map 'firstName', to: :first_name
@@ -469,8 +489,8 @@ to `:first_name` attribute and the second column to `:last_name`.
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 
   csv do
     map 'firstName', to: :first_name
@@ -483,8 +503,8 @@ end
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 
   hsh do
     map 'firstName', to: :first_name
@@ -499,9 +519,9 @@ XML is more complicated format than JSON or YAML. To map elements, attributes an
 
 ```ruby
 class Address < Shale::Mapper
-  attribute :street, Shale::Type::String
-  attribute :city, Shale::Type::String
-  attribute :zip, Shale::Type::String
+  attribute :street, :string
+  attribute :city, :string
+  attribute :zip, :string
 
   xml do
     map_content to: :street
@@ -511,10 +531,10 @@ class Address < Shale::Mapper
 end
 
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
-  attribute :age, Shale::Type::Integer
-  attribute :hobbies, Shale::Type::String, collection: true
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
+  attribute :hobbies, :string, collection: true
   attribute :address, Address
 
   xml do
@@ -553,7 +573,7 @@ You can use `cdata: true` option on `map_element` and `map_content` to handle CD
 
 ```ruby
 class Address < Shale::Mapper
-  attribute :content, Shale::Type::String
+  attribute :content, :string
 
   xml do
     map_content to: :content, cdata: true
@@ -561,7 +581,7 @@ class Address < Shale::Mapper
 end
 
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
+  attribute :first_name, :string
   attribute :address, Address
 
   xml do
@@ -587,9 +607,9 @@ To map namespaced elements and attributes use `namespace` and `prefix` propertie
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
-  attribute :age, Shale::Type::Integer
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
 
   xml do
     root 'person'
@@ -614,11 +634,11 @@ explicitly declare it on `map_attribute`).
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :middle_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
-  attribute :age, Shale::Type::Integer
-  attribute :hobby, Shale::Type::String
+  attribute :first_name, :string
+  attribute :middle_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
+  attribute :hobby, :string
 
   xml do
     root 'person'
@@ -654,9 +674,9 @@ For CSV the default is to render `nil` elements.
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
-  attribute :age, Shale::Type::Integer
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
 
   json do
     map 'first_name', to: :first_name, render_nil: true
@@ -704,9 +724,9 @@ class Base < Shale::Mapper
 end
 
 class Person < Base
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
-  attribute :age, Shale::Type::Integer
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
 
   json do
     # override default from Base class
@@ -723,8 +743,8 @@ end
 
 ```ruby
 class Person < Base
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 
   json do
     render_nil false
@@ -743,9 +763,9 @@ you can use methods to do so:
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :hobbies, Shale::Type::String, collection: true
-  attribute :street, Shale::Type::String
-  attribute :city, Shale::Type::String
+  attribute :hobbies, :string, collection: true
+  attribute :street, :string
+  attribute :city, :string
 
   json do
     map 'hobbies', using: { from: :hobbies_from_json, to: :hobbies_to_json }
@@ -834,7 +854,7 @@ You can also pass a `context` object that will be available in extractor/generat
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :password, Shale::Type::String
+  attribute :password, :string
 
   json do
     map 'password', using: { from: :password_from_json, to: :password_to_json }
@@ -864,7 +884,7 @@ If you want to work on multiple elements at a time you can group them using `gro
 
 ```ruby
 class Person < Shale::Mapper
-  attribute :name, Shale::Type::String
+  attribute :name, :string
 
   json do
     group from: :name_from_json, to: :name_to_json do
@@ -915,12 +935,12 @@ To delegate fields to child complex types you can use `receiver: :child` declara
 
 ```ruby
 class Address < Shale::Mapper
-  attribute :city, Shale::Type::String
-  attribute :street, Shale::Type::String
+  attribute :city, :string
+  attribute :street, :string
 end
 
 class Person < Shale::Mapper
-  attribute :name, Shale::Type::String
+  attribute :name, :string
   attribute :address, Address
 
   json do
@@ -1040,8 +1060,8 @@ names and shouldn't be included in the returned collection. It also accepts all
 
 ```ruby
 class Person
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
 end
 
 people = Person.from_csv(<<~DATA, headers: true, col_sep: '|')
@@ -1066,6 +1086,63 @@ Person.to_csv(people, headers: true, col_sep: '|')
 # James|Sixpack
 ```
 
+Most adapters accept options specific to them. Eg. if you want to be able to work
+with NaN values in JSON:
+
+```ruby
+class Person
+  attribute :age, :float
+end
+
+person = Person.from_json('{"age": NaN}', allow_nan: true)
+
+# =>
+#
+# #<Person:0x0000000113d7a488 @age=Float::NAN>
+
+Person.to_json(person, allow_nan: true)
+
+# =>
+#
+# {
+#   "age": NaN
+# }
+```
+
+### Overriding attribute methods
+
+It's possible to override an attribute method to change its output:
+
+```ruby
+class Person < Shale::Mapper
+  attribute :gender, :string
+
+  def gender
+    if super == 'm'
+      'male'
+    else
+      'female'
+    end
+  end
+end
+
+puts Person.from_json('{"gender":"m"}')
+
+# =>
+#
+# #<Person:0x00007f9bc3086d60
+#  @gender="male">
+```
+
+Be conscious that the original attribute value will be lost after its transformation though:
+
+```ruby
+puts User.from_json('{"gender":"m"}').to_json
+# => {"gender":"male"}
+```
+
+It'll no longer return gender `m`.
+
 ### Using custom models
 
 By default Shale combines mapper and model into one class. If you want to use your own classes
@@ -1083,15 +1160,15 @@ end
 class AddressMapper < Shale::Mapper
   model Address
 
-  attribute :street, Shale::Type::String
-  attribute :city, Shale::Type::String
+  attribute :street, :string
+  attribute :city, :string
 end
 
 class PersonMapper < Shale::Mapper
   model Person
 
-  attribute :first_name, Shale::Type::String
-  attribute :last_name, Shale::Type::String
+  attribute :first_name, :string
+  attribute :last_name, :string
   attribute :address, AddressMapper
 end
 
@@ -1131,12 +1208,21 @@ PersonMapper.to_json(person, pretty: true)
 
 Shale supports these types out of the box:
 
-- `Shale::Type::Boolean`
-- `Shale::Type::Date`
-- `Shale::Type::Float`
-- `Shale::Type::Integer`
-- `Shale::Type::String`
-- `Shale::Type::Time`
+- `:boolean` (`Shale::Type::Boolean`)
+- `:date` (`Shale::Type::Date`)
+- `:float` (`Shale::Type::Float`)
+- `:integer` (`Shale::Type::Integer`)
+- `:string` (`Shale::Type::String`)
+- `:time` (`Shale::Type::Time`)
+
+The symbol type alias and the type class are interchangeable:
+
+```ruby
+class Person < Shale::Mapper
+  attribute :age, Shale::Type::Integer
+  # attribute :age, :integer
+end
+```
 
 ### Writing your own type
 
@@ -1152,10 +1238,35 @@ class MyIntegerType < Shale::Type::Value
 end
 ```
 
+Then you can use it in your model:
+
+```ruby
+class Person < Shale::Mapper
+  attribute :age, MyIntegerType
+end
+```
+
+You can also register your own type with a symbol alias if you
+intend to use it often.
+
+```ruby
+require 'shale/type'
+
+Shale::Type.register(:my_integer, MyIntegerType)
+```
+
+Then you can use it like this:
+
+```ruby
+class Person < Shale::Mapper
+  attribute :age, :my_integer
+end
+```
+
 ### Adapters
 
 Shale uses adapters for parsing and generating documents.
-By default Ruby's standard JSON, YAML, CSV parsers are used for handling JSON YAML, CSV documents.
+By default Ruby's standard JSON and YAML parsers are used for handling JSON and YAML documents.
 
 You can change it by providing your own adapter. For JSON, YAML, TOML and CSV adapter must
 implement `.load` and `.dump` class methods.
@@ -1183,6 +1294,14 @@ require 'shale/adapter/toml_rb'
 Shale.toml_adapter = Shale::Adapter::TomlRB
 ```
 
+To handle CSV documents you have to set CSV adapter. Shale provides adapter for `csv` parser:
+
+```ruby
+require 'shale'
+require 'shale/adapter/csv'
+Shale.csv_adapter = Shale::Adapter::CSV
+```
+
 To handle XML documents you have to explicitly set XML adapter.
 Shale provides adapters for most popular Ruby XML parsers:
 
@@ -1288,6 +1407,81 @@ end
 Shale::Schema::JSONGenerator.register_json_type(MyEmailType, MyEmailJSONType)
 ```
 
+To add validation keywords to the schema, you can use a custom model and do this:
+
+```ruby
+require 'shale/schema'
+
+class PersonMapper < Shale::Mapper
+  model Person
+
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :address, :string
+  attribute :age, :integer
+
+  json do
+    properties max_properties: 5, additional_properties: false
+
+    map "first_name", to: :first_name, schema: { required: true }
+    map "last_name", to: :last_name, schema: { required: true }
+    map "address", to: :address, schema: { max_length: 128, description: "Street, home number, city and country" }
+    map "age", to: :age, schema: { minimum: 1, maximum: 150, description: "Person age" }
+  end
+end
+
+Shale::Schema.to_json(
+  PersonMapper,
+  pretty: true
+)
+
+# =>
+#
+# {
+#   "$schema": "https://json-schema.org/draft/2020-12/schema",
+#   "description": "My description",
+#   "$ref": "#/$defs/Person",
+#   "$defs": {
+#     "Person": {
+#       "type": "object",
+#       "properties": {
+#         "first_name": {
+#           "type": "string"
+#         },
+#         "last_name": {
+#           "type": "string"
+#         },
+#         "address": {
+#           "type": [
+#             "string",
+#             "null"
+#           ],
+#           "maxLength": 128,
+#           "description": "Street, home number, city and country"
+#         },
+#         "age": {
+#           "type": [
+#             "integer",
+#             "null"
+#           ],
+#           "minimum": 1,
+#           "maximum": 150,
+#           "description": "Person age"
+#         }
+#       },
+#       "required": [
+#         "first_name",
+#         "last_name"
+#       ],
+#       "maxProperties": 5,
+#       "additionalProperties": false
+#     }
+#   }
+# }
+```
+
+Validation keywords are supported for all types, only the global `enum` and `const` types are not supported.
+
 ### Compiling JSON Schema into Shale model
 
 :warning: Only **[Draft 2020-12](https://json-schema.org/draft/2020-12/schema)** JSON Schema is supported

data/lib/shale/adapter/json.rb

@@ -11,27 +11,30 @@ module Shale
       # Parse JSON into Hash
       #
       # @param [String] json JSON document
+      # @param [Hash] options
       #
       # @return [Hash]
       #
       # @api private
-      def self.load(json)
-        ::JSON.parse(json)
+      def self.load(json, **options)
+        ::JSON.parse(json, **options)
       end
 
       # Serialize Hash into JSON
       #
       # @param [Hash] obj Hash object
-      # @param [true, false] pretty
+      # @param [Hash] options
       #
       # @return [String]
       #
       # @api private
-      def self.dump(obj, pretty: false)
-        if pretty
-          ::JSON.pretty_generate(obj)
+      def self.dump(obj, **options)
+        json_options = options.except(:pretty)
+
+        if options[:pretty]
+          ::JSON.pretty_generate(obj, **json_options)
         else
-          ::JSON.generate(obj)
+          ::JSON.generate(obj, **json_options)
         end
       end
     end

data/lib/shale/adapter/nokogiri.rb

@@ -61,7 +61,7 @@ module Shale
         result = doc.to_xml(save_with: save_with)
 
         unless pretty
-          result = result.sub(/\n/, '')
+          result = result.sub("\n", '')
         end
 
         result

data/lib/shale/adapter/ox.rb

@@ -22,7 +22,8 @@ module Shale
       #
       # @api private
       def self.load(xml)
-        Node.new(::Ox.parse(xml))
+        element = ::Ox.parse(xml)
+        Node.new(element.respond_to?(:root) ? element.root : element)
       rescue ::Ox::ParseError => e
         raise ParseError, "Document is invalid: #{e.message}"
       end

data/lib/shale/adapter/toml_rb.rb

@@ -4,29 +4,31 @@ require 'toml-rb'
 
 module Shale
   module Adapter
-    # TOML adapter
+    # TomlRB adapter
     #
     # @api public
     class TomlRB
       # Parse TOML into Hash
       #
       # @param [String] toml TOML document
+      # @param [Hash] options
       #
       # @return [Hash]
       #
       # @api private
-      def self.load(toml)
+      def self.load(toml, **_options)
         ::TomlRB.parse(toml)
       end
 
       # Serialize Hash into TOML
       #
       # @param [Hash] obj Hash object
+      # @param [Hash] options
       #
       # @return [String]
       #
       # @api private
-      def self.dump(obj)
+      def self.dump(obj, **_options)
         ::TomlRB.dump(obj)
       end
     end