ConsoleRunner [CLI for any *.rb]

Gem Version Build Status Code Climate Coverage Status

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 and Optimist gems. It's an analog of Python Fire in Ruby language.

  1. it parses YARD annotations of classes and methods to 'understand' your code
  2. it generates friendly unix-like help menu for your tool (using Optimist 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 tag annotation @runnable.

Usage

console_runner extends YARD 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

    # @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:

gem 'console_runner'

And then execute:

$ bundle

Or install it yourself as:

$ gem install console_runner

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:
# @runnable This tool can talk to you. Run it when you are lonely.
#   Written in Ruby.  
class MyClass

    def initialize
      @hello_msg = 'Hello!' 
      @bye_msg = 'Good Bye!' 
    end

    # @runnable Say 'Hello' to you.
    # @param [String] name Your name
    def say_hello(name)
      puts @hello_msg + ', ' + name
    end

    # @runnable Say 'Good Bye' to you.
    def say_bye
      puts @bye_msg
    end

end

 ~> c_run /projects/example/my_class.rb  --help
Options:
  --debug    Run in debug mode.

This tool can talk to you. Run it when you are lonely.
Written in Ruby.

Available actions:
        - say_hello
                Say 'Hello' to you.
        - say_bye
                Say 'Good Bye' to you.

 ~> c_run /projects/example/my_class.rb  say_hello -h
Options:
  -d, --debug    Run in debug mode.
  -h, --help     Show this message
  --name=<s>     (Ruby class: String) Your name

Say 'Hello' to you.

Can I send parameters to my methods?

Yes, console_runner parses YARD annotation (@param and @option tags) and check the list of parameters for your method.

Restriction: You can use Hash parameters as well (for storing options). But you cannot use the same name for parameter and for option.

For example, def limit(number, options = {number: 5})... - number name is not allowed. You should use another parameter name.

Example:
# @runnable This tool can talk to you. Run it when you are lonely.
#   Written in Ruby.  
class MyClass

    def initialize
      @hello_msg = 'Hello' 
      @bye_msg = 'Good Bye' 
    end

    # @runnable Say 'Hello' to you.
    # @param [String] name Your name
    # @param [Hash] options options
    # @option options [Boolean] :second_meet Have you met before?
    # @option options [String] :prefix Your custom prefix
    def say_hello(name, options = {})
      second_meet = nil
      second_meet = 'Nice to see you again!' if options['second_meet']
      prefix = options['prefix']
      message = @hello_msg + ', '
      message += "#{prefix} " if prefix
      message += "#{name}. "
      message += second_meet if second_meet
      puts message
    end

end

~> c_run /projects/example/my_class.rb  say_hello -h 
Options:
  -d, --debug      Run in debug mode.
  -h, --help       Show this message
  --name=<s>       (Ruby class: String) Your name
  --second-meet    (Ruby class: Boolean) Have you met before?
  --prefix=<s>     (Ruby class: String) Your custom prefix

Say 'Hello' to you.

~> c_run /projects/example/my_class.rb  say_hello -n John --second-meet --prefix Mr. 
Hello, Mr. John. Nice to see you again!

Can I use optional parameters?

Yes. All parameters with @option YARD tag are optional.

--second-meet and --prefix parameters are optional in the following example:

# @runnable Say 'Hello' to you.
    # @param [String] name Your name
    # @param [Hash] options options
    # @option options [Boolean] :second_meet Have you met before?
    # @option options [String] :prefix Your custom prefix

Another approach is to use default values for parameters. Parameter --name in the following example is optional because it has the default value Chuck.

    # @runnable Say 'Hello' to you.
    # @param [String] name Your name
    # @param [Hash] options options
    # @option options [Boolean] :second_meet Have you met before?
    # @option options [String] :prefix Your custom prefix
    def say_hello(name = 'Chuck', options = {})
      second_meet = nil
      second_meet = 'Nice to see you again!' if options['second_meet']
      prefix = options['prefix']
      message = @hello_msg + ', '
      message += "#{prefix} " if prefix
      message += "#{name}. "
      message += second_meet if second_meet
      puts message
    end

-> c_run /projects/example/my_class.rb  say_hello  
Hello, Chuck.

Is it works only for class methods?

console_runner works with both methods - class and instance methods. It's clear how it works with class method - method is called without any preconditions. Instance method will be called in accordance with following logic:

  1. call :initialize method
  2. call specified action method

My require code doesn't work well. How can I fix it?

Use require_relative method instead.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yuri-karpovich/console_runner.

License

The gem is available as open source under the terms of the MIT License.