atum 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8294a7df7c6ba5628b32d1028bbde6906cd2d6f2
-  data.tar.gz: 26ca258696c254884a703cf80301a1b9724dd574
+  metadata.gz: 4e0b2d59a4b5c181a68fd73d5670f2bd8a61c150
+  data.tar.gz: 3a47425502fa080a76b0bf7672f23912985d9b29
 SHA512:
-  metadata.gz: 08060202dbca9091a413c351ee17c46b97c41ffead0a220c14e9cd983fc78a0e0b69213a35de350fa07fc080d659ad11fb7ab0b070420c8c42c319ad4817bdc7
-  data.tar.gz: b3c58055353f154167f496b7465e1a4f290c9ffbbfbd4e280bd49dfbbf6283e9fe5e58f930edcb0ebbe569a53824b3a4e900ef9ac75dd854215922e51a5b5401
+  metadata.gz: a3c1476cda130ad87820109c763a8e6eace73d260054cea9cb691262ccf760352e871b6e78ee6f124d38c65a0a69394cc4678df3899fe2e31a37731cb87d82fc
+  data.tar.gz: d5d5e914a53afde32eb6106a364e55c82d993650865cfb8fa333a13fca62cceda1c69ff857b94b556f8e8c6faf829e976f0f3d9bc0045646c891aaf297bbcdd8

data/.rubocop_todo.yml

@@ -23,3 +23,7 @@ Style/Documentation:
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 Style/SignalException:
   Enabled: false
+
+# Offense count: 1
+Style/EachWithObject:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,2 @@
 # Change Log
 
-## 0.1.2
-
-- Actions which don't require a body can now be passed optional parameters

data/CONTRIBUTORS.md

@@ -1,15 +1,16 @@
 # Contributors
-## Original [Heroics](https://github.com/interagent/heroics) contributors:
-
-Andrea Salicetti <andrea.salicetti@gmail.com>
-Jamu Kakar <jkakar@kakar.ca>
-Jonathan Roes <jroes@jroes.net>
-Mark Fine <mark.fine@gmail.com>
-Mark McGranaghan <mmcgrana@gmail.com>
-Neil Middleton <neil@heroku.com>
-Wesley Beary <geemus+github@gmail.com>
 
 ## Atum contributors
 
-Pete Hamilton <peterejhamilton@gmail.com>
-Isaac Seymour <i.seymour@oxon.org>
+- [Pete Hamilton](https://github.com/petehamilton)
+- [Isaac Seymour](https://github.com/isaacseymour)
+
+## Original [Heroics](https://github.com/interagent/heroics) contributors:
+
+- [Andrea Salicetti](andrea.salicetti@gmail.com)
+- [Jamu Kakar](jkakar@kakar.ca)
+- [Jonathan Roes](jroes@jroes.net)
+- [Mark Fine](mark.fine@gmail.com)
+- [Mark McGranaghan](mmcgrana@gmail.com)
+- [Neil Middleton](neil@heroku.com)
+- [Wesley Beary](geemus+github@gmail.com)

data/README.md

@@ -3,55 +3,100 @@
 Ruby HTTP client generator for JSON APIs represented with JSON schema, forked
 from [Heroics](https://github.com/interagent/heroics).
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'atum'
-
-And then execute:
+**WARNING: Atum is currently in early Alpha development. You have been warned.**
 
-    $ bundle install
-
-Or install it yourself as:
+## Installation
 
     $ gem install atum
 
 ## Usage
 
-### Generating a client
+### Generating Clients
 
 Atum generates an HTTP client from a JSON schema that describes your JSON
 API. Look at [prmd](https://github.com/interagent/prmd) for tooling to help
 write a JSON schema.  When you have a JSON schema prepared you can generate a
-client for your API:
+client for your API.
+
+To see a simple example, you can look at the [Fruity API json
+schema](https://github.com/gocardless/atum/blob/master/spec/fixtures/fruity_schema.json)
+in Atum's spec fixtures
+
+#### 1. Create a New Gem
+
+To generate a new rubygem client, you can run:
 
 ```
-$ atum MyApp schema.json https://api.myapp.com
+$ atum new fruity-api
 ```
 
-This will output a client into a new `my_app` folder, in the current directory,
-unless that folder exists.
+This will does several things:
+
+- Createa a new gem called fruity-api in a `fruity-api` folder in the current
+   directory
+
+   ```
+> atum new fruity-api
+      create  fruity-api/Gemfile
+      create  fruity-api/Rakefile
+      create  fruity-api/LICENSE.txt
+      create  fruity-api/README.md
+      create  fruity-api/.gitignore
+      create  fruity-api/fruity-api.gemspec
+      create  fruity-api/lib/fruity/api.rb
+      create  fruity-api/lib/fruity/api/version.rb
+Initializing git repo in /Users/petehamilton/projects/atum/fruity-api
+    ```
+- Creates a `.atum.yml` file in the root of the gem and populate it with:
+   ```
+   gem_name: fruity-api
+   constant_name: FruityApi
+   ```
+   You can add more configuration options to this file to prevent having to add
+   lots of command line arguments later. See below.
+
+#### 2. Generate the client files
+
+Now you have a gem, you need to populate the lib directory. To do this, navigate
+to the root of your gem and run:
+
+```
+$ atum generate --file PATH_TO_SCHEMA --url API_URL
+```
+
+*Note: You can store the file and url config in your .atum.yml file for
+convenience*
+
 
 ### Passing custom headers
 
 If your client needs to pass custom headers with each request these can be
-specified using `-H`:
+specified using `--default-headers or -H`:
 
 ```
-atum -H "Accept: application/vnd.myapp+json; version=3" MyApp schema.json https://api.myapp.com
+atum generate -H 'Accept: application/vnd.myapp+json; version=3'
 ```
 
-Pass multiple `-H` options if you need more than one custom header.
+To pass multiple headers, just give multiple strings:
+
+```
+atum generate -H 'header1' 'header2' 'header3'
+```
+
+You can also define a default\_headers section in your .atum.yml file.
+
+```
+default_headers:
+  - Accept: application/vnd.myapp+json; version=3
+  - Accept-Language: Fr
+```
 
 ### Generating API documentation
 
-The generated client has [Yard](http://yardoc.org/)-compatible docstrings.
-You can generate documentation using `yard`:
+The generated client has [Yard](http://yardoc.org/)-compatible docstrings. You can therefore generate documentation using `yard`:
 
-__not convinced this is actually correct now it's a directory?__
 ```
-yard doc -m markdown my_app
+yard doc -m markdown .
 ```
 
 This will generate HTML in the `docs` directory.  Note that Yard creates an
@@ -61,21 +106,37 @@ through Jekyll.
 
 ### Handling failures
 
-The client uses [Faraday](https://github.com/lostisland/faraday) for doing the
-HTTP requests, which chooses the most appropriate library for the runtime and
-other cool things. As such, you may encounter Faraday errors, which are mostly
-subclasses of `Faraday::ClientError`.
-
-```ruby
-begin
-  client.app.create('name' => 'example')
-rescue Faraday::ClientError => error
-  puts error
-end
+When an API returns an error, Atum will return an `ApiError`.
+
+Assuming the error response form the server is in JSON format, like:
+
+```
+{
+  "error": {
+    "documentation_url": "https://developer.gocardless.com/enterprise#validation_failed",
+    "message": "Validation failed",
+    "type": "validation_failed",
+    "code": 422,
+    "request_id": "dd50eaaf-8213-48fe-90d6-5466872efbc4",
+    "errors": [
+      {
+        "message": "must be a number",
+        "field": "sort_code"
+      }, {
+        "message": "is the wrong length (should be 8 characters)",
+        "field": "sort_code"
+      }
+    ]
+  }
+}
 ```
 
+Atum will return an Atum::Core::ApiError error. You can access the raw hash (unenveloped) via a `.errors` method, otherwise the error message will contain the error's message and a link to the documentation if it exists.
+
+
+
 ## Supporting Ruby < 2.0.0
-This gem only directly supports Ruby >= 2.0.0 out of the box due to our use of
+Atum only supports Ruby >= 2.0.0 out of the box due to our use of
 Enumerable::Lazy for lazy loading of paginated API resources.
 
 However, support for previous ruby versions can be added using a gem such as

data/atum.gemspec

@@ -1,5 +1,3 @@
-# coding: utf-8
-
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
@@ -9,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.name          = 'atum'
   spec.version       = Atum::VERSION
   spec.authors       = %w(isaacseymour petehamilton)
-  spec.email         = ['i.seymour@oxon.org', 'peterejhamilton@gmail.com']
+  spec.email         = %w(isaac@gocardless.com pete@gocardless.com)
   spec.description   = 'A Ruby client generator for JSON APIs described with a JSON schema'
   spec.summary       = 'A Ruby client generator for JSON APIs described with a JSON schema'
   spec.homepage      = 'https://github.com/gocardless/atum'
@@ -29,9 +27,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'webmock', '~> 1.18'
   spec.add_development_dependency 'pry-nav', '~> 0.2'
   spec.add_development_dependency 'yard', '~> 0.8'
-  spec.add_development_dependency 'appraisal', '~> 1.0.2'
 
   spec.add_dependency 'erubis', '~> 2.7'
   spec.add_dependency 'faraday', '>= 0.8.9'
   spec.add_dependency 'activesupport', '~> 4.1'
+  spec.add_dependency 'thor', '~> 0.19'
 end

data/bin/atum

@@ -1,41 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'optparse'
 require 'atum'
 
-options = { headers: {} }
-
-option_parser = OptionParser.new do |opts|
-  opts.banner = 'Usage: atum module_name schema_filename url'
-
-  opts.on('-h', '--help', 'Display this screen') do
-    puts opts
-    exit
-  end
-
-  opts.on('-v', '--version', 'Display the version atum is running at') do
-    puts Atum::VERSION
-    exit
-  end
-
-  opts.on('-H', '--header [HEADER]',
-          'Include header with all requests') do |header|
-    header_key, header_value, _ = header.split(':', 0)
-    options[:headers][header_key] = header_value.strip
-  end
-end
-
-option_parser.parse!
-
-if ARGV.length != 3
-  puts option_parser
-  exit
-end
-
-options = { default_headers: options[:headers] }
-
-module_name, schema_filename, url = ARGV
-
-generator = Atum::Generation::GeneratorService.new(module_name, schema_filename,
-                                                   url, options)
-generator.generate_files
+Atum::Generation::CLI.start(ARGV)

data/lib/atum/generation.rb

@@ -13,3 +13,4 @@ require 'atum/generation/generators/base_generator'
 require 'atum/generation/generators/module_generator'
 require 'atum/generation/generators/client_generator'
 require 'atum/generation/generators/resource_generator'
+require 'atum/generation/cli'

data/lib/atum/generation/cli.rb

@@ -0,0 +1,145 @@
+require 'thor'
+require 'yaml'
+require 'fileutils'
+
+# rubocop:disable Metrics/ClassLength
+module Atum
+  module Generation
+    class CLI < Thor
+      desc 'new <client_name>', 'create a new client gem'
+      def new(client_name)
+        # Generate a basic gem
+        run_command("bundle gem #{client_name}")
+
+        # Add atum to the gemspec file
+        run_command("sed -i '$ d' #{client_name}/#{client_name}.gemspec")
+        run_command("echo '\n  spec.add_runtime_dependency \"atum\", " \
+                    "\"~> #{Atum::VERSION}\"' >> " \
+                    "#{client_name}/#{client_name}.gemspec")
+        run_command("echo 'end' >> #{client_name}/#{client_name}.gemspec")
+
+        # Populate a .atum file in the root
+        Dir.chdir(client_name) do
+          File.open('.atum.yml', 'w') do |f|
+            names = name_versions(client_name)
+            f.puts "gem_name: #{client_name}"
+            f.puts "constant_name: #{names[:constant_name]}"
+          end
+        end
+      end
+
+      desc 'generate', 'generate the atum client in a lib directory'
+      option :default_headers,
+             aliases: '-H',
+             desc: 'A comma separated list of headers, ' \
+                   'e.g. Api-Version: 2010-10-03, Accept-Language: Fr',
+             default: '',
+             type: 'array'
+      option :constant_name, desc: 'e.g. FruityApi'
+      option :file
+      option :url
+      option :gem_name
+      option :commit, type: :boolean,
+                      desc: 'Automatically commit the generated code'
+      def generate
+        config = options_from_atum_file.merge(options)
+        validate_config(config)
+
+        names = name_versions(config['gem_name'])
+        config['constant_name'] = names[:constant_name]
+
+        # Preserve the version file
+        version_file = File.join('lib', names[:namespaced_path], 'version.rb')
+        version_file_content = File.read(version_file)
+
+        # Nuke everything in the lib folder
+        FileUtils.rm_rf('lib/*')
+
+        # Regenerate everything in the lib folder
+        regenerate_lib_folder(config)
+
+        # Re-write the version file
+        File.open(version_file, 'w') { |f| f.write(version_file_content) }
+
+        # Print advice
+        print_closing_message
+      end
+
+      desc 'version', 'print Atum version'
+      def version
+        print Atum::VERSION, "\n"
+      end
+
+      no_commands do
+
+        def options_from_atum_file
+          File.file?('.atum.yml') ? YAML.load_file('.atum.yml') : {}
+        end
+
+        def validate_config(config)
+          common = ' (either in .atum.yml or via cli options)'
+          begin
+            raise 'gem_name must be given' + common unless config.key?('gem_name')
+            raise 'file must be given' + common unless config.key?('file')
+            raise 'url must be given' + common unless config.key?('url')
+          rescue => e
+            message "Error: #{e.message}\n"
+            help(:generate)
+            exit
+          end
+        end
+
+        def parse_headers(hs)
+          Hash[hs.map { |header| header.split(':').map(&:strip) }]
+        end
+
+        def message(msg = nil)
+          print "#{msg}\n"
+        end
+
+        def run_command(cmd)
+          system(cmd)
+        end
+
+        def regenerate_lib_folder(config)
+          Dir.chdir('lib') do
+            Atum::Generation::GeneratorService.new(
+              config['constant_name'], config['file'], config['url'],
+              default_headers: parse_headers(options['default_headers'])
+            ).generate_files
+          end
+        end
+
+        def print_closing_message
+          message "Successfully regenerated with atum v#{Atum::VERSION})\n"
+          timestamp = Time.now.utc.iso8601
+          cmd = "git add . -A && git commit -am 'Regenerated client on " \
+                "#{timestamp} (atum v#{Atum::VERSION})'"
+
+          if options['commit']
+            message 'Staging files and committing changes...'
+            system(cmd)
+          else
+            message "We suggest you now run:\n"
+            message "\t#{cmd}\n"
+            message 'Or, run the command with the --commit flag to do this automatically'
+          end
+        end
+
+        def name_versions(name)
+          constant_name = name.split('_').map { |p| p[0..0].upcase + p[1..-1] }.join
+          if constant_name =~ /-/
+            constant_name = constant_name.split('-')
+                                         .map { |q| q[0..0].upcase + q[1..-1] }
+                                         .join('::')
+          end
+
+          { underscored_name: name.tr('-', '_'),
+            namespaced_path: name.tr('-', '/'),
+            constant_name: constant_name,
+            constant_array: constant_name.split('::') }
+        end
+      end
+    end
+  end
+end

data/lib/atum/generation/erb_context.rb

@@ -5,13 +5,24 @@ module Atum
         starter = ('  ' * tabs) + '# '
         max_line_length = 78 - (tabs * 2)
         comment.split("\n")
-          .map { |l| l.scan(/.{1,#{max_line_length}}/) }
-          .flatten.map { |l| starter + l.strip }.join("\n")
+               .flat_map { |l| break_line(l, max_line_length) }
+               .map { |l| starter + l.strip }
+               .join("\n")
       end
 
       def method(name, params)
         "#{name}" + (params.length > 0 ? "(#{params})" : '')
       end
+
+      def break_line(line, max_line_length)
+        line.split.reduce([]) do |lines, word|
+          if lines.empty? || (lines[-1] + " #{word}").size > max_line_length
+            lines << word
+          else
+            lines[-1] << " #{word}" && lines
+          end
+        end
+      end
     end
   end
 end

data/lib/atum/generation/generators/views/module.erb

@@ -13,10 +13,10 @@ module <%= @module_name.split("::")[0..i].join("::") %>; end
 <% end %>
 
 version_file = '<%= @module_name.downcase.underscore.split("/").last %>/version'
-if File.file?(version_file)
-require version_file
+if File.file? File.expand_path("#{version_file}.rb", File.dirname(__FILE__))
+  require_relative version_file
 else
-<%= "#{@module_name}::VERSION" %> = ''
+  <%= "#{@module_name}::VERSION" %> = ''
 end
 require_relative '<%= @module_name.downcase.underscore.split("/").last %>/client'
 <% @resources.each do |resource| %>

data/lib/atum/version.rb

@@ -1,3 +1,3 @@
 module Atum
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/spec/atum/generation/erb_context_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe Atum::Generation::ErbContext do
+  let(:ctx) { described_class.new }
+  describe '#commentify' do
+    let(:tabs) { 0 }
+    subject(:result) { ctx.commentify(comment, tabs) }
+
+    context 'when the comment is more than 78 characters' do
+      let(:comment) { (['abc '] * 20).join }
+      it 'should wrap by word' do
+        firstline  = '# ' + (['abc '] * 19).join.strip
+        secondline = '# abc'
+        expect(result).to eq(firstline + "\n" + secondline)
+      end
+    end
+  end
+end

data/spec/integration/client_integration_spec.rb

@@ -7,19 +7,23 @@ describe 'The Generated Client' do
   end
   let(:url) { 'http://USER:PASSWORD@api.fruity.com/fruits' }
   let(:tmp_folder) do
-    File.expand_path(File.join('..', '..', '..', 'tmp'), File.dirname(__FILE__))
+    File.expand_path(File.join('..', '..', 'tmp'), File.dirname(__FILE__))
   end
   let(:options) { { path: File.join(tmp_folder, 'client') } }
   let(:generator_service) do
     Atum::Generation::GeneratorService.new(name, schema_file, url, options)
   end
+  let(:pre_generation_setup) { -> { generator_service.generate_files } }
 
-  before do
-    generator_service.generate_files
-    require File.join(options[:path], 'fruity')
+  around(:each) do |example|
+    pre_generation_setup.call
+    load File.join(options[:path], 'fruity.rb')
     Fruity.connect(url, 'USER', 'PASSWORD')
+    example.run
+    Fruity.send(:remove_const, 'VERSION')
+    Fruity.send(:remove_const, 'SCHEMA')
+    FileUtils.rm_rf(options[:path])
   end
-  after { FileUtils.rm_rf(tmp_folder) }
 
   it 'can make get requests' do
     stub = WebMock.stub_request(:get, "#{url}/lemon")
@@ -88,4 +92,29 @@ describe 'The Generated Client' do
       .with(body: body.to_json)
     expect(Fruity.lemon.create(body: body))
   end
+
+  context "when a version file doesn't exist" do
+    it "doesn't define VERSION" do
+      expect(Fruity::VERSION).to eq('')
+    end
+  end
+
+  context 'when a version file exists' do
+    let(:version) { '1.2.3' }
+    let(:pre_generation_setup) do
+      lambda do
+        generator_service.generate_files
+        file = File.expand_path(File.join(options[:path], 'fruity', 'version.rb'))
+        File.open(file, 'w') do |f|
+          f.write "module #{name}\n"
+          f.write "  VERSION = '#{version}'\n"
+          f.write 'end'
+        end
+      end
+    end
+
+    it 'includes a version file for the client when one exists' do
+      expect(Fruity::VERSION).to eq(version)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atum
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - isaacseymour
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-09 00:00:00.000000000 Z
+date: 2014-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -137,20 +137,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: appraisal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 1.0.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 1.0.2
 - !ruby/object:Gem::Dependency
   name: erubis
   requirement: !ruby/object:Gem::Requirement
@@ -193,10 +179,24 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.19'
 description: A Ruby client generator for JSON APIs described with a JSON schema
 email:
-- i.seymour@oxon.org
-- peterejhamilton@gmail.com
+- isaac@gocardless.com
+- pete@gocardless.com
 executables:
 - atum
 extensions: []
@@ -207,7 +207,6 @@ files:
 - .rubocop.yml
 - .rubocop_todo.yml
 - .travis.yml
-- Appraisals
 - CHANGELOG.md
 - CONTRIBUTING.md
 - CONTRIBUTORS.md
@@ -238,6 +237,7 @@ files:
 - lib/atum/core/schema/parameter_choice.rb
 - lib/atum/core/schema/resource_schema.rb
 - lib/atum/generation.rb
+- lib/atum/generation/cli.rb
 - lib/atum/generation/erb_context.rb
 - lib/atum/generation/errors.rb
 - lib/atum/generation/generator_link.rb
@@ -264,6 +264,7 @@ files:
 - spec/atum/core/schema/parameter_choice_spec.rb
 - spec/atum/core/schema/parameter_spec.rb
 - spec/atum/core/schema/resource_schema_spec.rb
+- spec/atum/generation/erb_context_spec.rb
 - spec/atum/generation/generator_link_spec.rb
 - spec/atum/generation/generator_resource_spec.rb
 - spec/atum/generation/generator_service_spec.rb
@@ -301,3 +302,4 @@ signing_key:
 specification_version: 4
 summary: A Ruby client generator for JSON APIs described with a JSON schema
 test_files: []
+has_rdoc: 

data/Appraisals

@@ -1,9 +0,0 @@
-appraise "faraday-0.8.9" do
-  gem "faraday", "~> 0.8.9"
-  gem "atum", :path => "../"
-end
-
-appraise "faraday-0.9" do
-  gem "faraday", "~> 0.9"
-  gem "paperclip", :path => "../"
-end