yaml-schema 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7079554145bf81aef3f0fb89dfa5ad5e0867336866989da48e9217cbae1f114
-  data.tar.gz: e6bc2b714f98cce44632e17fc6b9d4d8bbaebea4583427897019ce8d28f81293
+  metadata.gz: df10b8348eda9fb9eb5d36af1119234e00b48a4d1e5ef7f104d9fade49f02493
+  data.tar.gz: 0d208c8b1883843586bd30c9de3cb5cafb6a65e8978eb495902d34e5c660462f
 SHA512:
-  metadata.gz: 347fe6c4f3a01eefc61b4f6a18570893c472fa815f942b9ec57ac9ccd8abd6d7f06d73b0f757dd38dee5c9da5f6e01d8c4dd76e5e726d4b92aa0e4a966126f89
-  data.tar.gz: 62a7ec295631d838f06c8932f4c1ae614650cfb635b1bd9bb2539425a53575e1bf87a9af748d1632e082c0f25dc93c7cc311173300c5bf47bfbf3cd11dbc6d41
+  metadata.gz: f345acb0e18034d923671d42507b3851a9735a41254e9bbd34caf2b6c9f89007e161fdf6b65844bd69528c40488db44ff341894aba73522622beae059d7c56c2
+  data.tar.gz: 847b358731e0a6acaa24964bed4d58849ccc3da6e6440b95ff143396e16f79adeadd58b0a1a00f1cbf7d61ce6ec7eaff231a18653a0693170f671d07d3abaf78

data/.github/workflows/ci.yml

@@ -7,6 +7,8 @@ on:
 jobs:
   ruby-versions:
     uses: ruby/actions/.github/workflows/ruby_versions.yml@master
+    with:
+      engine: cruby
 
   test:
     needs: ruby-versions

data/README.md

@@ -11,14 +11,14 @@ A library for validating YAML documents against a schema.
 ### Basic Validation
 
 ```ruby
-require 'yaml-schema'
+require "yaml-schema"
 
 schema = {
-  type: 'object',
-  properties: {
-    name: { type: 'string' },
-    age: { type: 'integer' },
-    active: { type: 'boolean' }
+  "type" => "object",
+  "properties" => {
+    "name" => { "type" => "string" },
+    "age" => { "type" => "integer" },
+    "active" => { "type" => "boolean" }
   }
 }
 
@@ -53,9 +53,9 @@ Specify multiple valid types for a field:
 
 ```ruby
 schema = {
-  type: 'object',
-  properties: {
-    value: { type: ['null', 'string'] }
+  "type" => "object",
+  "properties" => {
+    "value" => { "type" => ["null", "string"] }
   }
 }
 ```
@@ -64,17 +64,17 @@ schema = {
 
 ```ruby
 schema = {
-  type: 'object',
-  properties: {
-    users: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          name: { type: 'string' },
-          tags: {
-            type: 'array',
-            items: { type: 'string' }
+  "type" => "object",
+  "properties" => {
+    "users" => {
+      "type" => "array",
+      "items" => {
+        "type" => "object",
+        "properties" => {
+          "name" => { "type" => "string" },
+          "tags" => {
+            "type" => "array",
+            "items" => { "type" => "string" }
           }
         }
       }
@@ -83,6 +83,42 @@ schema = {
 }
 ```
 
+### Compiled Validators
+
+If you validate many documents against the same schema, you can compile the
+schema into a validator class specialized for it, rather than interpreting
+the schema on every call:
+
+```ruby
+PersonValidator = YAMLSchema::Compiler.compile(schema)
+
+PersonValidator.validate(node)          # raises on error, returns true otherwise
+PersonValidator.invalid?(node)          # returns the error, or false
+PersonValidator.validate(node, aliases: false)
+PersonValidator.new(node_info).validate(node)
+```
+
+Compiled validators raise the same exceptions with the same messages as
+`YAMLSchema::Validator`. The schema itself is validated at compile time.
+
+You can also generate Ruby source and check it into your project:
+
+```ruby
+File.write "person_validator.rb",
+  YAMLSchema::Compiler.to_ruby(schema, class_name: "PersonValidator")
+```
+
+Pass `standalone: true` to generate a validator that doesn't depend on
+yaml-schema at all. Stand-alone validators define their own exception classes
+(`PersonValidator::UnexpectedType`, etc., all subclasses of
+`PersonValidator::Exception`) instead of raising `YAMLSchema::Validator`
+exceptions:
+
+```ruby
+File.write "person_validator.rb",
+  YAMLSchema::Compiler.to_ruby(schema, class_name: "PersonValidator", standalone: true)
+```
+
 ## Error Handling
 
 Validation errors include detailed path information:

data/lib/yaml-schema/compiler.rb

@@ -0,0 +1,538 @@
+# frozen_string_literal: true
+
+module YAMLSchema
+  ##
+  # Base class for validators generated by YAMLSchema::Compiler.  Subclasses
+  # implement a private +_validate_root+ method that returns +nil+ when the
+  # node is valid, or an exception object describing the first error.
+  class CompiledValidator
+    UnexpectedType       = Validator::UnexpectedType
+    UnexpectedProperty   = Validator::UnexpectedProperty
+    UnexpectedTag        = Validator::UnexpectedTag
+    UnexpectedValue      = Validator::UnexpectedValue
+    UnexpectedAlias      = Validator::UnexpectedAlias
+    InvalidString        = Validator::InvalidString
+    InvalidPattern       = Validator::InvalidPattern
+    MissingRequiredField = Validator::MissingRequiredField
+
+    ##
+    # Validate +node+, raising an exception if it is invalid.
+    def self.validate node, aliases: true
+      self::INSTANCE.validate node, aliases: aliases
+    end
+
+    ##
+    # Validate +node+, returning the error if it is invalid, otherwise false.
+    def self.invalid? node, aliases: true
+      self::INSTANCE.invalid? node, aliases: aliases
+    end
+
+    def initialize node_info = Validator::NodeInfo
+      @node_info = node_info
+    end
+
+    ##
+    # Validate +node+, raising an exception if it is invalid.
+    def validate node, aliases: true
+      err = _validate_root(node, {}, [], aliases)
+      raise err if err
+      true
+    end
+
+    ##
+    # Validate +node+, returning the error if it is invalid, otherwise false.
+    def invalid? node, aliases: true
+      _validate_root(node, {}, [], aliases) || false
+    end
+
+    include Runtime
+  end
+
+  ##
+  # Compiles a schema into a Ruby class specialized for validating that
+  # schema.  The generated class behaves like YAMLSchema::Validator, but
+  # doesn't need to interpret the schema at validation time:
+  #
+  #   validator = YAMLSchema::Compiler.compile(schema)
+  #   validator.validate(node)
+  #
+  # The generated source can also be written to a file:
+  #
+  #   File.write "my_validator.rb", YAMLSchema::Compiler.to_ruby(schema, class_name: "MyValidator")
+  class Compiler
+    EMPTY_SCHEMA = {}.freeze # :nodoc:
+
+    ##
+    # Compile +schema+ and return a new validator class.
+    def self.compile schema
+      klass = Class.new(CompiledValidator)
+      klass.class_eval new(schema).body, "(yaml-schema compiled validator)", 1
+      klass
+    end
+
+    ##
+    # Compile +schema+ and return Ruby source code defining a validator
+    # class named +class_name+.
+    #
+    # By default the generated class inherits from
+    # YAMLSchema::CompiledValidator and requires this library at runtime.
+    # Pass <tt>standalone: true</tt> to generate a class with no dependency
+    # on yaml-schema.  Stand-alone validators define their own exception
+    # classes (e.g. <tt>MyValidator::UnexpectedType</tt>) rather than
+    # raising YAMLSchema::Validator exceptions.
+    def self.to_ruby schema, class_name:, standalone: false
+      body = new(schema).body
+
+      if standalone
+        body = standalone_support + "\n" + body
+        header = ""
+        superclass = ""
+      else
+        header = "\nrequire \"yaml-schema\"\n"
+        superclass = " < YAMLSchema::CompiledValidator"
+      end
+
+      <<~RUBY
+        # frozen_string_literal: true
+        # Generated by yaml-schema #{VERSION}. Do not edit.
+        #{header}
+        class #{class_name}#{superclass}
+        #{body.gsub(/^(?=.)/, "  ")}end
+      RUBY
+    end
+
+    STANDALONE_API = <<~'RUBY' # :nodoc:
+      class Exception < StandardError; end
+      class UnexpectedType < Exception; end
+      class UnexpectedProperty < Exception; end
+      class UnexpectedTag < Exception; end
+      class UnexpectedValue < Exception; end
+      class UnexpectedAlias < Exception; end
+      class InvalidString < Exception; end
+      class InvalidPattern < Exception; end
+      class MissingRequiredField < Exception; end
+
+      module NodeInfo
+        def self.read_tag node
+          node.tag
+        end
+      end
+
+      ##
+      # Validate +node+, raising an exception if it is invalid.
+      def self.validate node, aliases: true
+        INSTANCE.validate node, aliases: aliases
+      end
+
+      ##
+      # Validate +node+, returning the error if it is invalid, otherwise false.
+      def self.invalid? node, aliases: true
+        INSTANCE.invalid? node, aliases: aliases
+      end
+
+      def initialize node_info = NodeInfo
+        @node_info = node_info
+      end
+
+      ##
+      # Validate +node+, raising an exception if it is invalid.
+      def validate node, aliases: true
+        err = _validate_root(node, {}, [], aliases)
+        raise err if err
+        true
+      end
+
+      ##
+      # Validate +node+, returning the error if it is invalid, otherwise false.
+      def invalid? node, aliases: true
+        _validate_root(node, {}, [], aliases) || false
+      end
+    RUBY
+
+    # Source for everything a stand-alone validator needs: exception
+    # classes, the public API, and the shared runtime support code.
+    def self.standalone_support # :nodoc:
+      src = File.read(File.join(__dir__, "runtime.rb"))
+      runtime = src[/^[ \t]*# :runtime-begin:\n(.*?)^[ \t]*# :runtime-end:\n/m, 1] or
+        raise "runtime markers not found"
+      width = runtime.scan(/^[ \t]*(?=\S)/).map(&:length).min
+      runtime = runtime.gsub(/^[ \t]{#{width}}/, "")
+
+      STANDALONE_API + "\npublic\n\n" + runtime + "\npublic\n"
+    end
+
+    def initialize schema
+      Validator::INSTANCE.validate_schema!(schema)
+      @schema    = schema
+      @methods   = []
+      @constants = []
+      @names     = {}.compare_by_identity
+      @key_names = {}.compare_by_identity # schemas forced to "string" (property names)
+      @counter   = 0
+    end
+
+    ##
+    # Ruby source for the body of the validator class.
+    def body
+      root = schema_method(@schema, "")
+      src = +""
+      @constants.each { |c| src << c << "\n" }
+      src << "\n" unless @constants.empty?
+      src << "private\n\n"
+      src << "def _validate_root(node, aliases, path, allow_aliases)\n"
+      src << "  #{root}(node, aliases, path, allow_aliases)\n"
+      src << "end\n"
+      @methods.each { |m| src << "\n" << m }
+      src << "\npublic\n\nINSTANCE = new.freeze\n"
+      src
+    end
+
+    private
+
+    def lit str
+      str.dump
+    end
+
+    def next_name prefix
+      @counter += 1
+      "#{prefix}#{@counter}"
+    end
+
+    def indent code, n
+      pad = " " * n
+      code.gsub(/^(?=.)/, pad)
+    end
+
+    # Returns the name of a method that fully validates a node against
+    # +schema+ (alias resolution, tag lookup, and type checks).  Schemas are
+    # memoized by identity so shared sub-schemas share a method.
+    def schema_method schema, path, forced_type = nil
+      memo = forced_type ? @key_names : @names
+      return memo[schema] if memo.key?(schema)
+
+      name = memo[schema] = next_name("_v")
+      type = forced_type || schema["type"]
+
+      src = +""
+      src << "# #{path.empty? ? "/" : path}\n"
+      src << "def #{name}(node, aliases, path, allow_aliases)\n"
+      src << indent(<<~RUBY, 2)
+        if node.anchor
+          if node.alias?
+            raise UnexpectedAlias unless allow_aliases
+            node = aliases[node.anchor]
+          else
+            aliases[node.anchor] = node
+          end
+        end
+
+        tag = @node_info.read_tag(node)
+      RUBY
+
+      if Array === type
+        # Unions return the first success, or the last failure
+        type.each_with_index do |t, i|
+          tname = "#{name}_#{t}"
+          @methods << "def #{tname}(node, tag, aliases, path, allow_aliases)\n" +
+            indent(type_body(t, schema, path), 2) +
+            "end\n"
+          if i == type.length - 1
+            src << "  #{tname}(node, tag, aliases, path, allow_aliases)\n"
+          else
+            src << "  return unless #{tname}(node, tag, aliases, path, allow_aliases)\n"
+          end
+        end
+      else
+        src << indent(type_body(type, schema, path), 2)
+      end
+      src << "end\n"
+
+      @methods << src
+      name
+    end
+
+    # Code for validating +node+ (already alias-resolved, with +tag+ read)
+    # as +type+.  Returns an error with +return+, and evaluates to nil on
+    # success.
+    def type_body type, schema, path
+      src = +tag_check(type, schema)
+
+      case type
+      when "object" then src << object_body(schema, path)
+      when "array"  then src << array_body(schema, path)
+      else               src << scalar_body(type, schema)
+      end
+
+      src << "nil\n"
+    end
+
+    def tag_check type, schema
+      expected = schema["tag"] if type == "object"
+
+      if expected
+        <<~RUBY
+          unless tag == #{lit expected}
+            if node.tag
+              return make_error(UnexpectedTag, #{lit "expected tag #{expected.dump}, but got "} + node.tag.dump, path)
+            else
+              return make_error(UnexpectedTag, #{lit "expected tag #{expected.dump}, but none specified"}, path)
+            end
+          end
+
+        RUBY
+      else
+        <<~RUBY
+          if tag
+            return make_error(UnexpectedTag, "expected no tag, but got " + node.tag.dump, path)
+          end
+
+        RUBY
+      end
+    end
+
+    # Validate a child node, pushing +segment+ on to the path for the
+    # duration of the call.
+    def child_call meth, node_expr, segment_expr
+      <<~RUBY
+        path.push(#{segment_expr})
+        err = #{meth}(#{node_expr}, aliases, path, allow_aliases)
+        path.pop
+        return err if err
+      RUBY
+    end
+
+    def object_body schema, path
+      src = +<<~RUBY
+        unless node.mapping?
+          return make_error(UnexpectedType, "expected Mapping, got " + node.class.name.dump, path)
+        end
+
+        children = node.children
+        len = children.length
+        i = 0
+      RUBY
+
+      if schema["properties"]
+        properties = schema["properties"]
+        key_meth = schema_method(schema["propertyNames"] || EMPTY_SCHEMA, "#{path}/propertyNames", "string")
+
+        unknown = if schema["additionalProperties"]
+          meth = schema_method(schema["additionalProperties"], "#{path}/additionalProperties")
+          child_call(meth, "val", "key.value")
+        else
+          <<~RUBY
+            path.push(key.value)
+            err = make_error(UnexpectedProperty, "unknown property " + key.value.dump, path)
+            path.pop
+            return err
+          RUBY
+        end
+
+        seen = properties.keys.each_with_index.map { |_, idx| "seen_#{idx}" }
+        seen.each { |s| src << "#{s} = false\n" }
+
+        src << <<~RUBY
+          while i < len
+            key = children[i]
+            val = children[i + 1]
+            i += 2
+
+            err = #{key_meth}(key, aliases, path, allow_aliases)
+            return err if err
+
+        RUBY
+
+        if properties.empty?
+          src << indent(unknown, 2)
+        else
+          src << "  case key.value\n"
+          properties.each_with_index do |(name, sub), idx|
+            meth = schema_method(sub, "#{path}/properties/#{name}")
+            src << "  when #{lit name}\n"
+            src << "    if #{seen[idx]}\n"
+            src << indent(unknown, 6)
+            src << "    else\n"
+            src << "      #{seen[idx]} = true\n"
+            src << indent(child_call(meth, "val", lit(name)), 6)
+            src << "    end\n"
+          end
+          src << "  else\n"
+          src << indent(unknown, 4)
+          src << "  end\n"
+        end
+        src << "end\n"
+
+        required = Array(schema["required"])
+        checks = properties.keys.each_with_index.select { |name, _| required.include?(name) }
+        unless checks.empty?
+          src << "\nmissing = nil\n"
+          checks.each do |name, idx|
+            src << "(missing ||= []) << #{lit name.dump} unless #{seen[idx]}\n"
+          end
+          src << <<~RUBY
+            if missing
+              return make_error(MissingRequiredField, "missing fields " + missing.join(" "), path)
+            end
+          RUBY
+        end
+      else
+        key_meth = schema_method(EMPTY_SCHEMA, "#{path}/propertyNames", "string")
+        meth = schema_method(schema["items"], "#{path}/items")
+        src << <<~RUBY
+          while i < len
+            key = children[i]
+            val = children[i + 1]
+            i += 2
+
+            err = #{key_meth}(key, aliases, path, allow_aliases)
+            return err if err
+
+          #{indent(child_call(meth, "val", "key.value"), 2)}end
+        RUBY
+      end
+
+      src
+    end
+
+    def array_body schema, path
+      src = +<<~RUBY
+        unless node.sequence?
+          return make_error(UnexpectedType, "expected Sequence, got " + node.class.name.dump, path)
+        end
+
+        children = node.children
+        len = children.length
+
+      RUBY
+
+      if max = schema["maxItems"]
+        src << <<~RUBY
+          if len > #{max}
+            return make_error(UnexpectedValue, #{lit "expected maximum #{max} items, but found "} + len.to_s, path)
+          end
+
+        RUBY
+      end
+
+      if min = schema["minItems"]
+        src << <<~RUBY
+          if len < #{min}
+            return make_error(UnexpectedValue, #{lit "expected minimum #{min} items, but found "} + len.to_s, path)
+          end
+
+        RUBY
+      end
+
+      if schema["items"]
+        meth = schema_method(schema["items"], "#{path}/items")
+        src << <<~RUBY
+          i = 0
+          while i < len
+          #{indent(child_call(meth, "children[i]", "i"), 2)}  i += 1
+          end
+        RUBY
+      else
+        schema["prefixItems"].each_with_index do |sub, idx|
+          meth = schema_method(sub, "#{path}/prefixItems/#{idx}")
+          src << "if len > #{idx}\n"
+          src << indent(child_call(meth, "children[#{idx}]", idx.to_s), 2)
+          src << "end\n"
+        end
+      end
+
+      src
+    end
+
+    def pattern_constant pattern
+      name = "PATTERN_#{@constants.length}"
+      @constants << "#{name} = Regexp.new(#{lit pattern.source}, #{pattern.options})"
+      name
+    end
+
+    def scalar_body type, schema
+      src = +<<~RUBY
+        unless node.scalar?
+          return make_error(UnexpectedType, "expected Scalar, got " + node.class.name.dump, path)
+        end
+
+        value = node.value
+      RUBY
+
+      pattern = schema["pattern"]
+
+      if type == "string"
+        src << <<~RUBY
+          unless node.quoted || node.tag == "!str"
+            found = extract_type(value)
+            if found != :string
+              return make_error(UnexpectedValue, "expected string, got " + found.to_s, path)
+            end
+          end
+        RUBY
+
+        if max = schema["maxLength"]
+          src << <<~RUBY
+            if value.bytesize > #{max}
+              return make_error(InvalidString, #{lit "expected string length to be <= #{max}"}, path)
+            end
+          RUBY
+        end
+
+        if min = schema["minLength"]
+          src << <<~RUBY
+            if value.bytesize < #{min}
+              return make_error(InvalidString, #{lit "expected string length to be >= #{min}"}, path)
+            end
+          RUBY
+        end
+
+        if pattern
+          src << <<~RUBY
+            unless value.match?(#{pattern_constant(pattern)})
+              return make_error(InvalidPattern, "expected string '" + value.dump + #{lit "' to match #{pattern}"}, path)
+            end
+          RUBY
+        end
+      else
+        src << <<~RUBY
+          if node.quoted
+            return make_error(UnexpectedValue, #{lit "expected #{type}, got string"}, path)
+          end
+        RUBY
+
+        if type == "null"
+          src << <<~RUBY
+            unless value == ""
+              return make_error(UnexpectedValue, "expected empty string, got " + value.dump, path)
+            end
+          RUBY
+        else
+          if pattern
+            src << <<~RUBY
+              unless value.match?(#{pattern_constant(pattern)})
+                return make_error(InvalidPattern, "expected '" + value.dump + #{lit "' to match #{pattern}"}, path)
+              end
+            RUBY
+          end
+
+          if type == "boolean"
+            src << <<~RUBY
+              unless value == "false" || value == "true"
+                return make_error(UnexpectedValue, "expected 'true' or 'false' for boolean", path)
+              end
+            RUBY
+          else
+            src << <<~RUBY
+              found = extract_type(value)
+              unless found == #{type.to_sym.inspect}
+                return make_error(UnexpectedValue, #{lit "expected #{type}, got "} + found.to_s, path)
+              end
+            RUBY
+          end
+        end
+      end
+
+      src
+    end
+  end
+end