Sirocco

A collection of interactive command line prompts for Lua

Note: Sirocco is in active development.

Installing

Requirements:

Lua 5.1/JIT/5.2/5.3
luarocks >= 3.0 (Note: hererocks -rlatest will install 2.4, you need to specify it with -r3.0)

luarocks install sirocco

Quickstart

See example.lua for an exhaustive snippet of all sirocco's features.

Text prompt

Basic text prompt. Every prompt inherits from it so most of its options apply to them.

Prompt {
    -- The prompt
    prompt         = "A simple question\n❱ ",
    -- A placeholder that will dissappear once the user types something
    placeholder    = "A simple answer",
    -- Whether the answer is required or not
    required       = true,
    -- The default answer
    default        = "A default answer",
    -- When hitting `tab`, will try to autocomplete based on those values
    possibleValues = {
        "some",
        "possible",
        "values",
    },
    -- Must return whether the current text is valid + a message in case it's not
    validator      = function(text)
        return text:match("[a-zA-Z]*"), "Message when not valid"
    end,
    -- If returns false, input will not appear at all
    filter         = function(input)
        return input:match("[a-zA-Z]*")
    end
}:ask() -- Returns the answer

Password

Obfuscates the input.

Password {
    prompt = "Enter your secret (hidden answer)\n❱ ",
    -- When false *** are printed otherwise nothing
    hidden = false
}:ask() -- Returns the actual answer

Confirm

A simple yes/no prompt.

Confirm {
    prompt = "All finished?"
}:ask() -- Returns the answer

List

Will choose the appropriate list (check list or radio list).

List {
    prompt   = "Where are you from?",
    -- If true can select multiple choices (check list) otherwise one (radio list)
    multiple = false,
    -- List of choices
    items    = {
        {
            -- The actual value returned if selected
            value = "New York",
            -- The value displayed to the user
            label = "New York"
        },
        {
            value = "Paris",
            label = "Paris"
        },
        {
            value = "Rome",
            label = "Rome"
        }
    },
    -- Indexes of already selected choices
    default  = { 2, 4 },
}:ask() -- Returns a table of the selected choices

Composite

Will jump from field to field when appropriate.

TODO: field's length should be optional

Composite {
    prompt = "What's your birthday? ",
    -- Separator between each fields
    separator = " / ",
    -- Fields definition
    fields = {
        {
            placeholder = "YYYY",
            filter = function(input)
                return input:match("%d")
                    and input
                    or ""
            end,
            -- Required
            length = 4,
        },
        {
            placeholder = "mm",
            filter = function(input)
                return input:match("%d")
                    and input
                    or ""
            end,
            length = 2,
        },
        {
            placeholder = "dd",
            filter = function(input)
                return input:match("%d")
                    and input
                    or ""
            end,
            length = 2,
        },
    }
}:ask() -- Returns a table of each field's answer

giann / sirocco