Awesome

CLAP — Command line argument parser for Pharo

Named after and inspired by clap-rs, but this is an independent implementation.

CLAP project is after major refactoring (due to needs raised by PharoLauncher CLI) and should be more stable now. It means main pieces are there but some features are still missing and eventually may force changes in the design in rare cases.

Loading instructions

Pharo image already contains stable version of CLAP, but you can load latest version of project by:

Metacello new 
	baseline: 'Clap';
    repository: 'github://pharo-contributions/clap-st/src';
    load.

starting from the shell

git clone https://github.com/pharo-contributions/clap-st.git
cd clap-st
curl https://get.pharo.org/64/ | bash

…and then, in the image just downloaded, open a workspace and evaluate:

Metacello new 
	baseline: 'Clap';
   	repository: 'gitlocal://./src';
   	load.

Shameless plug: I work with Fari and direnv to automate building and launching the development image:

# setup $PHARO
fari build
fari run

Defining and invoking commands

Commands and subcommands (their specification) are instances of #ClapCommandSpec. To make a command accessible from the command line, return it from a class-side factory method with the <commandline> pragma. Such class-side method should be defined on user-defined subclass of ClapApplication. For instance, here's how we declare the traditional hello, world! example, with the actual behavior delegated the instance-side method ClapCommandLineExamples >> sayHello:

hello
	"The usual Hello-World example, demonstrating a Clap command with a couple features."
	<script>
	<commandline>
	^ (ClapCommandSpec id: #hello)
		description: 'Provides greetings';
		commandClass: self;
		addHelp;
		addFlag: #whisper description: 'Greet discretely';
		addFlag: #shout description: 'Greet loudly';
		addFlag: #language 
			description: 'Select language of greeting' 
			positionalSpec: [ :positional |
				positional
					symbol;
					defaultValue: [ :arg :app | app defaultLanguage ] ];
		addPositional: #who spec: [ :positional |
			positional
				description: 'Recipient of the greetings';
				multiple: true;
				defaultValue: [ :arg :app | { app defaultRecipient } ] ];
		yourself

For now, CLAP installs itself as a named command line handler; e.g., to run the hello example command:

$PHARO_VM $PHARO_IMAGE clap hello
$PHARO_VM $PHARO_IMAGE clap hello --shout you

Commands can also be tested from within the image; running them from an interactive session will not quit the image, but any output from the command will still go to the standard output:

ClapCommandLineExamples hello
	activateWith: #('hello' '--help').

Contributors

Many thanks to everyone who has contributed to clap in one way or another:

Clément Mastin, Damien Pollet, Rajula Vineet Reddy, Christophe Demarey