Class: CommandLion::Command

Inherits:
Base
  • Object
show all
Defined in:
lib/command_lion/command.rb

Overview

Every command or option for Command Lion is built on the Command class.

A Command is typically built using the DSL provided within a build method block:

⚙️ Build Block

cmd = CommandLion::Command.build do
  # ...
end

This is used under the hood within an Application’s DSL run or block:

⚙️ Application Build Block

app = CommandLion::App.build do
  command :example_index do
    # ...
  end
end

The DSL keywords are simple methods provided for any Command object and can be accessed or modified outside of the DSL building block itself to, for example, query if it exists.

🗣 DSL

Command Lion’s DSL is meant to be as flexible as possible without being too compelx.

⚡️ Example

cmd = CommandLion::Command.build do
  index :example
  flags do
    short "-e"
    long  "--example"
  end
  type :strings
  default ["Jim", "Pam", "Dwight", "Michael"]
  before do
    unless arguments.count > 2
      abort "Must provide more than two arguments!"
    end
  end
  action do
    arguments.each do |argument|
      puts "Hello #{argument}!"
    end
  end
  after do
    exit 0
  end
end

Keywords

🔑 description

To provide further context for your command’s existence, it’s fairly nice to have a description.

Example

cmd = CommandLion::Command.build do
  description "Example"
end

cmd.description?
# => true

cmd.description = "Changed"
# => "Changed"

cmd.description
# => Changed
🔑 type

A command may require a specific argument from the command-line. The type of argument(s) that the command utilizies can be specified with this keyword.

Example

cmd = CommandLion::Command.build do
  type :string
end

cmd.type?
# => true

cmd.type = :strings
# => :strings

cmd.type
# => :strings
🔑 default

To specify a command’s default arguments, the default keyword can be used.

Example

cmd = CommandLion::Command.build do
  default "example"
end

cmd.default?
# => true

cmd.default = "EXAMPLE"
# => "EXAMPLE"

cmd.default
# => "EXAMPLE"

cmd.argument
# => "EXAMPLE"
🔑 delimiter

In the case of multiple command-line arguments, a custom delimter can be used to help split up the arguments. Command Lion uses the space betwen arguments as the default delimter.

Example

cmd = CommandLion::Command.build do
  delimter ","
end

cmd.delimter?
# => true

cmd.delimter = ":"
# => ":"

cmd.delimter
# => :
🔑 flag

If you’d like for one specfic flag to be used for the command, then this keyword is for you!

Example

cmd = CommandLion::Command.build do
  flag "example"
end

cmd.flag?
# => true

cmd.flag = "EXAMPLE"
# => "EXAMPLE"

cmd.flag 
# => "EXAMPLE"
🔑 flags

The flags keywords can be used two specify the short and long flags option for a command.

Example

cmd = CommandLion::Command.build do
  flags do
    short "-e"
    long  "--example
  end
end

cmd.flags?
# => true

cmd.flags.short? 
# => true

cmd.flags.long? 
# => true

cmd.flags.short = "-E" 
# => "-E"

cmd.flags.long = "--EXAMPLE" 
# => "--EXAMPLE"

cmd.flags.long
# => "--EXAMPLE"

cmd.flags.short
# => "-E"
🔑 threaded

To have your command spawn a thread and have the action block for your command run in its own background thread.

Example

cmd = CommandLion::Command.build do
  description "Example"
end

cmd.description?
# => true

cmd.description = "Changed"
# => "Changed"

cmd.description
# => Changed
🔑 action

What do you want a command to do when it is used? The action keyword can be used to capture the block you’d like to run when the command is used.

Example

cmd = CommandLion::Command.build do
  action do
    puts "Hello World!"
  end
end

cmd.action?
# => true

cmd.action
# => #<Proc:...>

cmd.action.call
# => Hello World! .. to STDOUT
🔑 before

Before the action block is called, you can specify anouther block to be used beforehand which can be used to help setup or do some custom error checking.

Example

cmd = CommandLion::Command.build do
  before do
    abort "Not on Mondays!" Time.now.monday?
  end
  action do
    puts "Hello World!"
  end
end

cmd.before?
# => true

cmd.before
# => #<Proc:...>

cmd.before.call
# aborts application if it's Monday
🔑 after

After the action block has been called and completed, anouther optional block can be used within the block given in the after keyword. This can be used for all sorts of nifty things: from stopping the application from moving on, to logging, to whatever else.

Example

cmd = CommandLion::Command.build do
  action do
    puts "Hello World!"
  end
  after do
    exit 0 
  end
end

cmd.after?
# => true

cmd.after
# => #<Proc:...>

cmd.after.call
# exits application with successful status code
🔑 index

A command’s index should be unique. It is used to used to accesses the command amongst other commands when used within an application. However, this keyword usually isn’t used unless being utilized when using Command Lion’s plugin system.

Example

cmd = CommandLion::Command.build do
  index :example
end

cmd.index?
# => :example

cmd.index
# => :example
🔑 option

a command may have mutiple sub commands or options associated with it. these effectively work exactly like any other command, but are just started as a leaf under the paren’t command’s options.

Example

cmd = CommandLion::Command.build do
  # ...
  option :example do
    action do
      puts "hello world!"
    end
  end
end

cmd.options?
# => true

cmd.options[:example]
# => #<proc:...>

cmd.after.call
# exits the application with successful status code

Direct Known Subclasses

Option

Method Summary

Methods inherited from Base

build, key_value, simple_attr, simple_attrs