Module Drydock
In: lib/drydock/screen.rb
lib/drydock.rb

Drydock is a DSL for command-line apps. See bin/example for usage examples.

Methods

Classes and Modules

Module Drydock::Screen
Class Drydock::ArgError
Class Drydock::Command
Class Drydock::InvalidArgument
Class Drydock::MissingArgument
Class Drydock::NoCommandsDefined
Class Drydock::OptError
Class Drydock::UnknownCommand

Constants

VERSION = 0.6

Public Instance methods

Provide a description for a command

Define a command-specific action.

This is functionally very similar to option, but with an exciting and buoyant twist: Drydock keeps track of actions for each command (in addition to treating it like an option). When an action is specified on the command line Drydock looks for command_action or action_command methods in the command class.

    action :E, :eat, "Eat something"
    command :oysters => Fresh::Oysters

    # Drydock will look for Fresh::Oysters#eat_oysters and Fresh::Oysters#oysters_eat.

Define a block to be called after the command. This is useful for stopping, closing, etc… the stuff in the before block.

Used to create an alias to a defined command. Here‘s an example:

   command :task do; ...; end
   alias_command :pointer, :task

Either name can be used on the command-line:

   $ yourscript task [options]
   $ yourscript pointer [options]

Inside of the command definition, you have access to the command name that was used via obj.alias.

Provide names for CLI arguments, in the order they appear.

    $ yourscript sample malpeque zinqy
    argv :name, :flavour
    command :sample do |obj|
      obj.argv.name        # => malpeque
      obj.argv.flavour     # => zinqy
    end

Define a block to be called before the command. This is useful for opening database connections, etc…

Canonizes a string (cmd) to the symbol for command names ’-’ is replaced with ‘_‘

Capture STDOUT or STDERR to prevent it from being printed.

   capture(:stdout) do
     ...
   end

Define a command.

    command :task do
      ...
    end

A custom command class can be specified using Hash syntax. The class must inherit from Drydock::Command (class CustomeClass < Drydock::Command)

    command :task => CustomCommand do
      ...
    end

Returns true if a command with the name cmd has been defined.

Identical to alias_command with reversed arguments. For whatever reason I forget the order so Drydock supports both. Tip: the argument order matches the method name.

An array of the currently defined commands names

A hash of the currently defined Drydock::Command objects

Enable or disable debug output.

    debug :on
    debug :off

Calling without :on or :off will toggle the value.

Returns true if debug output is enabled.

Returns a string version of cmd, decanonized. Lowercase, ‘_’ is replaced with ’-’

Define a default command. You can specify a command name that has been or will be defined in your script:

    default :task

Or you can supply a block which will be used as the default command:

    default do |obj|            # This command will be named "default"
      # ...
    end

    default :hullinspector do   # This one will be named "hullinspector"
      # ...
    end

If with_args is specified, the default command will receive all unknown values as arguments. This is necessary to define explicitly because drydock parses arguments expecting a command name. If the default command accepts arguments and with_args is not specified, drydock will raise an unknown command exception for the first argument.

Deprecated. Use about.

global(*args, &b)

Alias for global_option

Define a global option. See option for more info.

Define the default global usage banner. This is displayed with "script -h".

Return true if a command has been executed.

Tell the Drydock parser to ignore something. Drydock will currently only listen to you if you tell it to "ignore :options", otherwise it will ignore you!

what the thing to ignore. When it equals :options Drydock will not parse the command-specific arguments. It will pass the arguments directly to the Command object. This is useful when you want to parse the arguments in some a way that‘s too crazy, dangerous for Drydock to handle automatically.

Define a command-specific option.

args is passed directly to OptionParser.on so it can contain anything that‘s valid to that method. If a class is included, it will tell OptionParser to expect a value otherwise it assumes a boolean value. Some examples:

    option :h, :help, "Displays this message"
    option '-l x,y,z', '--lang=x,y,z', Array, "Requested languages"

    You can also supply a block to fiddle with the values. The final
    value becomes the option's value:

    option :m, :max, Integer, "Maximum threshold" do |v|
      v = 100 if v > 100
      v
    end

All calls to option must come before the command they‘re associated to. Example:

    option :t, :tasty,          "A boolean switch"
    option     :reason, String, "Requires a parameter"
    command :task do |obj|;
      obj.options.tasty       # => true
      obj.options.reason      # => I made the sandwich!
    end

When calling your script with a specific command-line option, the value is available via obj.longname inside the command block.

The project name. This is currently only used when printing list of commands (see: Drydock::Command#show_commands). It may be used elsewhere in the future.

Has the project been set?

Execute the given command. By default, Drydock automatically executes itself and provides handlers for known errors. You can override this functionality by calling +Drydock.run!+ yourself. Drydock will only call +run!+ once.

Disable automatic execution (enabled by default)

    Drydock.run = false

Returns true if automatic execution is enabled.

Define a block for processing STDIN before the command is called. The command block receives the return value of this block as obj.stdin:

    command :task do |obj|;
      obj.stdin   # => ...
    end

If a stdin block isn‘t defined, stdin above will be the STDIN IO handle.

The trawler catches any and all unknown commands that pass through Drydock. It‘s like the captain of aliases. cmd is the name of the command to direct unknowns to.

    trawler :command_name

Has the trawler been set?

Define a command-specific usage banner. This is displayed with "script command -h"

[Validate]