CLASP.js

Command-Line Argument Sorting and Parsing, for JavaScript

Table of Contents

• Summary
• Introduction
• Installation & usage
  • The name
• Components
  • Command-line parsing
  • Declarative specification of flags and options
  • Utility functions for displaying usage and version information
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Development/Testing Dependencies
  • Related projects
  • License

Summary

CLASP stands for Command-Line Argument Sorting and Parsing. The first CLASP library was a C library with a C++ wrapper. There have been several implementations in other languages. CLASP.js is the JavaScript version.

Introduction

CLASP stands for Command-Line Argument Sorting and Parsing. The first CLASP library was a C library with a C++ wrapper (see project CLASP). There have been several implementations in other languages. CLASP.js is the JavaScript version.

All CLASP libraries provide facilities for Command Line Interface (CLI) programs as described in the Components section below.

Installation & usage

Install using npm install clasp-js.

Use it via require('clasp-js').

The name

NOTE: the name clasp-js follows NPM's package-name rules, but breaks with one of the tips - the one about not including js or node in the name - because there are multiple CLASP libraries, and there already exists a clasp package in NPM.

Components

Command-line parsing

All CLASP libraries discriminate between three types of command-line arguments:

• flags are hyphen-prefixed arguments that are either present or absent, and hence have a boolean nature;
• options are hyphen-prefixed arguments that are given values; and
• values are non-hyphen-prefixed arguments that represent values.

For example, in the command line

myprog --all -c --opt1=val1 infile outfile

there are:

• two flags, --all and -c;
• one option called --opt1, which has the value val1; and
• two values, infile and outfile.

Flags and options may have aliases. One-letter flags may be combined. Option aliases may specify a value, and may be combined with one-letter flags. UNIX de-facto standard arguments confer specific meanings:

• --help means that the program should show the usage/help information and terminate;
• --version means that the program should show the version information and terminate;
• -- means that all subsequent arguments should be treated as values, regardless of any hyphen-prefixes or embedded = signs.

Declarative specification of flags and options

CLASP.js provides the clasp.specifications module to declare flags and options and their aliases. Use Flag() and Option() to build a specification list, then pass it to clasp.api.parse(). See EXAMPLES.md for worked examples.

Utility functions for displaying usage and version information

CLASP.js provides clasp.usage.showUsage() and clasp.usage.showVersion() to display help and version information and optionally terminate the process. Standard --help and --version specifications are available via clasp.specifications.HELP_FLAG and clasp.specifications.VERSION_FLAG.

Examples

Examples are provided in the examples directory, along with a markdown description for each. A detailed list TOC of them is provided in EXAMPLES.md.

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/CLASP.js.

Dependencies

None

Development/Testing Dependencies

• mocha;

Related projects

CLASP.js is inspired by the C/C++ CLASP library, which is documented in the articles:

• An Introduction to CLASP, Matthew Wilson, CVu, January 2012;
• Anatomy of a CLI Program written in C, Matthew Wilson, CVu, September 2012; and
• Anatomy of a CLI Program written in C++, Matthew Wilson, CVu, September 2015.

Other CLASP libraries include:

• CLASP;
• CLASP.Go;
• CLASP.NET;
• CLASP.Python;
• CLASP.Ruby.

License

CLASP.js is released under the 3-clause BSD license. See LICENSE for details.