ruedigergad/cli4clj

Create simple interactive CLIs for Clojure applications.

cli4clj

Create simple interactive CLIs for Clojure applications.

Overview

The aim of cli4clj is to allow the quick and effortless creation of interactive command line interfaces (CLIs). It is build on top of jline2. Features of cli4clj are:

• Simple configuration via maps
• Command line history
  • Default configuration for persistent history (since 1.4.0)
• Command line editing
• Tab-completion
  • For command names
  • Hints for selected commands: based on function arguments and custom hints
• Aliases can be used to define alternative command names, e.g., for shortcuts.
• Clojure data types, e.g., vector, list, map, etc., can be used as command arguments.
• Build-in help
• Customizable, similar to the Clojure REPL
• Functionality for testing CLIs via unit tests [1], [2]
• "Embedded CLIs"

On my website I wrote some posts about cli4clj in which you can find more verbose information.

Usage

See https://github.com/ruedigergad/cli4clj/blob/master/src/cli4clj/example.clj for a usage example.

The given examples can be run via "lein run", respectively "lein run -- alt" to show the "alternate" scrolling mode.

First, animated gifs show basic interaction and the alternate scrolling mode. Afterwards, a static textual example provides some more details.

Basic Interaction:

Alternate Scrolling Mode Introduction:

Below is an example output that shows running the usage example:

~/r/p/c/cli4clj (master=) lein run
cli# help
add [a]
    Add two values.	 Arguments: [[summand1 summand2]]

divide [d]
    Divide two values.	 Arguments: [[numer denom]]
    The first argument will be divided by the second argument.

help [?]
    Show help.
    Display a help text that lists all available commands including further detailed information about these commands.

quit [q]
    Quit the CLI.
    Terminate and close the command line interface.

test-cmd [h t]
    Test Command
    Prints a test message to stdout.

to-csv
    Seq to CSV	 Arguments: [[data]]
    E.g.: "to-csv [1 2 3]"

cli# test-cmd
This is a test.
cli# t
This is a test.
cli# add 1 2
3
cli# ; Example for an error due to wrong number of arguments.
cli# add 1 2 3
Wrong number of args (3) passed to: example/-main/fn--168
cli# ; Example for an error due to exception in function.
cli# divide 1 0
Divide by zero
cli# d 4 2
2
cli# d 4 3
4/3
cli# ; Example to show the use of complexer data types, here, a vector and a list.
cli# to-csv [1 7 0 1]
"1,7,0,1"
cli# ; Note that the list is not quoted.
cli# to-csv (1 8 6 4)
"1,8,6,4"
cli# 
cli# ; Examples of tab-completion.
cli# TAB
?        a        add      d        divide   e        exit     h        help     q        quit     t        test     to-csv   
cli# add TAB
Arguments: [[summand1 summand2]]                                      
cli# add 1 2
3
cli# diTAB
cli# divide TAB
Arguments: [[numer denom]]   Divide two values.                                        
cli# divide 1 3
1/3
cli# to-csv TAB
Arguments: [[data]]                                                                                                     
The data argument can be of any Clojure sequence type, e.g., [1 2 3] or (:a :b :c). Note that the list is not quoted.   
                                                                                                                        
cli# to-csv [1 2 3]
"1,2,3"
cli# q
~/r/p/c/cli4clj (master=) lein run

For examples how the testing functionality can be used please see the test cases in: https://github.com/ruedigergad/cli4clj/blob/master/test/cli4clj/test/example.clj

API docs can be found at: http://ruedigergad.github.io/cli4clj/doc/

Detailed Test Results

Detailed unit test results are avilable at: http://ruedigergad.github.io/cli4clj/test-results/html/

License

Copyright © 2015-2021 cli4clj Contributors

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

cli4clj's Issues

EOF needs to optionally quit

Right now, pressing Ctl-D on MacOS doesn't shut down a CLI application based on cli4clj as with most other MacOS command line apps. There probably needs to be an option in cli4clj that will optionally detect EOF and return as if "q" had been entered into the CLI.

Can't use invalid edn as input to a cli

We have cli program that has valid inputs that aren't valid edn. For example, we allow users to specify ids that have a slash in them: 12345/abc. cli4clj runs this through the clojure read function, which crashes when trying to read this - it thinks it's an invalid number.

Would it be possible to allow the read function to be pluggable, similar to how eval is pluggable? Or is there some other way to work around this issue?

cannot get the example to run on Win 10 cmd.

hello, this appears to be a very useful tool for my project but I failed to get it to work on the very first try. When running lein run I got the first prompt but then it would not respond to any commands:

> lein run
Reflection warning, C:\...\form-init8532592205835804337.clj:1:889 - call to static method invokeStaticMethod on clojure.lang.Reflector can't be resolved (argument types: unknown, java.lang.String, unknown).
cli#



Terminate batch job (Y/N)? y

What may I be missing?

Thanks.