class Tabular::Habit

Overview

A class that manages the formation of a set of [Tablets][Tabular::Tablets] within the block of [Tabular.form][Tabular.form].

Defined in:

tabular/habit.cr

Instance Method Summary

Instance Method Detail

def argument(choices : Array(String), help : String = "", directives : Directable | Nil = nil) #

Create a [Argument][Tabular::Kind::Argument]-flavoured [Tablet][Tabular::Tablet].

  • choices: A set of possible values for the argument. If empty?, any value is accepted.
  • help: See [Tablet#help][Tabular::Tablet#help].
  • directives: See [Directive][Tabular::Directive].

[View source]
def argument(*choice, help = "", directives : Directable | Nil = nil) #

Create a [Argument][Tabular::Kind::Argument]-flavoured [Tablet][Tabular::Tablet].

  • choice: Any number of possible values for the argument. If empty?, any value is accepted.
  • help: See [Tablet#help][Tabular::Tablet#help].
  • directives: See [Directive][Tabular::Directive].

[View source]
def command(name : String, aliases : Array(String) = [] of String, help = "", directives : Directable | Nil = nil) #

Create a [Command][Tabular::Kind::Command]-flavoured [Tablet][Tabular::Tablet].


[View source]
def command(name : String, *aliases, help = "", directives : Tabular::Directable | Nil = nil) #

Create a [Command][Tabular::Kind::Command]-flavoured [Tablet][Tabular::Tablet].


[View source]
def command(name : String, aliases : Array(String) = [] of String, help = "", directives : Directable | Nil = nil, &) #

Create a [Command][Tabular::Kind::Command]-flavoured [Tablet][Tabular::Tablet] along with its nested formation:

Tabular.form do
  command "cmd1", help: "command with dispatched completions"

  command "cmd2", help: "command with inline completions" do
    option "--file", "-f" { argument }
    option "--debug"
    command "sub1"
    command "arg2_choice1", "arg2_choice2"
  end

  # will never trigger on `cmd2`
  dispatch do |command|
    Command1.complete if command.name == "cmd1"
  end
end

[View source]
def command(name : String, *aliases, help = "", directives : Tabular::Directable | Nil = nil, &) #

Create a [Command][Tabular::Kind::Command]-flavoured [Tablet][Tabular::Tablet] along with its nested formation:

Tabular.form do
  command "cmd1", help: "command with dispatched completions"

  command "cmd2", help: "command with inline completions" do
    option "--file", "-f" { argument }
    option "--debug"
    command "sub1"
    command "arg2_choice1", "arg2_choice2"
  end

  # will never trigger on `cmd2`
  dispatch do |command|
    Command1.complete if command.name == "cmd1"
  end
end

[View source]
def delimiters(value : String) #

Specify the global string of characters that may delimit an [Option][Tabular::Kind::Option]-flavour [Tablet][Tabular::Tablet].

Tabular.form do
  # Allows for something like `--option=`
  delimiters "="
  # Allows for something like `-option:`
  delimiters ":"
  # Allows for all of the above
  delimiters ":="
end

[View source]
def delimiters : String #

Return the global string of characters that may delimit an [Option][Tabular::Kind::Option]-flavour [Tablet][Tabular::Tablet].


[View source]
def directives(kind : Kind, value : Directable) #

Sepcify the global [Directive][Tabular::Directive] for all [Tablets][Tabular::Tablets] of kind.


[View source]
def directives(kind : Kind) : Directive #

Return the global [Directive][Tabular::Directive] for all [Tablets][Tabular::Tablets] of kind.


[View source]
def dispatch(&block : Tablet -> Bool) #

Yield control back to the CLI with block when a [Command][Tabular::Kind::Command] is matched:

if Tabular.prompt?
  Tabular.form do
    command "cmd1"
    command "cmd2"

    dispatch do |command|
      # bespoke handling
    end
  end
end

[View source]
def installer(name = "completion", help = "install [TAB] completions") #

Create a [Tablet][Tabular::Tablet] for the [Command][Tabular::Kind::Command] that installs completions on your users' shell.

if Tabular.prompt?
  Tabular.form do
    command "cmd1"
    command "cmd2"

    # will complete `setup-tab` and possible params
    installer "setup-tab"

    dispatch do |command|
      # handle `cmd1` & `cmd2`
    end
  end
end

[View source]
def option(name : String, *aliases, help = "", directives : Directable | Nil = nil, delimiters = Tabular.delimiters, repeatable = false) #

Create a [Option][Tabular::Kind::Option]-flavoured [Tablet][Tabular::Tablet].


[View source]
def option(name : String, *aliases, help = "", delimiters = Tabular.delimiters, repeatable = false, &) #

Create a [Option][Tabular::Kind::Option]-flavoured [Tablet][Tabular::Tablet] with expected [Argument][Tabular::Kind::Argument]-flavoured [Tablet]Tabular::Tablet:

option "--opt" do
  argument "arg1_choice1", "arg1_choice2", "arg1_choice3"
  argument "arg2_choice1", "arg2_choice2"
end

[View source]
def relay(words : Array(String) = @words) #

Create a [Command][Tabular::Kind::Command] that yield completions for words back to the shell:

if Tabular.prompt?
  Tabular.form do
    relay
  end
end

Completions from the point of this [Tablet][Tabular::Tablet] are generated as if the command-line started with the remaining [#words][Tabular::Habit#words]. This is useful for sudo-like commands that expect a command prompt to run in a specific context.


[View source]
def size : Int32 #

Returns the number of [Tablets][Tabular::Tablets] in the [Habit][Tabular::Habit].


[View source]
def tablet(kind : Kind, *args, **kwargs) #

Create a [Tablet][Tabular::Tablet].


[View source]
private def words : Array(String) #

The current set of command-lne arguments in the completion process.


[View source]