peowly
v1.3.2
Published
meow inspired parseArgs() based CLI parser with help text helpers
Downloads
141,189
Readme
meow
inspired parseArgs()
based CLI parser. Also contains help text helpers
Usage
Simple
const { flags } = peowly({
options: {
fix: {
description: 'Fixes stuff',
type: 'boolean',
},
},
});
Example
See example/basic.js
API
peowly()
peowly(options): { flags, input, remainderArgs, showHelp }
Meta Options
description
- string | false - a description that will be prefixed to the help text (defaults topkg.description
, deactivated byfalse
)examples
- seeHelpMessageInfo
help
- string - the help text to show on--help
, preferably generated withformatHelpMessage()
(defaults to being rendered withformatHelpMessage()
using available data)indent
- seeHelpMessageInfo
name
- string - the name of the CLI command. Used by a couple of other defaults. (defaults to the first key inpkg.bin
and else topkg.name
)pkg
-PackageJsonLike
- apackage.json
which some meta data can be derived fromprocessTitle
- string | false - sets theprocess.title
to this (defaults toname
, deactivated byfalse
)usage
- seeHelpMessageInfo
version
- string - the version to show on--version
(defaults topkg.version
)
Parser Options
args
- string[] - same as forparseArgs()
(defaults toprocess.argv
withexecPath
andfilename
removed)options
-Flags
- superset of that ofparseArgs()
. Every option / flag is expected to have adescription
string property in addition to whatparseArgs()
require and they may have alistGroup
string property as wellreturnRemainderArgs
- boolean - if set, then all parts ofargs
that doesn't match a flag inoptions
will be returned asremainderArgs
, which can eg. be forwarded to another parser
formatHelpMessage()
formatHelpMessage(name: string, info?: HelpMessageInfo): string
Arguments
name
- string - the name of the CLI command
HelpMessageInfo
aliases
-HelpListBasic
- list of help items to join withcommands
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 thename
and the suffix after that, separated by spacesflags
-HelpList
- the flags to output in the help, compatible withFlags
indent
- number - the number of spaces to indent the help text with (defaults to2
)noDefaultFlags
- boolean - excludes the default flags from the help textusage
- string - what, if anything, that follows the$ ${name}
in'Usage'
headline in the initial help text
Types
import type { AnyFlag } from 'peowly';
interface HelpListBasicItem {
listGroup?: string;
description: string;
}
type HelpListItem = AnyFlag | HelpListBasicItem;
type HelpListBasic = Record<string, HelpListBasicItem>;
type HelpList = Record<string, HelpListItem | string>;
defaultFlags
Contains the definition of the two default flags --help
and --version
.
formatHelpList()
Most of the time you should use formatHelpMessage()
instead.
function formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string
Arguments
list
- HelpList - the list that represents the flags, see types informatHelpMessage()
indent
- number - how far to indent the list
HelpListOptions
fixedPadName
- boolean - when set,padName
will be treated as a fixed rather than minimum paddingkeyPrefix
- string - a prefix for the namepadName
- number - the minimum padding between names and descriptionsshortFlagPrefix
- string - a prefix for ashortFlag
(defaults to'-'
)
formatFlagList()
function formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string
Same as formatHelpList()
but with the keyPrefix
option defaulting to '--'
.
formatGroupedHelpList()
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 unlessfixedPadName
is set) the padding between name and description will be calculated within each group instead of across all groupsdefaultGroupName
- 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
formatGroupedFlagList()
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 forparseArgs()
meow
- a more full fledged alternative and name inspiration (p
as inparseArgs
,eow
as inmeow
,ly
to avoid being perceived as a typejacking)meow-with-subcommands
- a companion module tomeow
that provides the same help functionality as this modulepeowly-commands
- a companion module to this module that makes it on par withmeow-with-subcommands
See also
parseArgs()
- the node.js API this module is built around. Available sincev18.3.0
andv16.17.0
, non-experimental sincev20.0.0
.