heroics 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ef1ff049152a681067bf9cd179da754105d8419c
-  data.tar.gz: 1e98dc4aa35031eefc0734252bc1e650c969073b
+  metadata.gz: 57ff3e602b9779ad560f218f14288d8871402d33
+  data.tar.gz: 6763bba24c1ccb627963116ee6f43ed341113703
 SHA512:
-  metadata.gz: 1b7486964a14891fcbede7250748ffd41e8b44c5f7446f4bac06260365d79b3b1b5801dc14d13706a2a61ed0cc42961ff181aff9063eadf449264cd465babbb6
-  data.tar.gz: dd2217537e68ae2ab93fd1985c3812edaba6c0a666af6b8202ba3a560a4ac89fa3b9a5f59841e92ecd95c3a9110502383309139bbcc001720a46529924a20230
+  metadata.gz: 97435f7696ba084ec24a487ea3a652a880100124981e1ebf7f1e91bebf8baff64c6b281dca44e8480d550d3097ac368e36ddd8a466114841b9811b8dd2f4e072
+  data.tar.gz: 05282988882070b71e6cf9c9c6834bb65fc91c783da88c08e0163b54a21e97dedec950d9b187593cbed23b18c379404d0a6acb091800cb37adbdf586386c1fd9

data/bin/heroics-generate

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'heroics'
+
+options = {}
+option_parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: heroics-generate module_name schema_filename url'
+  opts.on( '-h', '--help', 'Display this screen' ) do
+    puts opts
+    exit
+  end
+end
+
+option_parser.parse!
+module_name, schema_filename, url = ARGV
+schema = Heroics::Schema.new(MultiJson.decode(File.read(schema_filename)))
+options = {
+  default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'},
+  cache: 'Moneta.new(:File, dir: "#{Dir.home}/.heroics/platform-api")'
+}
+puts Heroics.generate_client(module_name, schema, url, options)

data/heroics.gemspec

@@ -25,8 +25,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'turn'
 
+  spec.add_dependency 'erubis', '~> 2.7.0'
   spec.add_dependency 'excon'
-  spec.add_dependency 'netrc'
   spec.add_dependency 'moneta'
-  spec.add_dependency 'multi_json'
+  spec.add_dependency 'multi_json', '>= 1.9.2'
+  spec.add_dependency 'netrc'
 end

data/lib/heroics.rb

@@ -1,4 +1,5 @@
 require 'base64'
+require 'erubis'
 require 'excon'
 require 'moneta'
 require 'multi_json'
@@ -18,3 +19,4 @@ require 'heroics/client'
 require 'heroics/schema'
 require 'heroics/command'
 require 'heroics/cli'
+require 'heroics/client_generator'

data/lib/heroics/client_generator.rb

@@ -0,0 +1,106 @@
+module Heroics
+  # Generate a static client that uses Heroics under the hood.  This is a good
+  # option if you want to ship a gem or generate API documentation using Yard.
+  #
+  # @param module_name [String] The name of the module, as rendered in a Ruby
+  #   source file, to use for the generated client.
+  # @param schema [Schema] The schema instance to generate the client from.
+  # @param url [String] The URL for the API service.
+  # @param options [Hash] Configuration for links.  Possible keys include:
+  #   - default_headers: Optionally, a set of headers to include in every
+  #     request made by the client.  Default is no custom headers.
+  #   - cache: Optionally, a Moneta-compatible cache to store ETags.  Default
+  #     is no caching.
+  def self.generate_client(module_name, schema, url, options)
+    filename = File.dirname(__FILE__) + '/views/client.erb'
+    eruby = Erubis::Eruby.new(File.read(filename))
+    context = build_context(module_name, schema, url, options)
+    eruby.evaluate(context)
+  end
+
+  private
+
+  # Process the schema to build up the context needed to render the source
+  # template.
+  def self.build_context(module_name, schema, url, options)
+    resources = []
+    schema.resources.each do |resource_schema|
+      links = []
+      resource_schema.links.each do |link_schema|
+        links << GeneratorLink.new(link_schema.name.gsub('-', '_'),
+                                   link_schema.description,
+                                   link_schema.parameter_details,
+                                   link_schema.needs_request_body?)
+      end
+      resources << GeneratorResource.new(resource_schema.name.gsub('-', '_'),
+                                         resource_schema.description,
+                                         links)
+    end
+
+    context = {module_name: module_name,
+               url: url,
+               default_headers: options.fetch(:default_headers, {}),
+               cache: options.fetch(:cache, {}),
+               description: schema.description,
+               schema: MultiJson.dump(schema.schema),
+               resources: resources}
+  end
+
+  # A representation of a resource for use when generating source code in the
+  # template.
+  class GeneratorResource
+    attr_reader :name, :description, :links
+
+    def initialize(name, description, links)
+      @name = name
+      @description = description
+      @links = links
+    end
+
+    # The name of the resource class in generated code.
+    def class_name
+      Heroics.camel_case(name)
+    end
+  end
+
+  # A representation of a link for use when generating source code in the
+  # template.
+  class GeneratorLink
+    attr_reader :name, :description, :parameters, :takes_body
+
+    def initialize(name, description, parameters, takes_body)
+      @name = name
+      @description = description
+      @parameters = parameters
+      if takes_body
+        parameters << BodyParameter.new
+      end
+    end
+
+    # The list of parameters to render in generated source code for the method
+    # signature for the link.
+    def parameter_names
+      @parameters.map { |info| info.name }.join(', ')
+    end
+  end
+
+  # Convert a lower_case_name to CamelCase.
+  def self.camel_case(text)
+    return text if text !~ /_/ && text =~ /[A-Z]+.*/
+    text = text.split('_').map{ |element| element.capitalize }.join
+    [/^Ssl/, /^Http/, /^Xml/].each do |replace|
+      text.sub!(replace) { |match| match.upcase }
+    end
+    text
+  end
+
+  # A representation of a body parameter.
+  class BodyParameter
+    attr_reader :name, :description
+
+    def initialize
+      @name = 'body'
+      @description = 'the object to pass as the request payload'
+    end
+  end
+end

data/lib/heroics/schema.rb

@@ -14,6 +14,11 @@ module Heroics
       end
     end
 
+    # A description of the API.
+    def description
+      @schema['description']
+    end
+
     # Get a schema for a named resource.
     #
     # @param name [String] The name of the resource.
@@ -60,6 +65,11 @@ module Heroics
                     end]
     end
 
+    # A description of the resource.
+    def description
+      @schema['definitions'][name]['description']
+    end
+
     # Get a schema for a named link.
     #
     # @param name [String] The name of the link.
@@ -122,7 +132,21 @@ module Heroics
     #
     # @return [Array<String>] The parameters.
     def parameters
-      resolve_parameters(link_schema['href'].scan(PARAMETER_REGEX))
+      parameter_names = link_schema['href'].scan(PARAMETER_REGEX)
+      resolve_parameters(parameter_names)
+    end
+
+    # Get the names and descriptions of the parameters this link expects.
+    #
+    # @return [Hash<String, String>] A list of hashes with `name` and
+    #   `description` key/value pairs describing parameters.
+    def parameter_details
+      parameter_names = link_schema['href'].scan(PARAMETER_REGEX)
+      resolve_parameter_details(parameter_names)
+    end
+
+    def needs_request_body?
+      return link_schema.has_key?('schema')
     end
 
     # Get an example request body.
@@ -132,14 +156,14 @@ module Heroics
       if body_schema = link_schema['schema']
         definitions = @schema['definitions'][@resource_name]['definitions']
         Hash[body_schema['properties'].keys.map do |property|
-               # FIXME This is wrong! -jkakar
-               if definitions.has_key?(property)
-                 example = definitions[property]['example']
-               else
-                 example = ''
-               end
-               [property, example]
-             end]
+          # FIXME This is wrong! -jkakar
+          if definitions.has_key?(property)
+            example = definitions[property]['example']
+          else
+            example = ''
+          end
+          [property, example]
+        end]
       end
     end
 
@@ -173,7 +197,7 @@ module Heroics
     private
 
     # Match parameters in definition strings.
-    PARAMETER_REGEX = /\{\([%\/a-zA-Z0-9_]*\)\}/
+    PARAMETER_REGEX = /\{\([%\/a-zA-Z0-9_-]*\)\}/
 
     # Get the raw link schema.
     #
@@ -188,10 +212,8 @@ module Heroics
     #   convert to parameter names.
     # @return [Array<String>] The parameters.
     def resolve_parameters(parameters)
-      # FIXME This is all pretty terrible.  It'd be much better to
-      # automatically resolve $ref's based on the path instead of special
-      # casing everything. -jkakar
       properties = @schema['definitions'][@resource_name]['properties']
+      return [''] if properties.nil?
       definitions = Hash[properties.each_pair.map do |key, value|
                            [value['$ref'], key]
                          end]
@@ -216,6 +238,72 @@ module Heroics
       end
     end
 
+    # Get the parameters this link expects.
+    #
+    # @param parameters [Array] The names of the parameter definitions to
+    #   convert to parameter names.
+    # @return [Array<Parameter|ParameterChoice>] A list of parameter instances
+    #   that represent parameters to be injected into the link URL.
+    def resolve_parameter_details(parameters)
+      properties = @schema['definitions'][@resource_name]['properties']
+      return [] if properties.nil?
+
+      # URI decode parameters and strip the leading '{(' and trailing ')}'.
+      parameters = parameters.map { |parameter| URI.unescape(parameter[2..-3]) }
+      parameters.map do |parameter|
+        # Split the path into components and discard the leading '#' that
+        # represents the root of the schema.
+        path = parameter.split('/')[1..-1]
+        info = lookup_parameter(path, @schema)
+        # The reference can be one of several values.
+        resource_name = path[1].gsub('-', '_')
+        if info.has_key?('anyOf')
+          ParameterChoice.new(resource_name,
+                              unpack_multiple_parameters(info['anyOf']))
+        elsif info.has_key?('oneOf')
+          ParameterChoice.new(resource_name,
+                              unpack_multiple_parameters(info['oneOf']))
+        else
+          name = path[-1]
+          Parameter.new(resource_name, name, info['description'])
+        end
+      end
+    end
+
+    # Unpack an 'anyOf' or 'oneOf' multi-parameter blob.
+    #
+    # @param parameters [Array<Hash>] An array of hashes containing '$ref'
+    #   keys and definition values.
+    # @return [Array<Parameter>] An array of parameters extracted from the
+    #   blob.
+    def unpack_multiple_parameters(parameters)
+      parameters.map do |info|
+        parameter = info['$ref']
+        path = parameter.split('/')[1..-1]
+        info = lookup_parameter(path, @schema)
+        resource_name = path[1].gsub('-', '_')
+        name = path[-1]
+        Parameter.new(resource_name, name, info['description'])
+      end
+    end
+
+    # Recursively walk the object hierarchy in the schema to resolve a given
+    # path.  This is used to find property information related to definitions
+    # in link hrefs.
+    #
+    # @param path [Array<String>] An array of paths to walk, such as
+    #   ['definitions', 'resource', 'definitions', 'property'].
+    # @param schema [Hash] The schema to walk.
+    def lookup_parameter(path, schema)
+      key = path[0]
+      remaining = path[1..-1]
+      if remaining.empty?
+        return schema[key]
+      else
+        lookup_parameter(remaining, schema[key])
+      end
+    end
+
     # Convert a path parameter to a format suitable for use in a path.
     #
     # @param [Fixnum,String,TrueClass,FalseClass,Time] The parameter to format.
@@ -243,6 +331,54 @@ module Heroics
   def self.download_schema(url, options={})
     default_headers = options.fetch(:default_headers, {})
     response = Excon.get(url, headers: default_headers, expects: [200, 201])
-    Schema.new(MultiJson.decode(response.body))
+    Schema.new(MultiJson.load(response.body))
+  end
+
+  # A representation of a parameter.
+  class Parameter
+    attr_reader :resource_name, :description
+
+    def initialize(resource_name, name, description)
+      @resource_name = resource_name
+      @name = name
+      @description = description
+    end
+
+    # The name of the parameter, with the resource included, suitable for use
+    # in a function signature.
+    def name
+      "#{@resource_name}_#{@name}"
+    end
+
+    # A pretty representation of this instance.
+    def inspect
+      "Parameter(name=#{@name}, description=#{@description})"
+    end
+  end
+
+  # A representation of a set of parameters.
+  class ParameterChoice
+    attr_reader :resource_name, :parameters
+
+    def initialize(resource_name, parameters)
+      @resource_name = resource_name
+      @parameters = parameters
+    end
+
+    # A name created by merging individual parameter descriptions, suitable
+    # for use in a function signature.
+    def name
+      @parameters.map { |parameter| parameter.name }.join('_or_')
+    end
+
+    # A description created by merging individual parameter descriptions.
+    def description
+      @parameters.map { |parameter| parameter.description }.join(' or ')
+    end
+
+    # A pretty representation of this instance.
+    def inspect
+      "ParameterChoice(parameters=#{@parameters})"
+    end
   end
 end

data/lib/heroics/version.rb

@@ -1,3 +1,3 @@
 module Heroics
-  VERSION = '0.0.6'
+  VERSION = '0.0.7'
 end

data/lib/heroics/views/client.erb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+#
+# WARNING: Do not edit by hand, this file was generated by Heroics:
+#
+#   https://github.com/heroku/heroics
+#
+
+require 'uri'
+
+module <%= @module_name %>
+  # Get a Client configured to use HTTP Basic authentication.
+  #
+  # @param username [String] The username to use with the API.
+  # @param password [String] The password to use with the API.
+  # @param headers [Hash<String,String>] Optionally, custom to headers to
+  #   include with every response.
+  # @return [Client] A client configured to use the API with HTTP Basic
+  #   authentication.
+  def self.connect(username, password, headers=nil)
+    url = URI.parse("<%= @url %>")
+    url.user = username
+    url.password = password
+    default_headers = <%= @default_headers %>
+    unless headers.nil?
+      default_headers.merge!(headers)
+    end
+    cache = <%= @cache %>
+    options = {
+      options: {default_headers: default_headers,
+                cache: cache}
+    }
+    client = Heroics.client_from_schema(SCHEMA, url.to_s, options)
+    Client.new(client)
+  end
+
+  # Get a Client configured to use OAuth authentication.
+  #
+  # @param oauth_token [String] The OAuth token to use with the API.
+  # @param headers [Hash<String,String>] Optionally, custom to headers to
+  #   include with every response.
+  # @return [Client] A client configured to use the API with OAuth
+  #   authentication.
+  def self.connect_oauth(oauth_token, headers=nil)
+    url = "<%= @url %>"
+    default_headers = <%= @default_headers %>
+    unless headers.nil?
+      default_headers.merge!(headers)
+    end
+    cache = <%= @cache %>
+    options = {
+      options: {default_headers: default_headers,
+                cache: cache}
+    }
+    client = Heroics.client_from_schema(oauth_token, SCHEMA, url, options)
+    Client.new(client)
+  end
+
+  # <%= @description %>
+  class Client
+    def initialize(client)
+      @client = client
+    end
+    <% for resource in @resources %>
+
+    # <%= resource.description %>
+    #
+    # @return [<%= resource.class_name %>]
+    def <%= resource.name %>
+      @<%= resource.name %>_resource ||= <%= resource.class_name %>.new(@client)
+    end
+    <% end %>
+  end
+
+  private
+  <% for resource in @resources %>
+
+  # <%= resource.description %>
+  class <%= resource.class_name %>
+    def initialize(client)
+      @client = client
+    end
+    <% for link in resource.links %>
+
+    # <%= link.description %>
+    <% unless link.parameters.empty? %>
+    #
+    <% for parameter in link.parameters %>
+    # @param <%= parameter.name %>: <%= parameter.description %>
+    <% end %>
+    <% end %>
+    def <%= link.name %>(<%= link.parameter_names %>)
+      @client.<%= resource.name %>.<%= link.name %>(<%= link.parameter_names %>)
+    end
+    <% end %>
+  end
+  <% end %>
+
+  SCHEMA = Heroics::Schema.new(MultiJson.load(<<-'HEROICS_SCHEMA'))
+<%= @schema %>
+HEROICS_SCHEMA
+end

data/test/client_generator_test.rb

@@ -0,0 +1,34 @@
+require 'helper'
+require 'netrc'
+require 'stringio'
+
+class GenerateClientTest  < MiniTest::Unit::TestCase
+  include ExconHelper
+
+  # generate_client takes a module, schema, API URL and options and returns a
+  # string containing generated Ruby client code.
+  def test_generate_client
+    Excon.stub(method: :get) do |request|
+      assert_equal('example.com', request[:host])
+      assert_equal('/schema', request[:path])
+      assert_equal('application/vnd.example+json; version=3',
+                   request[:headers]['Accept'])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(SAMPLE_SCHEMA)}
+    end
+
+    netrc = Netrc.read
+    username, token = netrc['example.com']
+    schema_url = "https://example.com/schema"
+    options = {
+        default_headers: {'Accept' => 'application/vnd.example+json; version=3'},
+        cache: 'Moneta.new(:File, dir: "#{Dir.home}/.heroics/example")'
+    }
+    schema = Heroics.download_schema(schema_url, options)
+    client_source = Heroics.generate_client("ExampleAPI", schema,
+                                            "api.example.com", options)
+    # Ensure the generated code is syntactically valid.
+    eval(client_source)
+  end
+end

data/test/schema_test.rb

@@ -50,7 +50,7 @@ class ResourceSchemaTest < MiniTest::Unit::TestCase
     assert_equal("Unknown link 'unknown-link'.", error.message)
   end
 
-  # ResourceSchema.links returns a list of LinkSchema children.
+  # ResourceSchema.links returns an array of LinkSchema children.
   def test_links
     schema = Heroics::Schema.new(SAMPLE_SCHEMA)
     assert_equal(
@@ -80,7 +80,7 @@ class LinkSchemaTest < MiniTest::Unit::TestCase
                  schema.resource('resource').link('list').description)
   end
 
-  # LinkSchema.parameters returns an empty list if the link doesn't require
+  # LinkSchema.parameters returns an empty array if the link doesn't require
   # parameters.
   def test_parameters_without_parameters
     schema = Heroics::Schema.new(SAMPLE_SCHEMA)
@@ -88,8 +88,8 @@ class LinkSchemaTest < MiniTest::Unit::TestCase
     assert_equal([], link.parameters)
   end
 
-  # LinkSchema.parameters returns a list of named parameter required to invoke
-  # the link correctly.
+  # LinkSchema.parameters returns an array of named parameter required to
+  # invoke the link correctly.
   def test_parameters
     schema = Heroics::Schema.new(SAMPLE_SCHEMA)
     link = schema.resource('resource').link('info')
@@ -105,6 +105,40 @@ class LinkSchemaTest < MiniTest::Unit::TestCase
     assert_equal(['uuid_field|email_field'], link.parameters)
   end
 
+  # LinkSchema.parameter_details returns an empty array if the link doesn't
+  # require parameters.
+  def test_parameter_details_without_parameters
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    link = schema.resource('resource').link('list')
+    assert_equal([], link.parameter_details)
+  end
+
+  # LinkSchema.parameter_details returns an array of Parameter with information
+  # about the parameters accepted by the link.
+  def test_parameter_details
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    link = schema.resource('resource').link('info')
+    parameters = link.parameter_details
+    assert_equal(1, parameters.length)
+    parameter = parameters[0]
+    assert_equal('resource_uuid_field', parameter.name)
+    assert_equal('A sample UUID field', parameter.description)
+  end
+
+  # LinkSchema.parameter_details returns an array of ParameterChoices, when
+  # more than one value may be used with a property, with information about
+  # the parameters accepted by the link.
+  def test_parameter_details_with_one_of_field
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    link = schema.resource('resource').link('identify_resource')
+    parameters = link.parameter_details
+    assert_equal(1, parameters.length)
+    parameter = parameters[0]
+    assert_equal('resource_uuid_field_or_resource_email_field', parameter.name)
+    assert_equal('A sample UUID field or A sample email address field',
+                 parameter.description)
+  end
+
   # LinkSchema.body returns nil if the link doesn't accept a request body.
   def test_example_body_without_body
     schema = Heroics::Schema.new(SAMPLE_SCHEMA)
@@ -125,7 +159,7 @@ class LinkSchemaTest < MiniTest::Unit::TestCase
                  link.example_body)
   end
 
-  # LinkSchema.format_path converts a list of parameters into a path.
+  # LinkSchema.format_path converts an array of parameters into a path.
   def test_format_path
     schema = Heroics::Schema.new(SAMPLE_SCHEMA)
     link = schema.resource('resource').link('info')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: heroics
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - geemus
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-09 00:00:00.000000000 Z
+date: 2014-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -67,6 +67,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: erubis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.0
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
@@ -82,7 +96,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: netrc
+  name: moneta
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -96,21 +110,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: moneta
+  name: multi_json
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.9.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.9.2
 - !ruby/object:Gem::Dependency
-  name: multi_json
+  name: netrc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -128,6 +142,7 @@ email:
 - geemus@gmail.com
 - jkakar@kakar.ca
 executables:
+- heroics-generate
 - heroku-api
 extensions: []
 extra_rdoc_files: []
@@ -139,11 +154,13 @@ files:
 - README.md
 - Rakefile
 - TODO
+- bin/heroics-generate
 - bin/heroku-api
 - heroics.gemspec
 - lib/heroics.rb
 - lib/heroics/cli.rb
 - lib/heroics/client.rb
+- lib/heroics/client_generator.rb
 - lib/heroics/command.rb
 - lib/heroics/errors.rb
 - lib/heroics/link.rb
@@ -151,8 +168,10 @@ files:
 - lib/heroics/resource.rb
 - lib/heroics/schema.rb
 - lib/heroics/version.rb
+- lib/heroics/views/client.erb
 - test.rb
 - test/cli_test.rb
+- test/client_generator_test.rb
 - test/client_test.rb
 - test/command_test.rb
 - test/helper.rb