peowly

meow inspired parseArgs() based CLI parser. Also contains help text helpers

Usage

$3

``javascript
const { flags } = peowly({
options: {
fix: {
description: 'Fixes stuff',
type: 'boolean',
},
},
});
`

$3

See example/basic.js

API

$3

`ts
peowly(options): { flags, input, remainderArgs, showHelp }
`

#### Meta Options

* description - _string_ | _false_ - a description that will be prefixed to the help text (defaults to pkg.description, deactivated by false)
* examples - see HelpMessageInfo
* help - _string_ - the help text to show on --help, preferably generated with formatHelpMessage() (defaults to being rendered with formatHelpMessage() using available data)
* indent - see HelpMessageInfo
* name - _string_ - the name of the CLI command. Used by a couple of other defaults. (defaults to the first key in pkg.bin and else to pkg.name)
* pkg - _PackageJsonLike_ - a package.json which some meta data can be derived from
* processTitle - _string_ | _false_ - sets the process.title to this (defaults to name, deactivated by false)
* usage - see HelpMessageInfo
* version - _string_ - the version to show on --version (defaults to pkg.version)

#### Parser Options

* args - _string[]_ - same as for parseArgs() (defaults to process.argv with execPath and filename removed)
* options - _Flags_ - superset of that of parseArgs(). Every option / flag is expected to have a description string property in addition to what parseArgs() require and they may have a listGroup string property as well
* returnRemainderArgs - _boolean_ - if set, then all parts of args that doesn't match a flag in options will be returned as remainderArgs, which can eg. be forwarded to another parser

$3

`ts
formatHelpMessage(name: string, info?: HelpMessageInfo): string
`

#### Arguments

* name - _string_ - the name of the CLI command

#### HelpMessageInfo

* aliases - _HelpListBasic_ - list of help items to join with commands but with group name defaulting to 'Aliases' and other group names being prefixed with ' Aliases'
* commands - _HelpListBasic_ - list of help items to add prior to the flags list and with a default group name of 'Commands'
* examples - _(string | { prefix?: string, suffix?: string })[]_ - will be added as examples on individual lines prefixed with $ ${name} or, if provided as prefix and suffix, then the prefix will go inbetween $ and the name and the suffix after that, separated by spaces
* flags - _HelpList_ - the flags to output in the help, compatible with _Flags_
* indent - _number_ - the number of spaces to indent the help text with (defaults to 2)
* noDefaultFlags - _boolean_ - excludes the default flags from the help text
* usage - _string_ - what, if anything, that follows the $ ${name} in 'Usage' headline in the initial help text

#### Types

`ts
import type { AnyFlag } from 'peowly';

interface HelpListBasicItem {
listGroup?: string;
description: string;
}

type HelpListItem = AnyFlag | HelpListBasicItem;

type HelpListBasic = Record;

type HelpList = Record;
`

$3

Contains the definition of the two default flags --help and --version.

$3

Most of the time you should use formatHelpMessage() instead.

`ts
function formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string
`

#### Arguments

* list - _HelpList_ - the list that represents the flags, see types in formatHelpMessage()
* indent - _number_ - how far to indent the list

#### HelpListOptions

* fixedPadName - _boolean_ - when set, padName will be treated as a fixed rather than minimum padding
* keyPrefix - _string_ - a prefix for the name
* padName - _number_ - the minimum padding between names and descriptions
* shortFlagPrefix - _string_ - a prefix for a shortFlag (defaults to '-')

$3

`ts
function formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string
`

Same as formatHelpList() but with the keyPrefix option defaulting to '--'.

$3

`ts
formatGroupedHelpList(list: HelpList, indent: number, options?: HelpListGroupOptions): string
`

Similar to formatHelpList() but prints help items grouped and has some additional options to support it in that.

#### HelpListGroupOptions

Same as HelpListOptions but with these additional options:

* alignWithinGroups - _boolean_ - when set (and unless fixedPadName is set) the padding between name and description will be calculated within each group instead of across all groups
* defaultGroupName - _string_ - the default group name where all items that have no explicit group belonging will be placed (defaults to 'Default')
* defaultGroupOrderFirst - _boolean_ - if set the default group is added at the start rather than at the end

$3

`ts
formatGroupedFlagList(list: HelpList, indent: number, options?: HelpListGroupOptions): string
`

Same as formatGroupedHelpList() but with the keyPrefix option defaulting to '--' and defaultGroup defaulting to 'Options'.

Similar modules

* argsclopts - also concerned with generating help texts for parseArgs()
* meow - a more full fledged alternative and name inspiration (p as in parseArgs, eow as in meow, ly to avoid being perceived as a typejacking)
* meow-with-subcommands - a companion module to meow that provides the same help functionality as this module
* peowly-commands - a companion module to this module that makes it on par with meow-with-subcommands

See also

* parseArgs() - the node.js API this module is built around. Available since v18.3.0 and v16.17.0, non-experimental since v20.0.0`.