prmd 0.6.2 → 0.7.0

data/lib/prmd/commands/init.rb

@@ -1,107 +1,39 @@
+require 'json'
+require 'prmd/template'
+require 'prmd/core/generator'
+
+# :nodoc:
 module Prmd
-  def self.init(resource, options={})
-    data = {
-      '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
-      'title'       => 'FIXME',
-      'definitions' => {},
-      'description' => 'FIXME',
-      'links'       => [],
-      'properties'  => {},
-      'type'        => ['object']
-    }
+  # Schema generation
+  module Generate
+    # Creates a default Prmd::Generator using default templates
+    #
+    # @return [Prmd::Generator]
+    def self.make_generator
+      base = Prmd::Template.load_json('init_default.json')
+      template = Prmd::Template.load_template('init_resource.json.erb', '')
+      Prmd::Generator.new(base: base, template: template)
+    end
+  end
 
-    schema = Prmd::Schema.new(data)
+  # Generate a schema template
+  #
+  # @param [String] resource
+  # @param [Hash<Symbol, Object>] options
+  # @return [String] schema template in YAML (yaml option was enabled) else JSON
+  def self.init(resource, options = {})
+    gen = Generate.make_generator
 
+    generator_options = { resource: nil, parent: nil }
     if resource
-      if resource.include?('/')
-        parent, resource = resource.split('/')
-      end
-      schema['id']    = "schemata/#{resource}"
-      schema['title'] = "FIXME - #{resource[0...1].upcase}#{resource[1..-1]}"
-      schema['definitions'] = {
-        "created_at" => {
-          "description" => "when #{resource} was created",
-          "example"     => "2012-01-01T12:00:00Z",
-          "format"      => "date-time",
-          "type"        => ["string"]
-        },
-        "id" => {
-          "description" => "unique identifier of #{resource}",
-          "example"     => "01234567-89ab-cdef-0123-456789abcdef",
-          "format"      => "uuid",
-          "type"        => ["string"]
-        },
-        "identity" => {
-          "$ref" => "/schemata/#{resource}#/definitions/id"
-        },
-        "updated_at" => {
-          "description" => "when #{resource} was updated",
-          "example"     => "2012-01-01T12:00:00Z",
-          "format"      => "date-time",
-          "type"        => ["string"]
-        }
-      }
-      schema['links'] = [
-        {
-          "description"   => "Create a new #{resource}.",
-          "href"          => "/#{resource}s",
-          "method"        => "POST",
-          "rel"           => "create",
-          "schema"        => {
-            "properties"  => {},
-            "type"        => ["object"]
-          },
-          "title"         => "Create"
-        },
-        {
-          "description"   => "Delete an existing #{resource}.",
-          "href"          => "/#{resource}s/{(%2Fschemata%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
-          "method"        => "DELETE",
-          "rel"           => "destroy",
-          "title"         => "Delete"
-        },
-        {
-          "description"   => "Info for existing #{resource}.",
-          "href"          => "/#{resource}s/{(%2Fschemata%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
-          "method"        => "GET",
-          "rel"           => "self",
-          "title"         => "Info"
-        },
-        {
-          "description"   => "List existing #{resource}s.",
-          "href"          => "/#{resource}s",
-          "method"        => "GET",
-          "rel"           => "instances",
-          "title"         => "List"
-        },
-        {
-          "description"   => "Update an existing #{resource}.",
-          "href"          => "/#{resource}s/{(%2Fschemata%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
-          "method"        => "PATCH",
-          "rel"           => "update",
-          "schema"        => {
-            "properties"  => {},
-            "type"        => ["object"]
-          },
-          "title"         => "Update"
-        }
-      ]
-      if parent
-        schema['links'] << {
-          "description"  => "List existing #{resource}s for existing #{parent}.",
-          "href"         => "/#{parent}s/{(%2Fschemata%2F#{parent}%23%2Fdefinitions%2Fidentity)}/#{resource}s",
-          "method"       => "GET",
-          "rel"          => "instances",
-          "title"        => "List"
-        }
-      end
-      schema['properties'] = {
-        "created_at"  => { "$ref" => "/schemata/#{resource}#/definitions/created_at" },
-        "id"          => { "$ref" => "/schemata/#{resource}#/definitions/id" },
-        "updated_at"  => { "$ref" => "/schemata/#{resource}#/definitions/updated_at" }
-      }
+      parent = nil
+      parent, resource = resource.split('/') if resource.include?('/')
+      generator_options[:parent] = parent
+      generator_options[:resource] = resource
     end
 
+    schema = gen.generate(generator_options)
+
     if options[:yaml]
       schema.to_yaml
     else

data/lib/prmd/commands/render.rb

@@ -1,24 +1,37 @@
-module Prmd
-  def self.render(schema, options={})
-    doc = ''
-
-    options[:content_type] ||= 'application/json'
-    options[:style] ||= 'default'
+require 'prmd/core/renderer'
 
-    if options[:prepend]
-      doc << options[:prepend].map {|path| File.read(path)}.join("\n") << "\n"
+# :nodoc:
+module Prmd
+  # Render helper module
+  module Render
+    # Retrieve the schema template
+    #
+    # @param [Hash<Symbol, Object>] options
+    # @return (see Prmd::Template.load_template)
+    def self.get_template(options)
+      template = options.fetch(:template) do
+        abort 'render: Template was not provided'
+      end
+      template_dir = File.expand_path(template)
+      # to keep backward compatibility
+      template_dir = File.dirname(template) unless File.directory?(template_dir)
+      Prmd::Template.load_template('schema.erb', template_dir)
     end
+  end
 
-    template_dir = File::expand_path(options[:template])
-    if not File.directory?(template_dir)  # to keep backward compatibility
-      template_dir = File.dirname(options[:template])
+  # Render provided schema to Markdown
+  #
+  # @param [Prmd::Schema] schema
+  # @return [String] rendered schema in Markdown
+  def self.render(schema, options = {})
+    renderer = Prmd::Renderer.new(template: Render.get_template(options))
+    doc = ''
+    if options[:prepend]
+      doc <<
+      options[:prepend].map { |path| File.read(path) }.join("\n") <<
+      "\n"
     end
-
-    doc << Prmd::Template::render('schema.erb', template_dir, {
-      options:         options,
-      schema:          schema
-    })
-
+    doc << renderer.render(schema, options)
     doc
   end
 end

data/lib/prmd/commands/verify.rb

@@ -1,51 +1,94 @@
-require "json"
-require "json_schema"
+require 'json'
+require 'json_schema'
 
+# :nodoc:
 module Prmd
-  # These schemas are listed manually and in order because they reference each
-  # other.
-  SCHEMAS = [
-    "schema.json",
-    "hyper-schema.json",
-    "interagent-hyper-schema.json"
-  ]
+  # Schema Verification
+  module Verification
+    # These schemas are listed manually and in order because they reference each
+    # other.
+    SCHEMAS = [
+      'schema.json',
+      'hyper-schema.json',
+      'interagent-hyper-schema.json'
+    ]
 
-  def self.verify(schema_data)
-    store = init_document_store
+    # @return [JsonSchema::DocumentStore]
+    def self.init_document_store
+      store = JsonSchema::DocumentStore.new
+      SCHEMAS.each do |file|
+        file = File.expand_path("../../../../schemas/#{file}", __FILE__)
+        data = JSON.parse(File.read(file))
+        schema = JsonSchema::Parser.new.parse!(data)
+        schema.expand_references!(store: store)
+        store.add_schema(schema)
+      end
+      store
+    end
 
-    if !(schema_uri = schema_data["$schema"])
-      return ["Missing $schema."]
+    # @return [JsonSchema::DocumentStore]
+    def self.document_store
+      @document_store ||= init_document_store
     end
 
-    # for good measure, make sure that the schema parses and that its
-    # references can be expanded
-    schema, errors = JsonSchema.parse!(schema_data)
-    return JsonSchema::SchemaError.aggregate(errors) if !schema
+    # @param [Hash] schema_data
+    # @return [Array<String>] errors from failed verfication
+    def self.verify_parsable(schema_data)
+      # for good measure, make sure that the schema parses and that its
+      # references can be expanded
+      schema, errors = JsonSchema.parse!(schema_data)
+      return JsonSchema::SchemaError.aggregate(errors) unless schema
 
-    valid, errors = schema.expand_references(store: store)
-    return JsonSchema::SchemaError.aggregate(errors) if !valid
+      valid, errors = schema.expand_references(store: document_store)
+      return JsonSchema::SchemaError.aggregate(errors) unless valid
 
-    if !(meta_schema = store.lookup_schema(schema_uri))
-      return ["Unknown $schema: #{schema_uri}."]
+      []
     end
 
-    valid, errors = meta_schema.validate(schema_data)
-    return JsonSchema::SchemaError.aggregate(errors) if !valid
+    # @param [Hash] schema_data
+    # @return [Array<String>] errors from failed verfication
+    def self.verify_meta_schema(meta_schema, schema_data)
+      valid, errors = meta_schema.validate(schema_data)
+      return JsonSchema::SchemaError.aggregate(errors) unless valid
 
-    []
-  end
+      []
+    end
+
+    # @param [Hash] schema_data
+    # @return [Array<String>] errors from failed verfication
+    def self.verify_schema(schema_data)
+      schema_uri = schema_data['$schema']
+      return ['Missing $schema key.'] unless schema_uri
+
+      meta_schema = document_store.lookup_schema(schema_uri)
+      return ["Unknown $schema: #{schema_uri}."] unless meta_schema
 
-  private
+      verify_meta_schema(meta_schema, schema_data)
+    end
+
+    # Verfies that a given schema is valid
+    #
+    # @param [Hash] schema_data
+    # @return [Array<String>] errors from failed verification
+    def self.verify(schema_data)
+      a = verify_schema(schema_data)
+      return a unless a.empty?
+      b = verify_parsable(schema_data)
+      return b unless b.empty?
+      []
+    end
 
-  def self.init_document_store
-    store = JsonSchema::DocumentStore.new
-    SCHEMAS.each do |file|
-      file = File.expand_path("../../../../schemas/#{file}", __FILE__)
-      data = JSON.parse(File.read(file))
-      schema = JsonSchema::Parser.new.parse!(data)
-      schema.expand_references!(store: store)
-      store.add_schema(schema)
+    class << self
+      private :init_document_store
+      private :document_store
+      private :verify_parsable
+      private :verify_schema
+      private :verify_meta_schema
     end
-    store
+  end
+
+  # (see Prmd::Verification.verify)
+  def self.verify(schema_data)
+    Verification.verify(schema_data)
   end
 end

data/lib/prmd/core/combiner.rb

@@ -0,0 +1,91 @@
+require 'prmd/schema'
+require 'prmd/core/schema_hash'
+
+# :nodoc:
+module Prmd
+  # Schema combiner
+  class Combiner
+    #
+    # @param [Hash<Symbol, Object>] properties
+    def initialize(properties = {})
+      @properties = properties
+      @schema = properties.fetch(:schema)
+      @base = properties.fetch(:base, {})
+      @meta = properties.fetch(:meta, {})
+    end
+
+    # @param [Array] array
+    # @return [Array]
+    def reference_localizer_array(array)
+      array.map { |element| reference_localizer(element) }
+    end
+
+    # @param [Hash] hash
+    # @return [Hash]
+    def reference_localizer_hash(hash)
+      if hash.key?('$ref')
+        hash['$ref'] = '#/definitions' + hash['$ref'].gsub('#', '')
+                                                     .gsub('/schemata', '')
+      end
+      if hash.key?('href') && hash['href'].is_a?(String)
+        hash['href'] = hash['href'].gsub('%23', '')
+                                   .gsub(/%2Fschemata(%2F[^%]*%2F)/,
+                                         '%23%2Fdefinitions\1')
+      end
+      hash.each_with_object({}) { |(k, v), r| r[k] = reference_localizer(v) }
+    end
+
+    #
+    # @param [Object] datum
+    # @return [Object]
+    def reference_localizer(datum)
+      case datum
+      when Array
+        reference_localizer_array(datum)
+      when Hash
+        reference_localizer_hash(datum)
+      else
+        datum
+      end
+    end
+
+    #
+    # @param [Prmd::SchemaHash] schemata
+    # @return [Prmd::Schema]
+    def combine(*schemata)
+      # tracks which entities where defined in which file
+      schemata_map = {}
+
+      data = {}
+      data.merge!(@base)
+      data.merge!(@meta)
+
+      schemata.each do |schema|
+        id = schema.fetch('id')
+        id_ary = id.split('/').last
+
+        if s = schemata_map[id]
+          $stderr.puts "`#{id}` (from #{schema.filename}) was already defined" \
+                       "in `#{s.filename}` and will overwrite the first" \
+                       "definition"
+        end
+        # avoinding damaging the original schema
+        embedded_schema = schema.dup
+        # schemas are now in a single scope by combine
+        embedded_schema.delete('id')
+        schemata_map[id] = embedded_schema
+
+        data['definitions'][id_ary] = embedded_schema.to_h
+        data['properties'][id_ary] = { '$ref' => "#/definitions/#{id_ary}" }
+
+        reference_localizer(data['definitions'][id_ary])
+      end
+
+      Prmd::Schema.new(data)
+    end
+
+    private :reference_localizer_array
+    private :reference_localizer_hash
+    private :reference_localizer
+  end
+end

data/lib/prmd/core/generator.rb

@@ -0,0 +1,27 @@
+require 'json'
+require 'prmd/schema'
+
+# :nodoc:
+module Prmd
+  # Schema generator
+  class Generator
+    #
+    # @param [Hash<Symbol, Object>] properties
+    def initialize(properties = {})
+      @properties = properties
+      @base = properties.fetch(:base, {})
+      @template = properties.fetch(:template)
+    end
+
+    #
+    # @param [Hash<Symbol, Object>] options
+    def generate(options = {})
+      res = @template.result(options)
+      resource_schema = JSON.parse(res)
+      schema = Prmd::Schema.new
+      schema.merge!(@base)
+      schema.merge!(resource_schema)
+      schema
+    end
+  end
+end

data/lib/prmd/core/renderer.rb

@@ -0,0 +1,56 @@
+require 'prmd/template'
+
+# :nodoc:
+module Prmd
+  # Schema Generator
+  class Renderer
+    #
+    # @param [Hash<Symbol, Object>] properties
+    def initialize(properties = {})
+      @properties = properties
+      @template = @properties.fetch(:template)
+    end
+
+    #
+    # @return [Hash<Symbol, Object>]
+    def default_options
+      {
+        http_header: {},
+        content_type: 'application/json',
+        doc: {},
+        prepend: nil
+      }
+    end
+
+    #
+    # @param [Hash<Symbol, Object>] options
+    # @return [void]
+    def append_default_options(options)
+      options[:doc] = {
+        url_style: 'default',
+        disable_title_and_description: false
+      }.merge(options[:doc])
+    end
+
+    #
+    # @param [Hash<Symbol, Object>] options
+    # @return [Hash<Symbol, Object>]
+    def setup_options(options)
+      opts = default_options
+      opts.merge!(options)
+      append_default_options(opts)
+      opts
+    end
+
+    #
+    # @param [Prmd::Schema] schema
+    # @param [Hash<Symbol, Object>] options
+    def render(schema, options = {})
+      @template.result(schema: schema, options: setup_options(options))
+    end
+
+    private :default_options
+    private :append_default_options
+    private :setup_options
+  end
+end