denomander@0.5.0

Denomander is a solution for Deno command-line interfaces. It is inspired from commander.js by tj which is the node’s version.

Installation

import Denomander from "https://deno.land/x/denomander/mod.ts";

Usage example

At first initialize the app and optionally you may pass the name, description and version of the app. If not you can change them afterwards by setting the app_name, app_description and app_version variables.

const program = new Denomander(
  {
    app_name: "My MY App",
    app_description: "My MY Description",
    app_version: "1.0.1"
  }
);

There are three option types: commands, options and required options.

Options

To set an option just call the option() method passing a) the sort and the long flag seperated by space and b) the description. The value can be accessed as properties.

program
  .option("-a --address", "Define the address")
  .option("-p --port", "Define the port")
  .parse(Deno.args);

  if(program.address){
    const port = program.port || "8000";
    console.log(`Server is running on <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>p</mi><mi>r</mi><mi>o</mi><mi>g</mi><mi>r</mi><mi>a</mi><mi>m</mi><mi mathvariant="normal">.</mi><mi>a</mi><mi>d</mi><mi>d</mi><mi>r</mi><mi>e</mi><mi>s</mi><mi>s</mi></mrow><mo>:</mo></mrow><annotation encoding="application/x-tex">{program.address}:</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">p</span><span class="mord mathnormal">ro</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">am</span><span class="mord">.</span><span class="mord mathnormal">a</span><span class="mord mathnormal">dd</span><span class="mord mathnormal">ress</span></span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{port}`);
  }

You may define the option’s short and long flags by seperating them with either with a) space, b) comma, or c) | (vertical bar or “pipe”)

program
  .option("-a, --address", "Define the address")
  .option("-p | --port", "Define the port")
  .parse(Deno.args);

console.log(`Server is running on <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>p</mi><mi>r</mi><mi>o</mi><mi>g</mi><mi>r</mi><mi>a</mi><mi>m</mi><mi mathvariant="normal">.</mi><mi>a</mi><mi>d</mi><mi>d</mi><mi>r</mi><mi>e</mi><mi>s</mi><mi>s</mi></mrow><mo>:</mo></mrow><annotation encoding="application/x-tex">{program.address}:</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">p</span><span class="mord mathnormal">ro</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">am</span><span class="mord">.</span><span class="mord mathnormal">a</span><span class="mord mathnormal">dd</span><span class="mord mathnormal">ress</span></span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{program.port}`);

Required Options

The implementation of required option is exactly same as the optional option but you have to call the requiredOption() method instead.

program
  .option("-a --address", "Define the address")
  .requiredOption("-p --port", "Define the port")
  .parse(Deno.args);

  // The port is required so it must have a value
  let address = program.address || "localhost";
  console.log(`Server run on <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>a</mi><mi>d</mi><mi>d</mi><mi>r</mi><mi>e</mi><mi>s</mi><mi>s</mi></mrow><mo>:</mo></mrow><annotation encoding="application/x-tex">{address}:</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord"><span class="mord mathnormal">a</span><span class="mord mathnormal">dd</span><span class="mord mathnormal">ress</span></span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{program.port}`);

Multiple short flags is supported (example from docker exec command)

You have the option to pass more than one short flags.

program
  .option("-i --interactive ", "Keep STDIN open even if not attached")
  .option("-t --tty", "Allocate a pseudo-TTY")
  .parse(Deno.args);

  if(program.interactive){
    console.log('Interactive Mode');
  }

  if(program.tty){
    console.log('Pseudo-TTY');
  }

  // deno run example.ts -it 
  // The previous command passes true in both if statements therfore it prints out both console.log commands

Commands

There are two ways to implement the command options. The first is to use an action handler by calling the action() method immediately after the command definition passing the callback function and the second is with custom one-line implementation.

Action Handler

program
  .command("clone [foldername]")
  .description("clone a repo")
  .action((foldername) => {
    console.log("The repo is cloned into: " + foldername);
  });

program.parse(Deno.args);

Custom Implementation

program.command("serve", "Start the server");

if(program.serve){
  console.log("The server has started...");
}

program.parse(Deno.args);

Option to change default commands (help, version)

In order to change the default commands (help, version) just call the corresponding method. In case of help pass the command and the description but in case of version you may also pass the actual version of the app and after that the command and the description.

 program.setVersion(
    "1.8.1",
    "-x --xversion",
    "Display the version of the app"
  );

  program.setHelp(
    "-c --customhelp",
    "Custom print help"
  );
  
  program.parse(args);

Custom help and version

To customize the commands call on() method passing the command and the callback function.

Must be before parse()

program.on("--help", () => {
  console.log("New Help Screen");
  console.log("--- --- ---");
  console.log("-p --port Define port");
});

program.on("--version", () => {
  console.log("New version are coming next week");
  console.log("v1.5.6");
});

// Last command
program.parse(args);

ToDo

program.on() method
Custom option processing
Option to change default commands (help, version)
description(), action() methods
Multiple short flags (-abc)
Long Flag alias

Used

Release History

0.1.0
- Initial Commit
0.2.0
- Change Command of Default Options [help, version]
- Custom help and version (program.on() method)
- Add description() and action() methods for commands
0.3.0
- Multiple short flags
- Comma and vertical bar separated options
0.3.1
- Add docblocks
- Extract some interfaces
- Fix some code readability errors
- Change internal exported classed to named from default (Only mod.ts file has the default export od Denomander class)
0.4.0
- Add CustomArgs interface
- Generate documentation
- Create utils finalise clearing project

Contributing

Fork it (https://github.com/yourname/yourproject/fork)
Create your feature branch (git checkout -b feature/fooBar)
Commit your changes (git commit -am 'Add some fooBar')
Push to the branch (git push origin feature/fooBar)
Create a new Pull Request

License

Distributed under the MIT License.

https://github.com/siokas/denomander