An expressive DSL for build interactive command-line applications
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin I've made a ton of changes to get to a point where Shelldon is Ruboco… Aug 23, 2017
lib Don't remove support for passing a block to the constructor Dec 22, 2017
spec
test_shell I've made a ton of changes to get to a point where Shelldon is Ruboco… Aug 23, 2017
.gitignore rm script Jan 6, 2016
.rbenv-gemsets I don't even remember what's in these changes but I bet they fix some… Aug 31, 2016
.rspec I've made a ton of changes to get to a point where Shelldon is Ruboco… Aug 23, 2017
.rubocop.yml I've made a ton of changes to get to a point where Shelldon is Ruboco… Aug 23, 2017
Gemfile
LICENSE.txt Initial commit Dec 12, 2015
README.md Small fixes Apr 14, 2016
Rakefile I've made a ton of changes to get to a point where Shelldon is Ruboco… Aug 23, 2017
build_and_install.sh
shelldon.gemspec

README.md

Shelldon

Gem Version

Shelldon is an expressive DSL for building interactive terminal applications, or REPLs (Read-Evaluate-Print-Loops).

There are some good gems out there for building command-line executables, but I couldn't find anything that built a REPL in the way that I wanted it -- and I build a lot of REPLs.

Installation

# Gemfile
gem 'shelldon'

$ bundle install

Or just gem install shelldon -- You know the drill.

Usage

Shelldon is made to be dead-simple to use. Here's a breakdown of the usage!

Start defining a shell like this:

Shelldon.shell :example do
end
Shelldon.run(:example)

Commands

Define a command with a command block:

Shelldon.shell :example do
  command :test do
    aliased 'test_command'
    help "Run a test command to show some text. Optionally, add an arg."
    usage "test"
    examples ['test', 'test blah']
    action { |arg = ''| puts "This is a test! #{arg}" }
  end
end
Shelldon.run(:example)

Sub-Commands

You can nest commands into other commands with the subcommand block. This is great for organizing functionality. You can retain the functionality of your higher-level commands, or if you want a higher-level command to act as a placeholder you can just tell Shelldon so!

For instance, you could run the command test foobar like this:

  command :test do
    placeholder

    subcommand :foobar do
      help "Print out 'Foobar!'"
      action {puts "Foobar!"}
    end
  end

Default Command ("No Such Command Found")

You can use the command_missing block to define behaviour when a command isn't explicitly registered. This can be anything from writing "No Such Command" to doing a similarity-search to passing the command to some other resource.

command_missing do
  action { |cmd| puts "No such command \"#{cmd}\"" }
end

Configuration

What good is a shell without config? The config block will allow you to set up parameters, validate and adjust input, set a configuration yml file, and interact with command-line opts.

Here's an example that implements the bash 'set -o vi/emacs' functionality in the shell

config do
  config_file '.shelldon_config'

  param :'-o' do
    type :string
    default 'emacs'
    # adjust runs before validate, and can 'fix' your input. In this case, allow 'vim' for 'vi'
    adjust { |s| s.to_s.downcase.strip.gsub('vim', 'vi') }
    # validate looks for a 'true' result, but in this case we're also using it to take action
    validate do |s|
      return false unless s == 'emacs' || s == 'vi'
      if s == 'emacs'
        Readline.emacs_editing_mode; true
      else
        Readline.vi_editing_mode; true
      end
    end
  end
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wwboynton/shelldon.

License

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

Let me know if you find a cool use for Shelldon!