evoke 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 46a11e1fe28465d778a34db82f633bff896279f3
-  data.tar.gz: 3e1fa45b6a7ba1759eb1c968388797f5ec7f0e4a
+  metadata.gz: 469f902eb78d1d43894adf316bd4ec3e428a1d3e
+  data.tar.gz: 257b7371196e71be263e7fda29a6e319cfc4177c
 SHA512:
-  metadata.gz: 2d9ad91ede3f0176a1641b2da5e8a486065f9f354433d4e0ab725cf813fd47484fa9d3789f581cd4ff2b6f5dc70c3a4014d5ab2d3248b0221fe9af4fb6c8a81b
-  data.tar.gz: 6847b441d5195c99eeb8bcfa790b11ae44d1e7b811c71331a6e9d68770dd35aa134873a7079ce8bf26428a805ff6c71eb3b4c52c00d7e9fdc0f919f31133e625
+  metadata.gz: da52e32aea945842bf8189c233b73005788fdafecb36a1229513533f3b75db1de124d31714ed820e09f2c8351fa72845cace43df705b50a0f4b0ea19e1a84da5
+  data.tar.gz: 2c382315f9b99381ac9d6854a98a94f5ce538b6006db24b73e73476cc9e0db8d56b379509ee83fa76f72432973538f22f51912d33d01af65d72a00b38fffdf10

data/.rubocop.yml

@@ -10,9 +10,22 @@ Lint/UnusedMethodArgument:
 Style/EmptyLinesAroundClassBody:
   Enabled: false
 
+Style/TrivialAccessors:
+  Enabled: false
+
+Style/AlignParameters:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
 Metrics/MethodLength:
   Enabled: true
   Max: 15
 
 Metrics/AbcSize:
   Enabled: false
+
+Metrics/LineLength:
+  Enabled: true
+  Max: 90

data/.travis.yml

@@ -1,3 +1,9 @@
 language: ruby
 rvm:
   - 2.0.0
+
+addons:
+  code_climate:
+    repo_token: 6cc2a484a3960daa5e16ecdc42e7ccfbb22b32e75b09ecc6707c3330e826ba4b
+
+before_install: gem install bundler --pre

data/Gemfile

@@ -1,4 +1,5 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in evoke.gemspec
 gemspec
+
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -1,5 +1,11 @@
 # Evoke
 
+[![GitHub version](https://badge.fury.io/gh/travishaynes%2Fevoke.svg)](http://badge.fury.io/gh/travishaynes%2Fevoke)
+[![Build Status](https://travis-ci.org/travishaynes/evoke.svg)](https://travis-ci.org/travishaynes/evoke)
+[![Code Climate](https://codeclimate.com/github/travishaynes/evoke/badges/gpa.svg)](https://codeclimate.com/github/travishaynes/evoke)
+[![Test Coverage](https://codeclimate.com/github/travishaynes/evoke/badges/coverage.svg)](https://codeclimate.com/github/travishaynes/evoke)
+[![Inline docs](http://inch-ci.org/github/travishaynes/evoke.svg)](http://inch-ci.org/github/travishaynes/evoke)
+
 A lightweight, zero-dependency task tool for Ruby.
 
 ## Installation
@@ -13,36 +19,45 @@ A lightweight, zero-dependency task tool for Ruby.
 Evoke tasks are Ruby classes that look like this:
 
 ```ruby
+# Prints a friendly message to the console.
+#
+# This comment actually does something. The first line is used as a short
+# description when `evoke help` or `evoke` is called without any arguments.
+# The rest of the comment is printed, along with the first line, when
+# `evoke help hello_world` is called to pull up help about this specific task.
 class HelloWorld < Evoke::Task
-  # This description appears when your run `evoke` without any arguments.
-  desc "Prints a friendly message"
 
-  # This method is called by Evoke when the task is executed.
+  # The initializer of an Evoke::Task cannot have any required parameters.
+  def initialize
+  end
+
+  # Called when this method is invoked on the command-line. This task would be
+  # invoked using `evoke hello_world`.
   def invoke
     puts "Hello world!"
   end
 end
 ```
 
-**Important:** Initializers for Evoke::Tasks cannot have any required arguments.
-
-This task would be invoked from the command-line with `evoke hello_world`.
-
 #### Namespacing
 
 Tasks are namespaced using modules. Their command names are underscored from
 their Ruby class names. For example, a task named `Example::HelloWorld` would be
 invoked on the command line with `evoke example/hello_world`.
 
-#### Command-line-arguments
+#### Command-Line Arguments
 
 Here's an example of a task that uses command-line arguments and is namespaced.
 
 ```ruby
 module Math
   class Add < Evoke::Task
+    # This can be used as an alternative to providing the short description in
+    # the class comment.
     desc "Adds two integers and prints the result in the console"
 
+    # All parameters come through as strings since they are read from the
+    # arguments supplied on the command-line.
     def invoke(a, b)
       puts a.to_i + b.to_i
     end
@@ -50,19 +65,50 @@ module Math
 end
 ```
 
-**Note:** All arguments come through as strings since they are read from the
-command-line.
-
 This task would be invoked from the command-line with `evoke math/add 5 10`,
 where a=5 and b=10 in this example.
 
-Switches are not currently supported. Use environment variables to use named
-arguments. Here's the same example as above using environment variables:
+#### Optional Arguments
+
+Variable-assigned optional parameters are supported. Key based, `&block` and
+`*` parameters are not and will raise an error.
+
+```ruby
+# SUPPORTED
+def invoke(req, opt='optional argument'); end
+
+# NOT SUPPORTED - errors will be raised
+def invoke(opt: 'optional argument'); end
+def invoke(*args); end
+def invoke(&block); end
+```
+
+
+#### Named Arguments
+
+Environment variables are used for named arguments. Make sure to document the
+required environment variables in the class comment of the task, perhaps even
+including some examples. Normal parameters are displayed in the tasks' help,
+environment variables are not.
+
+Here's an example of the `math/add` task from earlier using named arguments that
+is well documented:
 
 ```ruby
 module Math
+  # Adds two integers and prints the result in the console.
+  #
+  # Two environment variables are required to use this task: A and B.
+  #
+  # == Example: Adding 5 and 10.
+  #
+  #     evoke math/add A=5 B=10
+  #
+  # == Example: Adding 2 and 3.
+  #
+  #     evoke math/add A=2 B=3
+  #
   class Add < Evoke::Task
-    desc "Adds two integers and prints the result in the console"
 
     def initialize
       @a = ENV['A'].to_i
@@ -76,15 +122,15 @@ module Math
 end
 ```
 
-This task would be invoked from the command-line with `evoke math/add A=5 B=10`.
-
-#### Syntax Usage
+#### Documenting Tasks
 
 Using `evoke help` will give the user a more detailed description on how to use
 the task. Providing this description is as easy as adding a comment to the
 task's class. For example:
 
 ```ruby
+# Prints the sum of two integers.
+#
 # This is a completely useless task that allows you to add two numbers together
 # in the console using Evoke, a command-line task tool for Ruby.
 #
@@ -94,17 +140,22 @@ task's class. For example:
 #
 # This comment is displayed for this task when you run `evoke help add`.
 class Add < Evoke::Task
-  desc "Prints the sum of two integers."
-
   def invoke(a, b)
     puts a.to_i + b.to_i
   end
 end
 ```
 
-Alternately, you can use the #syntax class method:
+Alternately, you can use the `#syntax` and `#desc` class methods, which will
+take precedence over the class comment.
 
 ```ruby
+# This class comment will not be used to display help for this task because both
+# the short and long descriptions are provided using #desc and #syntax.
+#
+# If only the #syntax method was used, the first line of this comment would
+# still be used for the short description, and vice-versa. Both methods need to
+# be used to completely disregard this comment.
 class Add < Evoke::Task
   desc "Prints the sum of two integers."
   syntax "Provide two integers as arguments to this task."

data/Rakefile

@@ -2,7 +2,7 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.libs << "test"
+  t.libs << 'test'
   t.test_files = FileList['test/**/*_test.rb']
 end
 

data/lib/evoke.rb

@@ -10,7 +10,7 @@ module Evoke
     #
     # @return [Array] The task classes.
     def tasks
-      ObjectSpace.each_object(Class).select {|klass| klass < Evoke::Task }
+      ObjectSpace.each_object(Class).select { |klass| klass < Evoke::Task }
     end
 
     # Finds a task with the supplied name.
@@ -22,7 +22,7 @@ module Evoke
     #     Evoke.find_task('example/hello_world') # => Example::HelloWorld
     #
     def find_task(name)
-      tasks.find {|task| task.to_s == name.camelize }
+      tasks.find { |task| task.to_s == name.camelize }
     end
 
     # Loads all the Evoke tasks in the supplied path.
@@ -45,7 +45,7 @@ module Evoke
         path = File.expand_path(path)
       end
 
-      Dir[File.join(path, "**", "*_task.rb")].each {|f| load f }
+      Dir[File.join(path, '**', '*_task.rb')].each { |f| load f }
     end
 
     # Adds a code block that will be called before the task is invoked.
@@ -84,7 +84,7 @@ module Evoke
     # @param [Evoke::Task] task The task instance that is being invoked.
     # @param [Array] args The arguments that are being passed to the task.
     def call_before_hooks(task, *args)
-      Array(@before_hooks).each {|hook| hook.call(task, *args) }
+      Array(@before_hooks).each { |hook| hook.call(task, *args) }
     end
   end
 end

data/lib/evoke/cli.rb

@@ -13,9 +13,9 @@ module Evoke
     def start
       load_tasks
 
+      return no_tasks if tasks.empty?
       return usage if @command.nil?
-
-      return syntax if @command == "help"
+      return syntax if @command == 'help'
 
       task = Evoke.find_task(@command) unless @command.nil?
 
@@ -24,6 +24,8 @@ module Evoke
       Evoke.invoke(task, *@arguments)
     end
 
+    private
+
     # Prints the syntax usage of the task requested by help.
     def syntax
       return usage if @arguments.empty?
@@ -35,24 +37,26 @@ module Evoke
       return unknown_command if task.nil?
 
       task.print_syntax
+
+      exit(2)
     end
 
     # Prints the usage for all the discovered tasks.
     def usage
-      name_col_size = task_names.group_by(&:size).keys.max.to_i + 2
-      tasks.each {|task| task.print_usage(name_col_size) }
+      grouped_tasks = task_names.group_by(&:size)
+      name_sizes = grouped_tasks.keys
+      biggest_name = name_sizes.max || 0
+      tasks.each { |task| task.print_usage(biggest_name + 2) }
 
       exit(2)
     end
 
-    private
-
     # Gets the path for the local evoke.rb file. This doesn't check if the file
     # actually exists, it only returns the location where it might be.
     #
     # @return [String] The path for the evoke file.
     def evoke_file
-      @evoke_file = File.join(Dir.pwd, "evoke.rb")
+      @evoke_file = File.join(Dir.pwd, 'evoke.rb')
     end
 
     # Loads the Evoke tasks. This will first search for a file named `evoke.rb`
@@ -63,21 +67,18 @@ module Evoke
       return load(evoke_file) if File.file?(evoke_file)
 
       # Load the tasks from the current working directory.
-      Evoke.load_tasks("lib/tasks")
-
-      # No reason to continue if there are no tasks to work with.
-      return no_tasks if tasks.empty?
+      Evoke.load_tasks('lib/tasks')
     end
 
     # Tells the user there are no tasks to invoke and exits with status 1.
     def no_tasks
-      STDERR.puts "No tasks found in the current working directory."
+      $stderr.puts 'No tasks found in the current working directory.'
       exit(1)
     end
 
     # Tells the user that the supplied task could not be found.
     def unknown_command
-      STDERR.puts "No task named #{@command.inspect}"
+      $stderr.puts "No task named #{@command.inspect}"
       exit(1)
     end
 
@@ -93,7 +94,7 @@ module Evoke
     #
     # @return [Array] The name of all the tasks.
     def task_names
-      @task_names ||= tasks.map {|task| task.name.underscore }
+      @task_names ||= tasks.map { |task| task.name.underscore }
     end
   end
 end

data/lib/evoke/comment.rb

@@ -7,33 +7,54 @@ module Evoke
   #     # comment that will be read.
   #     class HelloWorld
   #       extend Evoke::Comment
+  #
+  #       def a_method
+  #         # this won't work without at least one non-inherited method
+  #       end
   #     end
   #
   #     HelloWorld.class_comment # => the multi-line comment before the class
   #
   module Comment
     # Extracts the comment prefixing a class.
-    #
+    # @note At least one non-inherited method needs to be present in the class.
     # @return [String] The class' comment.
     def class_comment
-      start_line, lines = start_index_and_code_lines
+      @class_comment ||= defined_methods.empty? ? '' : extract_class_comment
+    end
 
-      comment = []
+    private
 
-      (start_line - 1).downto(0).each do |i|
-        line = lines[i].strip
+    # Reads the class's file and extracts the comment of the class that extends
+    # this module.
+    #
+    # @return [String] The multi-line string before the class.
+    def extract_class_comment
+      bottom_line, lines = start_index_and_code_lines
 
-        if line.start_with?('#')
-          comment << line[1..line.length].strip
-        elsif comment != ''
-          break
-        end
+      comment = []
+
+      (bottom_line - 1).downto(0).each do |i|
+        line = parse_comment_line(lines[i])
+        break if line == false
+        comment << line
       end
 
-      comment.reverse.join("\n")
+      comment.reverse.join("\n").strip
     end
 
-    private
+    # Parses a line of code and extracts the comment if present.
+    #
+    # @param [String] line The line of code to parse.
+    # @return [NilClass] if the line is empty.
+    # @return [Boolean] false if the line is not a comment.
+    # @return [String] The extracted comment, without the prefixed # tag.
+    # @private
+    def parse_comment_line(line)
+      line = line.strip
+      return if line.empty?
+      line.start_with?('#') ? line[1..line.length].strip : false
+    end
 
     # Gets the lines in the class file and the line number that the class is
     # actually defined.
@@ -68,10 +89,12 @@ module Evoke
     # @return [Array] The source locations of every method in the class.
     # @private
     def defined_methods
-      methods = methods(false).map { |m| method(m) }
-      methods += instance_methods(false).map { |m| instance_method(m) }
-      methods.map!(&:source_location)
-      methods.compact
+      @defined_methods ||= begin
+        methods = methods(false).map { |m| method(m) }
+        methods += instance_methods(false).map { |m| instance_method(m) }
+        methods.map!(&:source_location)
+        methods.compact
+      end
     end
   end
 end

data/lib/evoke/inflections.rb

@@ -3,9 +3,10 @@ module Evoke
   # different purposes.
   module Inflections
     # Load the inflections.
-    Dir[File.expand_path("../inflections/*.rb", __FILE__)].each {|f| require f }
+    inflections_path = File.expand_path('../inflections/*.rb', __FILE__)
+    Dir[inflections_path].each { |f| require f }
 
     # Add the inflections to the String class.
-    constants.each {|i| String.send(:include, const_get(i)) }
+    constants.each { |i| String.send(:include, const_get(i)) }
   end
 end

data/lib/evoke/inflections/camelize.rb

@@ -1,35 +1,39 @@
-# String inflections for converting to CamelCase.
-#
-# Camelizing a string takes all the compound words separated by an underscore
-# and combines them together, capitalizing the first letter of each word. It
-# also converts '/' to '::'. For example "hello_world" is camelized to
-# "HelloWorld", and "hello/world" is camelized to "Hello::World".
-module Evoke::Inflections::Camelize
-  # Converts a string to CamelCase. It also converts '/' to '::'.
-  #
-  # @example Camelize the string "example/hello_world".
-  #
-  #     "example/hello_world".camelize # => "Example::HelloWorld"
-  #
-  # @return [String] The CamelCase string.
-  def camelize
-    dup.tap {|s|
-      s.capitalize!
-      s.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
-      s.gsub!("/", "::")
-    }
-  end
+module Evoke
+  module Inflections
+    # String inflections for converting to CamelCase.
+    #
+    # Camelizing a string takes all the compound words separated by an underscore
+    # and combines them together, capitalizing the first letter of each word. It
+    # also converts '/' to '::'. For example "hello_world" is camelized to
+    # "HelloWorld", and "hello/world" is camelized to "Hello::World".
+    module Camelize
+      # Converts a string to CamelCase. It also converts '/' to '::'.
+      #
+      # @example Camelize the string "example/hello_world".
+      #
+      #     "example/hello_world".camelize # => "Example::HelloWorld"
+      #
+      # @return [String] The CamelCase string.
+      def camelize
+        dup.tap do |s|
+          s.capitalize!
+          s.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
+          s.gsub!('/', '::')
+        end
+      end
 
-  # Replaces the existing String instance with a CamelCase string.
-  #
-  # @example Camelizing the string "example/hello_world".
-  #
-  #     string = "example/hello_world"
-  #     string.camelize!
-  #     string # => "Example::HelloWorld"
-  #
-  # @return [String] This string modified to CamelCase.
-  def camelize!
-    replace(camelize)
+      # Replaces the existing String instance with a CamelCase string.
+      #
+      # @example Camelizing the string "example/hello_world".
+      #
+      #     string = "example/hello_world"
+      #     string.camelize!
+      #     string # => "Example::HelloWorld"
+      #
+      # @return [String] This string modified to CamelCase.
+      def camelize!
+        replace(camelize)
+      end
+    end
   end
 end

data/lib/evoke/inflections/underscore.rb

@@ -1,38 +1,42 @@
-# String inflections for converting to underscored form.
-#
-# Underscoring a string injects an underscore between CamelCase words, replaces
-# all '::' with '/' and converts the string to lowercase. For example, the
-# string "HelloWorld" is underscored to "hello_world", and the string
-# "Hello::World" is underscored to "hello/world".
-module Evoke::Inflections::Underscore
-  # Creates an underscored, lowercase form of the string and changes '::' to '/'
-  # to convert namespaces to paths.
-  #
-  # @example Underscoring "Example::HelloWorld".
-  #
-  #     "Example::HelloWorld" # => "example/hello_world"
-  #
-  # @return [String] The underscored string.
-  def underscore
-    dup.tap {|s|
-      s.gsub!(/::/, '/')
-      s.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
-      s.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
-      s.tr!("-", "_")
-      s.downcase!
-    }
-  end
+module Evoke
+  module Inflections
+    # String inflections for converting to underscored form.
+    #
+    # Underscoring a string injects an underscore between CamelCase words, replaces
+    # all '::' with '/' and converts the string to lowercase. For example, the
+    # string "HelloWorld" is underscored to "hello_world", and the string
+    # "Hello::World" is underscored to "hello/world".
+    module Underscore
+      # Creates an underscored, lowercase form of the string and changes '::' to '/'
+      # to convert namespaces to paths.
+      #
+      # @example Underscoring "Example::HelloWorld".
+      #
+      #     "Example::HelloWorld" # => "example/hello_world"
+      #
+      # @return [String] The underscored string.
+      def underscore
+        dup.tap do |s|
+          s.gsub!(/::/, '/')
+          s.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          s.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+          s.tr!('-', '_')
+          s.downcase!
+        end
+      end
 
-  # Replaces the existing String instance with its underscored form.
-  #
-  # @example Underscoring the string "Example::HelloWorld".
-  #
-  #     string = "Example::HelloWorld"
-  #     string.underscore!
-  #     string # => "example/hello_world"
-  #
-  # @return [String] This underscored form of the original string.
-  def underscore!
-    replace(underscore)
+      # Replaces the existing String instance with its underscored form.
+      #
+      # @example Underscoring the string "Example::HelloWorld".
+      #
+      #     string = "Example::HelloWorld"
+      #     string.underscore!
+      #     string # => "example/hello_world"
+      #
+      # @return [String] This underscored form of the original string.
+      def underscore!
+        replace(underscore)
+      end
+    end
   end
 end

data/lib/evoke/parameters.rb

@@ -1,6 +1,18 @@
 module Evoke
   # Extendable module for providing access to method parameters during runtime.
   module Parameters
+    # Finds the minimum and maximum amount of parameters the supplied method
+    # supports.
+    #
+    # @param [UnboundMethod] method The method to check.
+    # @return [Array] The first item is the minimum size, second is the maximum.
+    def parameter_size(method)
+      req_size = required_parameters(method).size
+      opt_size = optional_parameters(method).size
+
+      [req_size, req_size + opt_size]
+    end
+
     # Gets all the required parameters for a method.
     #
     # @param [UnboundMethod] method The method to scan.

data/lib/evoke/task.rb

@@ -9,8 +9,11 @@ module Evoke
       # @param [Integer] name_col_size The size of the name column.
       # @private
       def print_usage(name_col_size)
+        description = "#{@desc || class_comment}".split("\n")[0]
+        description ||= 'No description available.'
+
         $stdout.print name.underscore.ljust(name_col_size)
-        $stdout.puts "# #{@desc || 'No description.'}"
+        $stdout.puts "# #{description}"
       end
 
       # Prints the syntax usage for this task to the console.
@@ -31,7 +34,7 @@ module Evoke
       # @param [String] value The description. Keep it short!
       # @return [String] The supplied description.
       def desc(value)
-        value += "." unless value.end_with?(?.)
+        value += '.' unless value.end_with?('.')
         @desc = value
       end
 
@@ -61,13 +64,17 @@ module Evoke
       # @return nil if the validation passes.
       # @private
       def validate_arguments(arguments)
-        e_size = instance_method(:invoke).arity
-        a_size = Array(arguments).size
+        invoke_method = instance_method(:invoke)
+        min, max = parameter_size(invoke_method)
+
+        size = Array(arguments).size
+        return if size >= min && size <= max
+
+        e_size = min == max ? min : "#{min}..#{max}"
 
-        return if e_size == a_size
+        $stderr.print 'Wrong number of arguments. '
+        $stderr.print "Received #{size} instead of #{e_size}.\n"
 
-        $stderr.print "Wrong number of arguments. "
-        $stderr.print "Received #{a_size} instead of #{e_size}.\n"
         exit(1)
       end
     end

data/lib/evoke/version.rb

@@ -1,3 +1,3 @@
 module Evoke
-  VERSION = "0.1.2"
+  VERSION = '0.1.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evoke
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Travis Haynes
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-03-05 00:00:00.000000000 Z
+date: 2015-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler