Cling

Based on spf13/cobra, Cling is built to be almost entirely modular, giving you absolute control over almost everything without the need for embedded macros - there isn't even a default help command or flag!

Contents

• Installation
• Basic Usage
• Commands
• Arguments and Options
• Customising
• Extensions
• Motivation
• Projects using Cling
• Contributing
• Contributors

Installation

1. Add the dependency to your shard.yml:

dependencies:
cling:
github: devnote-dev/cling

2. Run shards install

Basic Usage

require"cling"classMainCommand < Cling::Commanddefsetup : Nil@name="greet"@description="Greets a person"
add_argument "name", description:"the name of the person to greet", required:true
add_option 'c', "caps", description:"greet with capitals"
add_option 'h', "help", description:"sends help information"enddefpre_run(arguments : Cling::Arguments, options : Cling::Options) : Nilif options.has? "help"puts help_template # generated using Cling::Formatter
exit_program 0# exit code 0 for successfulendenddefrun(arguments : Cling::Arguments, options : Cling::Options) : Nil
message ="Hello, #{arguments.get("name")}!"if options.has? "caps"puts message.upcase
elseputs message
endendend
main =MainCommand.new
main.execute ARGV

$ crystal greet.cr -h
Greets a person
Usage:
greet <arguments> [options]
Arguments:
name the name of the person to greet (required)
Options:
-c, --caps greet with capitals
-h, --help sends help information
$ crystal greet.cr Dev
Hello, Dev!
$ crystal greet.cr -c Dev
HELLO, DEV!

Commands

By default, the Command class is initialized with almost no values. All information about the command must be defined in the setup method.

classMainCommand < Cling::Commanddefsetup : Nil@name="greet"@description="Greets a person"# defines an argument
add_argument "name", description:"the name of the person to greet", required:true# defines a flag option
add_option 'c', "caps", description:"greet with capitals"
add_option 'h', "help", description:"sends help information"endend

Note

See command.cr for the full list of options.

Commands can also contain children, or subcommands:

require"cling"# import our subcommand hererequire"./welcome_command"# using the `MainCommand` created earlier
main =MainCommand.new
main.add_command WelcomeCommand.new
# there is also the `add_commands` method for adding multiple# subcommands at one time# run the command
main.execute ARGV

$ crystal greet.cr -h
Greets a person
Usage:
greet <arguments> [options]
Commands:
welcome sends a friendly welcome message
Arguments:
name the name of person to greet (required)
Options:
-c, --caps greet with capitals
-h, --help sends help information
$ crystal greet.cr welcome Dev
Welcome to the CLI world, Dev!

As well as being able to have subcommands, they can also inherit certain properties from the parent command:

# in welcome_command.cr ...classWelcomeCommand < Cling::Commanddefsetup : Nil# ...# this will inherit the header and footer properties@inherit_borders=true# this will NOT inherit the parent flag options@inherit_options=false# this will inherit the input, output and error IO streams@inherit_streams=trueendend

Arguments and Options

Arguments and flag options can be defined in the setup method of a command using the add_argument and add_option methods respectively.

classMainCommand < Cling::Commanddefsetup : Nil
add_argument "name",
# sets a description for itdescription:"the name of the person to greet",
# set it as a required or optional argumentrequired:true,
# allow multiple values for the argumentmultiple:false,
# make it hidden from the help templatehidden:false# define an option with a short flag using chars
add_option 'c', "caps",
# sets a description for itdescription:"greet with capitals",
# set it as a required or optional flagrequired:false,
# the type of option it is, can be:# :none to take no arguments# :single to take one argument# or :multiple to take multiple argumentstype::none,
# optionally set a default valuedefault:nil,
# make it hidden from the help templatehidden:falseendend

Warning

You can only have one argument with the multiple option which will include all the remaining input values (or unknown arguments). See the example command for usage.

These arguments and options can then be accessed at execution time via the arguments and options parameters in the pre_run, run and post_run methods of a command:

classMainCommand < Cling::Command# ...defpre_run(arguments : Cling::Arguments, options : Cling::Options) : Nilif arguments.get("name").as_s.blank?
stderr.puts "Your name can't be blank!"
exit_program # defaults to exit code 1 for failedendendend

If you try to access the value of an argument or option that isn't set, it will raise a ValueNotFound exception. To avoid this, use the get? method and check accordingly:

# ...defrun(arguments : Cling::Arguments, options : Cling::Options) : Nil
caps = options.get?("caps").try(&.as_bool) ||false
stdout.puts caps # => falseend

Note

See argument.cr and option.cr for more information on parameter methods, and value.cr for value methods.

Customising

The help template is divided into the following sections:

[HEADER]
[DESCRIPTION]
[USAGE]
<NAME> <USE | "[<command>]" "[<arguments>]" "[<options>]">
[COMMANDS]
[ALIASES] <NAME> <SUMMARY>
[ARGUMENTS]
<NAME> <DESCRIPTION> ["(required)"]
[OPTIONS]
[SHORT] <LONG> <DESCRIPTION> ["(required)"] ["(default: ...)"]
[FOOTER]

Sections in <> will always be present, and ones in [] are optional depending on whether they are defined. Because of Cling's modularity, this means that you could essentially have a blank help template (wouldn't recommend it though).

You can customise the following options for the help template formatter:

classCling::Formatter::Options# The character to use for flag option delimiters (default is `-`).property option_delim : Char# Whether to show the `default` tag for options with default values (default is `true`).property show_defaults : Bool# Whether to show the `required` tag for required arguments/options (default is `true`).property show_required : Boolend

And pass it to the command like so:

require"cling"
options =Cling::Formatter::Options.new option_delim:'+', show_defaults:false# we can re-use this in multiple commands
formatter =Cling::Formatter.new options
classMainCommand < Cling::Command# ...defhelp_template : String
formatter.generate selfendend

Alternatively, if you want a completely custom design, you can pass a string directly:

defhelp_template : String<<-TEXT My custom command help text! Use: greet <name> [-c | --caps] [-h | --help] TEXTend

Extensions

Cling comes with a few useful extension methods for handling argument and option values:

require"cling"require"cling/ext"classStatCommand < Cling::MainCommanddefsetup : Nilsuper@name="stat"@description="Gets the stat information of a file"
add_argument "path", description:"the path of the file to stat", required:trueenddefrun(arguments : Cling::Arguments, options : Cling::Options) : Nil
path = arguments.get("path").as_path
ifFile.exists? path
info =File.info path
stdout.puts <<-INFO name: #{path.basename} size: #{info.size} directory: #{info.directory?} symlink: #{info.symlink?} permissions: #{info.permissions} INFOelse
stderr.puts "No file found at that path"endendendStatCommand.new.execute ARGV

$ crystal stat.cr ./shard.yml
name: shard.yml
size: 272
directory: false
symlink: false
permissions: rwxrwxrwx (0o777)

Note

See ext.cr for the full list of extension methods.

Additionally, you can define your own extension methods on the Value struct like so:

require"cling"moduleClingstructValuedefas_chars : Array(Char)
@raw.to_s.chars
endendendclassStatCommand# ...defpre_run(arguments : Cling::Arguments, options : Cling::Options) : Nilputs arguments.get("path").as_chars
# => ['.', '/', 's', 'h', 'a', 'r', 'd', '.', 'y', 'm', 'l']endend

Motivation

Most Crystal CLI builders/DSLs are opinionated with limited customisation available. Cling aims to be entirely modular so that you have the freedom to change whatever you want without having to write tons of boilerplate or monkey-patch code. Macro-based CLI shards can also be quite restrictive as they are not scalable, meaning that you may eventually have to refactor your application to another CLI shard. This is not meant to discourage you from using macro-based CLI shards, they are still useful for short and simple applications with a general template, but if you are looking for something to handle larger applications with guaranteed stability and scalability, Cling is the library for you.

Projects using Cling

Information made available thanks to shards.info.

• Docr - A CLI tool for searching Crystal documentation
• Fossil - 📦 Pterodactyl Archive Manager
• Geode - An alternative Crystal package manager
• Crimson - A Crystal Version Manager
• tanda_cli - A CLI application for people using Tanda/Workforce.com

Contributing

1. Fork it (https://github.com/devnote-dev/cling/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Devonte W - creator and maintainer

This repository is managed under the Mozilla Public License v2.

© 2022-present devnote-dev