danhper / ex_cli Goto Github PK

View Code? Open in Web Editor NEW

214.0 6.0 15.0 76 KB

User friendly CLI apps for Elixir

Home Page: https://hex.pm/packages/ex_cli

License: MIT License

Elixir 100.00%

elixir cli commandparser

ex_cli's Introduction

ExCLI

User friendly CLI apps for Elixir.

Screencast

Here is a small screencast of what a generated CLI app looks like.

Installation

Add ex_cli to your list of dependencies in mix.exs:

def deps do
  [{:ex_cli, "~> 0.1.0"}]
end

Usage

The basic usage is to use ExCLI.DSL to define your CLI, and ExCLI.run to run it. Here is a sample application:

defmodule MyApp.SampleCLI do
  use ExCLI.DSL

  name "mycli"
  description "My CLI"
  long_description ~s"""
  This is my long description
  """

  option :verbose, count: true, aliases: [:v]

  command :hello do
    aliases [:hi]
    description "Greets the user"
    long_description """
    Gives a nice a warm greeting to whoever would listen
    """

    argument :name
    option :from, help: "the sender of hello"

    run context do
      if context.verbose > 0 do
        IO.puts("Running hello command")
      end
      if from = context[:from] do
        IO.write("#{from} says: ")
      end
      IO.puts("Hello #{context.name}!")
    end
  end
end

ExCLI.run!(MyApp.SampleCLI)

Which can be used in the following way.

sample_cli hello -vv world --from me

or using the command's alias:

sample_cli hi -vv world --from me

The application usage will be shown if the parsing fails. The above example would show:

usage: mycli [--verbose] <command> [<args>]

Commands
   hello   Greets the user

`escript` and `mix` integration

You can very easily generate a mix task or an escript using ExCLI

`escript`

Pass escript: true to the use ExCLI.DSL and set the module as escript :main_module:

# lib/my_escript_cli.ex
defmodule MyEscriptCLI do
  use ExCLI.DSL, escript: true
end

# mix.exs
defmodule MyApp.Mixfile do
  def project do
    [app: :my_app,
     escript: [main_module: MyEscriptCLI]]
  end
end

`mix` integration

Pass mix_task: TASK_NAME to the use ExCLI.DSL.

# lib/my_cli_task.ex
defmodule MyCLITask do
  use ExCLI.DSL, mix_task: :great_task
end

You can then run

mix great_task

and get nicely formatted help with

mix help great_task

Documentation

Check out the documentation for more information.

Roadmap

Command parser

The command parser is now working and should be enough for a good number of tasks.
Integration with escript and mix

ExCLI.DSL can generate a module compatible with escript.build as well as a mix task.
Usage generation

A nicely formatted usage is generated from the DSL.
Help command

Then the goal will be to add a help command which can be used as app help command to show help about command.
Command parser improvements

When the usage and help parts are done, there are a few improvements that will be nice to have in the command parser:
- the ability to set a default command
- the ability to easily delegate a command to another module
- command aliases
Man page generation

When all this is done, the last part will to generate documentation in man page and markdown formats, which will probably be done as a mix task.

Contributing

Contributions are very welcome, feel free to open an issue or a PR.

I am also looking for a better name, ideas are welcome!

ex_cli's People

Contributors

Stargazers

Watchers

Forkers

ruby2elixir matteosister codeclimate-testing 023soft randycoulman ijverig gabipurcaru mark-d-holmberg ejpcmac kokakiwi sohjiro ktscode lucianogb lynsei wingyplus

ex_cli's Issues

Allow usage of a name with dot

Great package!

I think it'd be really nice if this was possible

use ExCLI.DSL, mix_task: :'mytask.install'

So it conformed to mix command rules (like 'mix deps.get' 'mix coveralls.detail' etc)

Negative values for arguments not parsed

option :lon, help: "The venue's longitude", type: :float

% mix venue -v add 'Temple of Boom' --lat 53.8020657 --lon -1.5319708
No argument provided for 'lon'
% mix venue -v add 'Temple of Boom' --lat 53.8020657 --lon '-1.5319708'
No argument provided for 'lon'

Full script:

defmodule BandTracker.Venue do
  use ExCLI.DSL, mix_task: :venue                                                                                    
                             
  name "BandTracker.Venue"
  description "Venue operations"                          

  option :verbose, count: true, aliases: [:v]

  command :add do
    aliases [:a]
    description "Add a new venue"

    argument :name, help: "The venue's name"
    option :lat, help: "The venue's latitude", type: :float
    option :lon, help: "The venue's longitude", type: :float

    run context do
      if context.verbose > 0 do
        IO.puts("Adding new venue...")
      end

      name = context[:name]
      lat = context[:lat]
      lon = context[:lon]

      IO.write("Name: #{name}, latitude: #{lat}, longitude: #{lon}")
    end
  end
end

Might be me, but I fail to see how to actually use this. There are examples that describe how to use the ExCLI DSL, so that is nice and shiny; but how is one supposed to go from there to an actual script, that can be run from the CLI?

Name discussion

I am also looking for a better name, ideas are welcome!

So let's discuss it here. :-)

Release latest changes?

Thanks for this library! It's just what I needed for a little learning project I'm working on!

When you have time, could you please release a new version that has the latest fixes included? I'm seeing the warnings that were addressed in 8175d9c.

Thanks!

Doesn't format long_descriptions or help

The README and module doc both use the :help and long_description dsl options but I can't seem to get them to print when I use the cli. Any idea how I can use them?

Command aliases or fuzzy command lookup?

Thanks again for this library! I'm finding it really helpful on a little side/learning project I've been working on.

I recently found myself wanting to provide aliases for my commands so that I could use a shorter name on the command line. One way to do this would be to add an aliases option to Command, and then modify command lookup to take aliases into account.

However, I see in the README that one of the roadmap ideas is

fuzzy handling of command (i.e. npm insta will run npm install)

A first cut at fuzzy handling would likely involve just matching prefixes; that could be improved later if needed. Doing a prefix match would also address my need, as the aliases I want to define are prefixes of the full command names.

I've looked through the code, and I don't think it would be terribly difficult to implement either of these ideas.

I'm willing to start working on a PR for this, but first I'd like to know which of these two directions you'd prefer.

Do you prefer the fuzzy (starting with prefix) matching? Or do you prefer the alias idea?

My time is somewhat limited, so I can't guarantee how fast I can get this done, but I'm willing to do the work on it.