evoke 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de1ac06c3626655a6e1d041392fd749cfde7c820
-  data.tar.gz: 7d634505e1b52a26b03bc2aaef687678f458d62e
+  metadata.gz: 46a11e1fe28465d778a34db82f633bff896279f3
+  data.tar.gz: 3e1fa45b6a7ba1759eb1c968388797f5ec7f0e4a
 SHA512:
-  metadata.gz: 3bef13d6b793bbdaa4225cdf375579a2788e05b3dd47fa508ce301ce2e9f4c6809b847d69f26d127a3773b974866b833b6a37fd82468c22761ea20bd93e76a2e
-  data.tar.gz: 9b12056349fedfbbf8845e135f1303a574b6e8a637c13fa77b3a252894fa63ce67b070f4c777b739780c5a9464e29af8fe8b2f58dc6cf80af8a25fbb646d466b
+  metadata.gz: 2d9ad91ede3f0176a1641b2da5e8a486065f9f354433d4e0ab725cf813fd47484fa9d3789f581cd4ff2b6f5dc70c3a4014d5ab2d3248b0221fe9af4fb6c8a81b
+  data.tar.gz: 6847b441d5195c99eeb8bcfa790b11ae44d1e7b811c71331a6e9d68770dd35aa134873a7079ce8bf26428a805ff6c71eb3b4c52c00d7e9fdc0f919f31133e625

data/.rubocop.yml

@@ -0,0 +1,18 @@
+Style/EmptyLineBetweenDefs:
+  Enabled: false
+
+Style/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: no_space
+
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: true
+  Max: 15
+
+Metrics/AbcSize:
+  Enabled: false

data/README.md

@@ -78,6 +78,43 @@ end
 
 This task would be invoked from the command-line with `evoke math/add A=5 B=10`.
 
+#### Syntax Usage
+
+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
+# 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.
+#
+# To use the task provide two integers via `evoke add A B`, where A and B are
+# the integers. For example: `evoke add 1 5` will result in the number 6 being
+# printed to the console. How completely pointless is that?
+#
+# 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:
+
+```ruby
+class Add < Evoke::Task
+  desc "Prints the sum of two integers."
+  syntax "Provide two integers as arguments to this task."
+
+  def invoke
+    puts a.to_i + b.to_i
+  end
+end
+```
+
 ### Loading Tasks
 
 There are two ways tasks can be loaded.

data/evoke.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors = ['Travis Haynes']
   spec.email = ['travis@hi5dev.com']
 
-  spec.summary = 'A build tool for Ruby.'
+  spec.summary = 'A low-profile, zero-dependency command-line task tool for Ruby.'
   spec.license = 'MIT'
 
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

data/lib/evoke/cli.rb

@@ -15,6 +15,8 @@ module Evoke
 
       return usage if @command.nil?
 
+      return syntax if @command == "help"
+
       task = Evoke.find_task(@command) unless @command.nil?
 
       return unknown_command if task.nil?
@@ -22,9 +24,22 @@ module Evoke
       Evoke.invoke(task, *@arguments)
     end
 
+    # Prints the syntax usage of the task requested by help.
+    def syntax
+      return usage if @arguments.empty?
+
+      @command = @arguments.shift
+
+      task = Evoke.find_task(@command)
+
+      return unknown_command if task.nil?
+
+      task.print_syntax
+    end
+
     # Prints the usage for all the discovered tasks.
     def usage
-      name_col_size = task_names.group_by(&:size).keys.max + 2
+      name_col_size = task_names.group_by(&:size).keys.max.to_i + 2
       tasks.each {|task| task.print_usage(name_col_size) }
 
       exit(2)
@@ -62,7 +77,7 @@ module Evoke
 
     # Tells the user that the supplied task could not be found.
     def unknown_command
-      STDERR.puts "No task for #{@command.inspect}"
+      STDERR.puts "No task named #{@command.inspect}"
       exit(1)
     end
 

data/lib/evoke/comment.rb

@@ -0,0 +1,77 @@
+module Evoke
+  # Extendable module for extracting multi-line comments for a class at runtime.
+  #
+  # @example Reading the comment of a class.
+  #
+  #     # This is the multi-line
+  #     # comment that will be read.
+  #     class HelloWorld
+  #       extend Evoke::Comment
+  #     end
+  #
+  #     HelloWorld.class_comment # => the multi-line comment before the class
+  #
+  module Comment
+    # Extracts the comment prefixing a class.
+    #
+    # @return [String] The class' comment.
+    def class_comment
+      start_line, lines = start_index_and_code_lines
+
+      comment = []
+
+      (start_line - 1).downto(0).each do |i|
+        line = lines[i].strip
+
+        if line.start_with?('#')
+          comment << line[1..line.length].strip
+        elsif comment != ''
+          break
+        end
+      end
+
+      comment.reverse.join("\n")
+    end
+
+    private
+
+    # Gets the lines in the class file and the line number that the class is
+    # actually defined.
+    #
+    # @param [Array] The start position is first, followed by the code lines.
+    # @private
+    def start_index_and_code_lines
+      data = read_class_file
+      pos = data =~ /class.*\s*#{simple_name}.*\s*\<.*/
+      [data[0..pos].count("\n"), data.split("\n")]
+    end
+
+    # The name of the class without a namespace.
+    #
+    # @return [String] The class' simple name.
+    # @private
+    def simple_name
+      name.rpartition('::')[2]
+    end
+
+    # Reads the file the class that extends this module is in.
+    #
+    # @return [String] The file's contents.
+    # @private
+    def read_class_file
+      path = defined_methods.first[0]
+      File.read(path)
+    end
+
+    # Gets all the methods a class has that are not inherited.
+    #
+    # @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
+    end
+  end
+end

data/lib/evoke/parameters.rb

@@ -0,0 +1,86 @@
+module Evoke
+  # Extendable module for providing access to method parameters during runtime.
+  module Parameters
+    # Gets all the required parameters for a method.
+    #
+    # @param [UnboundMethod] method The method to scan.
+    # @return [Array] An array of the method names.
+    def required_parameters(method)
+      select_parameters_by_type(method, :req)
+    end
+
+    # Gets all the optional parameters for a method.
+    #
+    # @param [UnboundMethod] method The method to scan.
+    # @return [Array] An array of the method names.
+    def optional_parameters(method)
+      select_parameters_by_type(method, :opt)
+    end
+
+    # Finds all the parameters of a given type for the supplied method.
+    #
+    # @example Get the key parameters for a method.
+    #
+    #     class Example
+    #       extend Evoke::Parameters
+    #
+    #       def hello(to: "world")
+    #         puts "Hello #{to}"
+    #       end
+    #     end
+    #
+    #     method = Example.instance_method(:hello)
+    #     key_params = Example.select_parameters_by_type(method, :key)
+    #
+    # @param [UnboundMethod] method The method to scan.
+    # @param [Symbol] type The type of method.
+    # @return [Array] An array of the method names.
+    def select_parameters_by_type(method, type)
+      args = method.parameters.select { |param| param[0] == type }
+      args.map { |arg| arg[1] }
+    end
+
+    # Parses the parameters for the supplied method into parameters that can be
+    # understood by humans. The method names are capitalized. Optional
+    # parameters are surrounded in brackets.
+    #
+    # @note Key and &block parameters are not supported.
+    #
+    # @param [UnboundMethod] method The method to scan.
+    # @return [Array] The human-readable method names.
+    # @raise [ArgumentError] if an unsupported parameter type is detected.
+    def parameter_names(method)
+      method.parameters.map { |type, name| parameter_name(method, type, name) }
+    end
+
+    private
+
+    # Parses a method parameter into a format that humans can understand.
+    #
+    # @param [UnboundMethod] method The method the parameter belongs to.
+    # @param [Symbol] type The parameter's type. Only :req and :opt supported.
+    # @param [Symbol] name The method's name.
+    # @return [String] The formatted parameter name.
+    # @raise [ArgumentError] if an unsupported parameter type is supplied.
+    # @private
+    def parameter_name(method, type, name)
+      case type
+      when :req then name.to_s.upcase
+      when :opt then "[#{name.to_s.upcase}]"
+      else unsupported_argument(method, name)
+      end
+    end
+
+    # Raised when a method has an unsupported parameter type.
+    #
+    # @param [UnboundMethod] method The method the parameter belongs o.
+    # @param [Symbol] name The method's name.
+    # @raise [ArgumentError] Backtraces to the source of the method.
+    # @private
+    def unsupported_argument(method, name)
+      message = "##{method.name} uses unsupported parameter type for #{name}"
+      source_location = method.source_location.join(':')
+      fail ArgumentError, message, source_location
+    end
+  end
+end

data/lib/evoke/task.rb

@@ -1,7 +1,10 @@
 module Evoke
   class Task
+    extend Evoke::Comment
+    extend Evoke::Parameters
+
     class << self
-      # Prints the usage of this task to the console.
+      # Prints the name and description of this task to the console.
       #
       # @param [Integer] name_col_size The size of the name column.
       # @private
@@ -10,8 +13,18 @@ module Evoke
         $stdout.puts "# #{@desc || 'No description.'}"
       end
 
-      # Describes the task. This message will be printed to the console when
-      # evoke is called without any arguments.
+      # Prints the syntax usage for this task to the console.
+      # @private
+      def print_syntax
+        params = parameter_names(instance_method(:invoke)).join(' ')
+        $stdout.puts "Usage: evoke #{name.underscore} #{params}"
+        $stdout.puts "\n#{syntax}"
+      end
+
+      # A short, one line description of the task.
+      #
+      # This message will be printed to the console when evoke is called without
+      # any arguments.
       #
       # @note All descriptions end with a period. One will be added if missing.
       #
@@ -22,6 +35,24 @@ module Evoke
         @desc = value
       end
 
+      # Describes the syntax of the task.
+      #
+      # The syntax is displayed to the user when they call `evoke help` for this
+      # task. This can be a detailed, multi-line description of how to use the
+      # task. By default the comment before the task's class will be used.
+      #
+      # @param [String] value The details on how to use the task.
+      # @return [String] The syntax - this method is both a getter and setter.
+      def syntax(value=nil)
+        if value.nil?
+          @syntax ||= class_comment
+        else
+          @syntax = value unless value.nil?
+        end
+
+        @syntax
+      end
+
       # Ensures that the task's #invoke method has the same amount of arguments
       # as the user supplied on the command-line. If not, an error message is
       # printed to STDERR and Evoke is terminated with an exit-status of 1.

data/lib/evoke/version.rb

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

data/lib/evoke.rb

@@ -1,8 +1,9 @@
-require 'evoke/version'
-require 'evoke/task'
-
 module Evoke
+  require 'evoke/version'
   require 'evoke/inflections'
+  require 'evoke/comment'
+  require 'evoke/parameters'
+  require 'evoke/task'
 
   class << self
     # Gets all the classes that descend from Evoke::Task.
@@ -83,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(*args) }
+      Array(@before_hooks).each {|hook| hook.call(task, *args) }
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: evoke
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Travis Haynes
@@ -61,6 +61,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rubocop.yml
 - .travis.yml
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -73,9 +74,11 @@ files:
 - exe/evoke
 - lib/evoke.rb
 - lib/evoke/cli.rb
+- lib/evoke/comment.rb
 - lib/evoke/inflections.rb
 - lib/evoke/inflections/camelize.rb
 - lib/evoke/inflections/underscore.rb
+- lib/evoke/parameters.rb
 - lib/evoke/task.rb
 - lib/evoke/version.rb
 homepage: 
@@ -101,5 +104,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: A build tool for Ruby.
+summary: A low-profile, zero-dependency command-line task tool for Ruby.
 test_files: []