Clap-st features & Examples Part 1

So as of this week, I am into the 10th week of my GSoC. So, I have been working on writing examples for clap-st with the clap-rs examples as reference. In this blog post, I would like to go through few examples of the current development version of clap-st. In this post, I use the current development version of clap-st so this might not work the same in the future :). Just to clear it up, most of the clap implementation is written by Damien Pollet and Clement Mastin. I am just a new kid here trying to understand clap and contribute as much as I can. So, all the credit should go to them.

Let me first list out the basic features of Clap-st and then explain each of these.

  1. Command
  2. Flag
  3. SubCommand
  4. Positionals
  5. Compulsory Args

I will briefly go through each one of these features along with examples. Since clap-st is still in development, there can be addition (or changes in a feature) of more features in the future. Hence, I named this post as Part 1. In the coming weeks I will write another part of this blog post with the latest features and more examples.

  1. Command
    • The command is the main part of the clap.To bluntly explain with Clap you should be able to create commands which can accept flags, positionals and subcommands.
    • With ClapCommand class a new command can be created and it will be followed by flags or positionals.
    • Example:

      | command context match |
      command := (ClapCommand withName: 'MyApp').
      context := ClapContext on: #('MyApp').
      match := command matchOn: context.
      ^match
    • This example creates a command with name ‘MyApp’ and then I tried to match the command with a collection ( which would be command line stdin in the future ). This will return AClapCommandMatch.
  2. Flag
    • Flags are similar to what we use in the Linux commands. Remember the command “ls”, which lists all the files and folders in a directory. And you might also know “ls -a”, which will list all the files and folders including all those which start with ‘.’ There are may such options which can be seen in the man pages. Flags are similar to this. You can define flags like slow, fast or flags like config which also takes a file positional as input. A lot can be done.
    • Flags have two name forms. A short and a long one. In the current Clap-st when you create a flag with name ‘xyz’. By default, the long form is –xyz and the short form is -x. Do note the number of hyphens.
    • Flags can be created using the class ClapFlag.
    • To retrieve the values of a flag, a flag must have a defined meaning. Refer to the example in SubCommand.
    • Example:
      ShortNameFlags –

      | flag1 command context match |
      flag1 := (ClapFlag withName: 'config').
      command := (ClapCommand withName: 'MyApp') addFlag: flag1.
      context := ClapContext on: #('MyApp' '-c').
      match := command matchOn: context.
      ^ match

      LongNameFlags –

      | flag1 command context match |
      flag1 := (ClapFlag withName: 'config').
      command := (ClapCommand withName: 'MyApp') addFlag: flag1.
      context := ClapContext on: #('MyApp' '--config').
      match := command matchOn: context.
      ^ match
  3. SubCommand
    • SubCommand is another command with its own set of arguments.
    • By arguments in the sense all the flags, positionals come under it.
    • Example:

      | flag subcommand command context match |
      flag:= (ClapFlag withName: 'list') meaning: [ :value | value isMismatch not].
      subcommand := (ClapCommand withName: 'test') addFlag: flag.
      command := (ClapCommand withName: 'MyApp')
      addSubcommand: subcommand.
      context := ClapContext on: #('MyApp' 'test' '--list').
      match := command matchOn: context.
      ((match atName: 'test') at:flag) value. "Returns true"
      ^ match
    • This example has a sub command which has a flag. So, if the context has that flag given in the input, the return value would be true. Else it would be false.
  4. Positionals
    • Positionals can be referred to as arguments other than flags like file names, numbers, strings, etc.
    • A positional can be created using the class ClapPositional.
    • Example:

      | pos1 command context match |
      pos1 := (ClapPositional withName: 'inputFile').
      command := (ClapCommand withName: 'MyApp') addPositional: pos1.
      context := ClapContext on: #('MyApp' 'input.txt').
      match := command matchOn: context.
      (match at:pos1) value. "Returns input.txt"
      ^ match
    • This example has a file name as positional.
  5. Compulsory Args
    • There might be situations where we might need some flags or some positionals as a compulsory for our functionality. In that case the method addCompulsory: is quite helpful.
    • Example:

      | pos1 command context match |
      pos1 := (ClapPositional withName: 'inputFile').
      command := (ClapCommand withName: 'MyApp') addCompulsory: (pos1) asCompulsory .
      context := ClapContext on: #('MyApp' 'input.txt').
      match := command matchOn: context.
      (match at:pos1) value. "Returns input.txt"
      ^ match
    • This example is similar to the positionals one. It has a file name as positional. But, here it is a compulsory field. without it, the code will return an AClapMismatch.

Do look at following classes for a deeper understanding Clap-st to write new Clap commands.

  • ClapCommand
  • ClapContext
  • ClapMatch
  • ClapFlag
  • ClapMisMatch
  • More classes can be found in the Clap-core package.

Link to the Clap-st repository: Clap-st

As of now a lot of these features are not merged into the master branch. So for development branches refer to Clements forked repository here.

For more examples or for the code refer this repository.

Note:

When you are trying to run these examples in the playground, make sure select the full code till the matchOn part and then select ‘Do it’ or ‘Do it and Go’. The output then would be a AClapCommandMatch. Then use the match variable and iterate the values. Feel free to clone the repo, experiment, give feedback or comments. Your feedback is very much valuable as Clap is still in development phase. Thank you.

References:

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s