README

eclier

Pronounced like eclair

The core of a command line application allowing for trivial user extension.

Every command and subcommand is its own .lua file that is either shipped as part of the built-in cartridge of commands or a plugin that the user installs.

The core contains the following:

  • A module loading system for preparing different commands for use
  • The core subcommand router

How to write plugins

Create a new file in the script home named after the plugin subcommand, for example: scripts/hello.lua:

script.verb = "hello"
script.help = "prints everyone's favorite hello world message"
script.author = "Xe" -- put your github username here
script.version = "1.0"
script.usage = ""

function(run) 
  print "Hello, world!"
end

And then run it using the example shell cli:

~/go/src/github.com/Xe/eclier:master λ go run ./example/main.go hello
Hello, world!
Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const (
	BuiltinScriptPath = "<built-in>"
	BuiltinAuthor     = "<built-in>"
	BuiltinVersion    = "<built-in>"
)

    Constants for built-in commands.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Command

    type Command interface {
    	Close() error
    	Init()
    	ScriptPath() string
    	Verb() string
    	Help() string
    	Usage() string
    	Author() string
    	Version() string
    	Run(ctx context.Context, arg []string) error
    }

      Command is an individual subcommand.

      func NewBuiltinCommand

      func NewBuiltinCommand(verb, help, usage string, doer func(context.Context, []string) error) Command

        NewBuiltinCommand makes it easier to write core commands for eclier.

        type Router

        type Router struct {
        	// contains filtered or unexported fields
        }

          Router is the main subcommand router for eclier. At a high level what this is doing is similar to http.ServeMux, but for CLI commands instead of HTTP handlers.

          func NewRouter

          func NewRouter(opts ...RouterOption) (*Router, error)

            NewRouter creates a new instance of Router and sets it up for use.

            func (*Router) AddCommand

            func (r *Router) AddCommand(cmd Command)

              AddCommand adds a given command instance to the eclier router.

              func (*Router) Run

              func (r *Router) Run(ctx context.Context, arg []string) error

                Run executes a single command given in slot 0 of the argument array.

                type RouterOption

                type RouterOption func(*Router)

                  RouterOption is a functional option for Router.

                  func WithAsarFile

                  func WithAsarFile(shortName, fname string) RouterOption

                    WithAsarFile loads an asar file full of lua scripts into this eclier router.

                    func WithFilesystem

                    func WithFilesystem(shortName string, fs http.FileSystem) RouterOption

                      WithFilesystem loads a http.FileSystem full of lua scripts into this eclier router.

                      func WithGluaCreationHook

                      func WithGluaCreationHook(hook func(*lua.LState)) RouterOption

                        WithGluaCreationHook adds a custom bit of code that runs every time a new gopher-lua LState is created. This allows users of this library to register custom libraries to the pile of states.

                        func WithScriptHome

                        func WithScriptHome(dir string) RouterOption

                          WithScriptHome sets the router's script home to the given directory. This is where lua files will be walked and parsed.

                          type Script

                          type Script struct {
                          	Verb    string
                          	Help    string
                          	Usage   string
                          	Author  string
                          	Version string
                          }

                          Directories

                          Path Synopsis
                          cmd
                          hk
                          internal