console_runner 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 46251b514ee3ff2c6fe6d1805b58bb7bc8740ebb
-  data.tar.gz: 7781c2c0188af33e49ab7bec3e99be229bb756ac
+  metadata.gz: 1c16db9e220aea79fb56dcfedbefaf35822d5759
+  data.tar.gz: 04a996f93da398cc7b3cf78054d4cbc0410d2572
 SHA512:
-  metadata.gz: 1ca1cf2617736897556652cfa6de3c7a894349359d3ab2472f759c7a8def9a0b617e77138e48dbab8e9c77c805451b52ff4aef38fca6ffb8187b9ddc2d62c4cc
-  data.tar.gz: 64c9e1747574c79f5ee1b863a7e26ba4a2dd9f98ecd10d8f4cfbab133b02350c34354ef73b5bf451487ea69c7b0dbb875cd597a857d7dae68bb5b68a7705e1f8
+  metadata.gz: b250ca7da42c8f2c2940577d0706a8ebc800af3463aef7f94b75c2a6aa626e809262b2e37b5c12dce3f515855bfe39ef0bd0fcf1a67683b8338f6c51458b9f93
+  data.tar.gz: 9e0c76daa906eb6cb2224caa38d86ad0e9df4adf374c79979a3ed15186625326161f5e7bb596049c3c9fa6d101ee26987befba7298460ee3830c5b7f1bca172a

data/README.md

@@ -5,9 +5,47 @@
 [![Code Climate][CC img]][Code Climate]
 [![Coverage Status][CS img]][Coverage Status]
 
-This gem provides you an ability to run any Ruby method from command-line (no any code modifications required!!!).
+This gem provides you an ability to run any Ruby method from command-line. No special code modifications required!.
+`console_runner` is a smart mix of [YARD](http://yardoc.org/) and [Trollop](http://manageiq.github.io/trollop/) gems. 
+> 1. it parses [YARD](http://yardoc.org/) annotations of classes and methods to 'understand' your code
+> 2. it generates friendly unix-like help menu for your tool (using [Trollop](http://manageiq.github.io/trollop/) gem)
+> 3. it parses command-line input and run your Ruby code in a proper way 
+
+Just 4 simple steps to make your code runnable from terminal:
+1. Just add `@runnable` tag in 
+
 One thing you need to do is to add an [YARD](http://yardoc.org/) tag annotation `@runnable`.
 
+## Usage
+`console_runner` extends [YARD](http://yardoc.org/) with a new tag: `@runnable`. You need to set this tag in a Class and Method annotation. After that it will be possible to call this method from command-line.
+Usage instructions are as simple as one, two, three:
+1. Add `@runnable` tag
+2. Now you can run your tool from terminal by `c_run /path/to/class.rb_file` command
+3. PROFIT! (: 
+
+### Example
+1. Install `console_runner` gem
+2. Put some code to `/home/user/project/my_class.rb`
+```ruby
+# @runnable
+class MyClass
+
+    # @runnable
+    def say_hello
+      puts 'Hello!'
+    end
+    
+end
+```
+3. Run terminal command to run `say_hello` method
+```bash
+c_run /home/user/project/my_class.rb say_hello
+
+-> Hello!
+```
+
+Read FAQ for more examples.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -24,84 +62,40 @@ Or install it yourself as:
 
     $ gem install console_runner
 
-## Usage
-Usage is simple. First of all you need to add `gem 'console_runner'` in your `Gemfile`.
-Then you need to specify `@runnable` tag in your class and method annotations. For example,
- 
+## FAQ
+##### **Can I add documentation for my tool and customize help page content?**
+Yes. Any text placed after `@runnable` tag will be displayed on the help page. You can add any additional information about how to use your tool there.
+> **Tip**: You can use multi-line text as well
+
+**Example:**
 ```ruby
-# This is basic Ruby class with YARD annotation.
-# Nothing special here except @runnable tag. This is a `console_runner` tag that
-# shows that this class can be runnable via bash command line.
-#
-# You can mark any method (class method or instance method) with @runnable tag to show you want the method to be executable.
-# We name class method as *class action* and instance method as *instance action* or just *action*.
-# Instance action requires #initialize method to be executed first. `console_runner` tool invokes #initialize
-# method automatically.
-#
-# @author Yuri Karpovich
-#
-# @runnable This is your "smart" assistant tool.
-#   NOTE: This message will be shown in your tool in --help menu.
-#
-# @since 0.1.0
-class SimpleSiri
-
-  def initialize
-    @name = 'Siri'
-    @age = Random.rand 100
-  end
-
-  # Say something
-  #
-  # @runnable
-  # @return [String]
-  # @param [String] what_to_say ask name or age of Siri
-  def say(what_to_say)
-    case what_to_say.downcase
-      when 'name'
-        puts 'My name is ' + @name
-      when 'age'
-        puts "I'm #{@age} years old"
-      else
-        puts "I don't know".green
-    end
-  end
+# @runnable This tool can talk to you. Run it when you are lonely.
+class MyClass
 
+    def initialize
+      @hello_msg = 'Hello!' 
+      @bye_msg = 'Good Bye!' 
+    end
+    
+    # @runnable Say 'Hello' to you.
+    def say_hello
+      puts @hello_msg
+    end
+    
+    # @runnable Say 'Good Bye' to you.
+    def say_bye
+      puts @bye_msg
+    end
+    
 end
 ```
 
-Then you can run the tool in your console:
-```bash
-c_run ruby_class.rb say --help
-
-This is your "smart" assistant tool.
-NOTE: This message will be shown in your tool in --help menu.
-  -h, --help               Show this message
-  -w, --what-to-say=<s>    (Ruby class: String) ask name or age of Siri
-```
-
 ```bash
- c_run ruby_class.rb say -w age
- 
-=======================================================
-Global options:
-     help = false
-INIT: initialize
-INIT options:
-
-Subcommand: say
-Subcommand options:
-     what_to_say = age
-=======================================================
-Start Time: 2017-04-11 21:39:40 +0300
-I'm 78 years old
-Finish Time: 2017-04-11 21:39:40 +0300 (Duration: 0.0 minutes)
-
+TODO example
 ```
 
 ## ToDo
 - fix help menu for action: action help text should be displayed, list of available actions should be displayed
-- write good readme
 
 ## Development
 

data/lib/console_runner.rb

@@ -1,77 +1,62 @@
 require 'file_parser'
-require 'cmd_parser'
+require 'trollop_configurator'
 require 'runner'
 require 'console_runner/version'
 
-
+# console_runner logic is here
 module ConsoleRunner
   file_from_arg = ARGV.shift
   raise ConsoleRunnerError, 'Specify file to be executed' unless file_from_arg
   file_path   = File.realpath file_from_arg
   file_parser = FileParser.new(file_path)
-
-
-  runnable_classes = file_parser.list_classes(:runnable)
-  if runnable_classes.count != 1
-    raise ConsoleRunnerError, "One runnable Class should be specified in file.
-Runnable class should be marked with @#{FileParser::RUNNABLE_TAG} tag"
-  end
-
-  clazz             = runnable_classes.first
-  all_methods       = file_parser.list_methods(:all, clazz)
-  runnable_methods  = file_parser.list_methods(:runnable, clazz)
-  initialize_method = all_methods.find { |m| m.name == :initialize }
-  run_method        = all_methods.find { |m| m.name == :run }
-
-
-  cmd            = ARGV[0]
-  action_methods = runnable_methods.select { |m| m.name.to_s == cmd }
-  if action_methods.count > 1
+  cmd         = ARGV[0]
+  actions     = file_parser.runnable_methods.select { |m| m.name.to_s == cmd }
+  if actions.count > 1
     raise(
       ConsoleRunnerError,
-      "Class and Instance methods have the same name (#{cmd}). Action name should be unique"
+      "Class and Instance methods have the same name (#{cmd}). Actions names should be unique"
     )
   end
-  action_method = action_methods.first
-  action_method ||= run_method
-  cmd_parser    = CmdParser.new(runnable_methods, initialize_method)
-  raise ConsoleRunnerError, "Cannot run! You haven't specify any method to run." unless action_method
-  cmd_parser.parse_method action_method
+  action      = actions.first
+  action      ||= file_parser.run_method
+  trol_config = TrollopConfigurator.new(file_parser)
+  raise ConsoleRunnerError, "Cannot run! You haven't specify any method to run." unless action
+  trol_config.parse_method action
 
 
   puts '======================================================='
   puts 'Global options:'
-  puts cmd_parser.global_opts.map { |k, v| "     #{k} = #{v}" }.join("\n")
-  if initialize_method
-    puts "INIT: #{initialize_method.name}"
+  puts trol_config.global_opts.map { |k, v| "     #{k} = #{v}" }.join("\n")
+  if file_parser.initialize_method
+    puts "INIT: #{file_parser.initialize_method.name}"
     puts 'INIT options:'
-    puts cmd_parser.init_method.cmd_opts.map { |k, v| "     #{k} = #{v}" }.join("\n")
+    puts trol_config.init_method.cmd_opts.map { |k, v| "     #{k} = #{v}" }.join("\n")
   end
-  puts "Subcommand: #{action_method.name}"
+  puts "Subcommand: #{action.name}"
   puts 'Subcommand options:'
-  puts cmd_parser.method.cmd_opts.map { |k, v| "     #{k} = #{v}" }.join("\n")
+  puts trol_config.method.cmd_opts.map { |k, v| "     #{k} = #{v}" }.join("\n")
   puts "Remaining arguments: #{ARGV.inspect}" if ARGV != []
   puts '======================================================='
 
 
   Runner.run {
     require file_path
-    class_full_name = clazz.title
+    class_full_name = file_parser.clazz.title
     raise ConsoleRunnerError, "#{class_full_name} is not defined" unless Module.const_defined?(class_full_name)
     klass_obj     = Module.const_get(class_full_name)
-    method_type   = action_method.scope
-    method_params = cmd_parser.method.params_array
+    method_type   = action.scope
+    method_params = trol_config.method.params_array
 
     case method_type
       when :class
-        klass_obj.send(action_method.name, *method_params)
+        klass_obj.send(action.name, *method_params)
       when :instance
-        init_method = cmd_parser.init_method
+        init_method = trol_config.init_method
         init_params = []
         init_params = init_method.params_array if init_method
         # TODO catch errors
         obj         = klass_obj.new(*init_params)
-        obj.send(action_method.name, *method_params)
+        obj.send(action.name, *method_params)
       else
         raise ConsoleRunnerError, "Unknown method type: #{method_type}"
     end

data/lib/console_runner/version.rb

@@ -1,3 +1,3 @@
 module ConsoleRunner
-  VERSION = '0.1.8'
+  VERSION = '0.1.9'
 end

data/lib/file_parser.rb

@@ -5,8 +5,10 @@ require 'console_runner_error'
 class FileParser
   RUNNABLE_TAG = :runnable
 
-  # array of #YARD::CodeObjects
-  attr_reader :all_objects
+  attr_reader :clazz,
+              :runnable_methods,
+              :initialize_method,
+              :run_method
 
   # Parse file with #YARD::CLI::Stats
   #
@@ -15,9 +17,18 @@ class FileParser
     raise ConsoleRunnerError "Cannot find file #{file_path}" unless File.exist?(file_path)
     code = YARD::CLI::Stats.new
     code.run(file_path)
-    @all_objects = code.all_objects
+    @all_objects     = code.all_objects
+    runnable_classes = list_classes(:runnable)
+    raise ConsoleRunnerError, 'At least one runnable Class should be specified in file' if runnable_classes.count != 1
+    @clazz             = runnable_classes.first
+    all_methods        = list_methods(:all, clazz)
+    @runnable_methods  = list_methods(:runnable, clazz)
+    @initialize_method = all_methods.find { |m| m.name == :initialize }
+    @run_method        = all_methods.find { |m| m.name == :run }
   end
 
+  private
+
   # List of methods
   # @param [Symbol] scope :all - list all methods, :runnable - list only runnable methods
   # @param [YARD::CodeObjects::ClassObject, nil] clazz list methods of specified class only
@@ -93,9 +104,11 @@ YARD::Tags::Library.define_tag 'Console Tool Description', FileParser::RUNNABLE_
 module YARD
   module CLI
     class Stats < Yardoc
-      def print_statistics; end
+      def print_statistics;
+      end
 
-      def print_undocumented_objects; end
+      def print_undocumented_objects;
+      end
     end
   end
 end

data/lib/method_parser.rb

@@ -2,8 +2,8 @@
 class MethodParser
   attr_reader :method,
               :name,
-              :param_tags,    # All method parameters tags
-              :option_tags    # Only options tags
+              :param_tags, # All method parameters tags
+              :option_tags # Only options tags
 
   attr_accessor :cmd_opts
 
@@ -15,6 +15,14 @@ class MethodParser
     @param_tags  = FileParser.select_param_tags @method
     @option_tags = FileParser.select_option_tags @method
     @cmd_opts    = nil
+    same_params = param_tags_names & option_tags_names
+    if same_params.count > 0
+      raise(
+        ConsoleRunnerError,
+        "You have the same name for @param and @option attribute(s): #{same_params.join(', ')}.
+Use different names to `console_runner` be able to run #{@name} method."
+      )
+    end
   end
 
   # Prepare

data/lib/{cmd_parser.rb → trollop_configurator.rb}

@@ -2,7 +2,7 @@ require 'trollop'
 require 'method_parser'
 
 # Parses command line and configure #Trollop
-class CmdParser
+class TrollopConfigurator
   attr_reader :global_opts, :method, :init_method
   TYPES_MAPPINGS = {
     'String'         => :string,
@@ -16,8 +16,12 @@ class CmdParser
     'Array(Float)'   => :floats,
     'Array(Boolean)' => :booleans
   }.freeze
-  # Should be executed before ARGV.shift
-  def initialize(runnable_methods, init_method= nil)
+
+  # Generate tool help menu.
+  # IMPORTANT! Should be executed before ARGV.shift
+  def initialize(file_parser)
+    runnable_methods = file_parser.runnable_methods
+    init_method = file_parser.initialize_method
     clazz        = runnable_methods.first.parent
     sub_commands = runnable_methods.map { |m| m.name.to_s }
     @parser      = Trollop::Parser.new
@@ -26,16 +30,6 @@ class CmdParser
 
     if init_method
       @init_method = MethodParser.new init_method
-      same_params  = @init_method.param_tags_names & @init_method.option_tags_names
-      if same_params.count > 0
-        raise(
-          ConsoleRunnerError,
-          "You have the same name for @param and @option attribute(s): #{same_params.join(', ')}.
-Use different names to `console_runner` be able to run #{@init_method.name} method."
-        )
-      end
-
-
       @init_method.param_tags.each do |tag|
         tag_name = tag.name
         tag_text = tag.text
@@ -47,13 +41,13 @@ Use different names to `console_runner` be able to run #{@init_method.name} meth
               option_name = option.pair.name.delete(':')
               option_text = option.pair.text
               option_type = option.pair.type
-              @parser.opt(option_name.to_sym, "(Ruby class: #{option_type}) " + option_text.to_s, type: CmdParser.parse_type(option_type))
+              @parser.opt(option_name.to_sym, "(Ruby class: #{option_type}) " + option_text.to_s, type: TrollopConfigurator.parse_type(option_type))
             end
           else
-            @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: CmdParser.parse_type(tag_type))
+            @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: TrollopConfigurator.parse_type(tag_type))
           end
         else
-          @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: CmdParser.parse_type(tag_type))
+          @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: TrollopConfigurator.parse_type(tag_type))
         end
       end
     end
@@ -76,15 +70,7 @@ Use different names to `console_runner` be able to run #{@init_method.name} meth
   # Parse method and configure #Trollop
   def parse_method(method)
     ARGV.shift
-    @method     = MethodParser.new method
-    same_params = @method.param_tags_names & @method.option_tags_names
-    if same_params.count > 0
-      raise(
-        ConsoleRunnerError,
-        "You have the same name for @param and @option attribute(s): #{same_params.join(', ')}.
-Use different names to `console_runner` be able to run #{@method.name} method."
-      )
-    end
+    @method            = MethodParser.new method
     method_params_tags = @method.param_tags
 
     method_params_tags.each do |tag|
@@ -98,13 +84,13 @@ Use different names to `console_runner` be able to run #{@method.name} method."
             option_name = option.pair.name.delete(':')
             option_text = option.pair.text
             option_type = option.pair.type
-            @parser.opt(option_name.to_sym, "(Ruby class: #{option_type}) " + option_text.to_s, type: CmdParser.parse_type(option_type))
+            @parser.opt(option_name.to_sym, "(Ruby class: #{option_type}) " + option_text.to_s, type: TrollopConfigurator.parse_type(option_type))
           end
         else
-          @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: CmdParser.parse_type(tag_type))
+          @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: TrollopConfigurator.parse_type(tag_type))
         end
       else
-        @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: CmdParser.parse_type(tag_type))
+        @parser.opt(tag_name.to_sym, "(Ruby class: #{tag_type}) " + tag_text.to_s, type: TrollopConfigurator.parse_type(tag_type))
       end
     end
     cmd_opts         = Trollop::with_standard_exception_handling @parser do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console_runner
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Yury Karpovich
@@ -157,13 +157,13 @@ files:
 - bin/setup
 - console_runner.gemspec
 - exe/c_run
-- lib/cmd_parser.rb
 - lib/console_runner.rb
 - lib/console_runner/version.rb
 - lib/console_runner_error.rb
 - lib/file_parser.rb
 - lib/method_parser.rb
 - lib/runner.rb
+- lib/trollop_configurator.rb
 homepage: https://github.com/yuri-karpovich/console_runner
 licenses:
 - MIT