yargonaut
Decorate yargs content with chalk styles and figlet fonts
yargonaut is the content decorator for yargs, allowing you to customize your yargs-based CLI output using chalk styles and/or figlet fonts ... easily!
Why? Because CLI apps with color and ASCII Art are more fun!
Could you customize yargs text, possibly using chalk or figlet, without yargonaut? Absolutely. But yargonaut makes it so easy! And yargonaut supports all locales that yargs and figlet support - out of the box.
Could terminal coloring or ASCII Art fonts be annoying in CLI apps? Well, sure. But used tastefully, it can add a degree of creative flair to make your CLI stand out. Use wisely!
Install
npm install --save yargonaut yargs
var yargonaut = // yargonaut first!var yargs = // then yargs
yargonaut assumes you have yargs installed independently.
To automatically support all locales that yargs supports, make sure to require('yargonaut')
in code before you require('yargs')
. This is important! If you choose to ignore this, yargonaut will attempt workarounds as best it can, but any issues caused by incorrect ordering of require()
statements will not be given priority. The ordering should be natural, since you'll need to configure yargonaut before yargs parses CLI args anyway.
Note that yargonaut does not wrap yargs and is not a replacement for yargs. It's built to work with yargs side-by-side, and it doesn't lock you in to a particular version of yargs, though internal string customization is only supported in yargs v3.16.1 and up.
If anything goes wrong, yargonaut attempts to fail gracefully and silently, so your CLI still works, just without the cool colors/fonts.
Examples
Use a single style and font for all top-level yargs strings:
style'blue' // that's it! var argv = argv
$ node order.js
_____ __ _
/ ___/__ __ _ __ _ ___ ____ ___/ /__ (_)
/ /__/ _ \/ ' \/ ' \/ _ `/ _ \/ _ (_-<_
\___/\___/_/_/_/_/_/_/\_,_/_//_/\_,_/___(_)
add Add item to cart
rm Remove item from cart
____ __ _ _
/ __ \___ / /_(_)__ ___ ___ (_)
/ /_/ / _ \/ __/ / _ \/ _ \(_-<_
\____/ .__/\__/_/\___/_//_/___(_)
/_/
-p, --product Product id(s) [required]
-s, --size Desired product size [choices: "s", "m", "l"] [default: "m"]
-c, --color Desired product color
____ __ _
/ __/_ _____ ___ _ ___ / /__ ___ (_)
/ _/ \ \ / _ `/ ' \/ _ \/ / -_|_-<_
/___//_\_\\_,_/_/_/_/ .__/_/\__/___(_)
/_/
order.js add -p 123 -s l -c green Add large, green product with id 123
__ ____ _ _ __ __ _
/ |/ (_)__ ___ (_)__ ___ _ _______ ___ ___ __(_)______ ___/ / ___ ________ ___ ____ _ ___ ___ / /_(_)
/ /|_/ / (_-<(_-</ / _ \/ _ `/ / __/ -_) _ `/ // / / __/ -_) _ / / _ `/ __/ _ `/ // / ' \/ -_) _ \/ __/
/_/ /_/_/___/___/_/_//_/\_, / /_/ \__/\_, /\_,_/_/_/ \__/\_,_/ \_,_/_/ \_, /\_,_/_/_/_/\__/_//_/\__(_)
/___/ /_/ /___/
p
Use one style and font for help content and another for error messages:
var argv = argv
$ node order.js
________ ________ _____ ______ _____ ______ ________ ________ ________ ________
|\ ____\|\ __ \|\ _ \ _ \|\ _ \ _ \|\ __ \|\ ___ \|\ ___ \|\ ____\ ___
\ \ \___|\ \ \|\ \ \ \\\__\ \ \ \ \\\__\ \ \ \ \|\ \ \ \\ \ \ \ \_|\ \ \ \___|_|\__\
\ \ \ \ \ \\\ \ \ \\|__| \ \ \ \\|__| \ \ \ __ \ \ \\ \ \ \ \ \\ \ \_____ \|__|
\ \ \____\ \ \\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \\ \ \ \ \_\\ \|____|\ \ ___
\ \_______\ \_______\ \__\ \ \__\ \__\ \ \__\ \__\ \__\ \__\\ \__\ \_______\____\_\ \|\__\
\|_______|\|_______|\|__| \|__|\|__| \|__|\|__|\|__|\|__| \|__|\|_______|\_________\|__|
\|_________|
add Add item to cart
rm Remove item from cart
________ ________ _________ ___ ________ ________ ________
|\ __ \|\ __ \|\___ ___\\ \|\ __ \|\ ___ \|\ ____\ ___
\ \ \|\ \ \ \|\ \|___ \ \_\ \ \ \ \|\ \ \ \\ \ \ \ \___|_|\__\
\ \ \\\ \ \ ____\ \ \ \ \ \ \ \ \\\ \ \ \\ \ \ \_____ \|__|
\ \ \\\ \ \ \___| \ \ \ \ \ \ \ \\\ \ \ \\ \ \|____|\ \ ___
\ \_______\ \__\ \ \__\ \ \__\ \_______\ \__\\ \__\____\_\ \|\__\
\|_______|\|__| \|__| \|__|\|_______|\|__| \|__|\_________\|__|
\|_________|
-p, --product Product id(s) [required]
-s, --size Desired product size [choices: "s", "m", "l"] [default: "m"]
-c, --color Desired product color
_______ ___ ___ ________ _____ ______ ________ ___ _______ ________
|\ ___ \ |\ \ / /|\ __ \|\ _ \ _ \|\ __ \|\ \ |\ ___ \ |\ ____\ ___
\ \ __/| \ \ \/ / | \ \|\ \ \ \\\__\ \ \ \ \|\ \ \ \ \ \ __/|\ \ \___|_|\__\
\ \ \_|/__ \ \ / / \ \ __ \ \ \\|__| \ \ \ ____\ \ \ \ \ \_|/_\ \_____ \|__|
\ \ \_|\ \ / \/ \ \ \ \ \ \ \ \ \ \ \ \___|\ \ \____\ \ \_|\ \|____|\ \ ___
\ \_______\/ /\ \ \ \__\ \__\ \__\ \ \__\ \__\ \ \_______\ \_______\____\_\ \|\__\
\|_______/__/ /\ __\ \|__|\|__|\|__| \|__|\|__| \|_______|\|_______|\_________\|__|
|__|/ \|__| \|_________|
order.js add -p 123 -s l -c green Add large, green product with id 123
╔╦╗┬┌─┐┌─┐┬┌┐┌┌─┐ ┬─┐┌─┐┌─┐ ┬ ┬┬┬─┐┌─┐┌┬┐ ┌─┐┬─┐┌─┐┬ ┬┌┬┐┌─┐┌┐┌┌┬┐
║║║│└─┐└─┐│││││ ┬ ├┬┘├┤ │─┼┐│ ││├┬┘├┤ ││ ├─┤├┬┘│ ┬│ ││││├┤ │││ │
╩ ╩┴└─┘└─┘┴┘└┘└─┘ ┴└─└─┘└─┘└└─┘┴┴└─└─┘─┴┘ ┴ ┴┴└─└─┘└─┘┴ ┴└─┘┘└┘ ┴
p
Customize only specific yargs strings:
style'yellow' 'Invalid values:' var argv = argv
$ node order.js -s xl
█████ ████ ███ █████ ████
░░███ ░░███ ░░░ ░░███ ░░███
░███ ████████ █████ █████ ██████ ░███ ████ ███████ █████ █████ ██████ ░███ █████ ████ ██████ █████ ██
░███ ░░███░░███ ░░███ ░░███ ░░░░░███ ░███ ░░███ ███░░███ ░░███ ░░███ ░░░░░███ ░███ ░░███ ░███ ███░░███ ███░░ ░░
░███ ░███ ░███ ░███ ░███ ███████ ░███ ░███ ░███ ░███ ░███ ░███ ███████ ░███ ░███ ░███ ░███████ ░░█████
░███ ░███ ░███ ░░███ ███ ███░░███ ░███ ░███ ░███ ░███ ░░███ ███ ███░░███ ░███ ░███ ░███ ░███░░░ ░░░░███
█████ ████ █████ ░░█████ ░░████████ █████ █████░░████████ ░░█████ ░░████████ █████ ░░████████░░██████ ██████ ██
░░░░░ ░░░░ ░░░░░ ░░░░░ ░░░░░░░░ ░░░░░ ░░░░░ ░░░░░░░░ ░░░░░ ░░░░░░░░ ░░░░░ ░░░░░░░░ ░░░░░░ ░░░░░░ ░░
Argument: s, Given: "xl", Choices: "s", "m", "l"
Change default rendering strategy for a specific string:
var argv = argv
$ node order.js -a -b
██╗ ██╗███╗ ██╗██╗ ██╗███╗ ██╗ ██████╗ ██╗ ██╗███╗ ██╗ █████╗ ██████╗ ██████╗ ██╗ ██╗███╗ ███╗███████╗███╗ ██╗████████╗███████╗ █████╗ ██████╗
██║ ██║████╗ ██║██║ ██╔╝████╗ ██║██╔═══██╗██║ ██║████╗ ██║ ██╔══██╗██╔══██╗██╔════╝ ██║ ██║████╗ ████║██╔════╝████╗ ██║╚══██╔══╝██╔════╝██╗ ██╔══██╗ ██╔══██╗
██║ ██║██╔██╗ ██║█████╔╝ ██╔██╗ ██║██║ ██║██║ █╗ ██║██╔██╗ ██║ ███████║██████╔╝██║ ███╗██║ ██║██╔████╔██║█████╗ ██╔██╗ ██║ ██║ ███████╗╚═╝ ███████║ ██████╔╝
██║ ██║██║╚██╗██║██╔═██╗ ██║╚██╗██║██║ ██║██║███╗██║██║╚██╗██║ ██╔══██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║██╔══╝ ██║╚██╗██║ ██║ ╚════██║██╗ ██╔══██║ ██╔══██╗
╚██████╔╝██║ ╚████║██║ ██╗██║ ╚████║╚██████╔╝╚███╔███╔╝██║ ╚████║ ██║ ██║██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║███████╗██║ ╚████║ ██║ ███████║╚═╝ ██║ ██║▄█╗ ██████╔╝
╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚══╝╚══╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═════╝
API
Chainable config methods
errors(font)
Render error messages using the specified figlet font.
- Returns:
yargonaut
singleton font
: string, name of figlet font
errorsStyle(style)
Apply the given chalk style to error messages, e.g. errorsStyle('red.bold')
.
- Returns:
yargonaut
singleton style
: string, the dot-delimited chalk style (color/modifier) to use
font(font, [key])
Render yargs strings using the specified figlet font. Optionally specify which yargs string(s) the font should apply to.
- Returns:
yargonaut
singleton font
: string, name of figlet fontkey
: string or array of strings, optional key(s) the font should apply to
help(font)
Render help content strings using the specified figlet font.
- Returns:
yargonaut
singleton font
: string, name of figlet font
helpStyle(style)
Apply the given chalk style to help content, e.g. helpStyle('green.underline')
.
- Returns:
yargonaut
singleton style
: string, the dot-delimited chalk style (color/modifier) to use
ocd(fn)
For obsessive control over string transformations, provide a function that yargonaut will call for every yargs string (every y18n lookup).
- Returns:
yargonaut
singleton fn
: function that returns a string and accepts the following:key
: string, the yargs key being renderedorigString
: string, the original string resolved by y18nnewString
: string, the new string as rendered by yargonaut/figletfiglet
: figlet, the figlet instancefont
: string, the configured figlet font for the key
style(style, [key])
Apply the given chalk style to all yargs strings, e.g. style('blue')
. Optionally specify which yargs string(s) the style should apply to.
- Returns:
yargonaut
singleton style
: string, the dot-delimited chalk style (color/modifier) to usekey
: string or array of strings, optional key(s) the style should apply to
transformUpToFirstColon(key)
Change the default splitting/rendering strategy for specific yargs strings.
- Returns:
yargonaut
singleton key
: string or array of strings, optional key(s) the render strategy should apply to
transformWholeString(key)
Change the default splitting/rendering strategy for specific yargs strings.
- Returns:
yargonaut
singleton key
: string or array of strings, optional key(s) the render strategy should apply to
Getter methods
getAllKeys()
Get a list of all known yargs strings (help content + error messages) subject to y18n lookup and yargonaut rendering.
- Returns: array of strings, representing all configured yargs strings
getErrorKeys()
Get a list of known error messages subject to y18n lookup and yargonaut rendering.
- Returns: array of strings, representing configured error msg yargs strings
getHelpKeys()
Get a list of known help content strings subject to y18n lookup and yargonaut rendering.
- Returns: array of strings, representing configured help content yargs strings
Convenience methods for playing with stuff
asFont(text, font, [throwErr])
Render any text as the given figlet font and return as string.
- Returns: string, the text rendered as font
text
: string, the text to renderfont
: string, the figlet font to use for renderingthrowErr
: boolean, optional flag to throw any error that might occur, defaults tofalse
chalk()
Get access to the chalk
instance used by yargonaut. In case you want to color your own strings without having to require('chalk')
yourself.
- Returns:
chalk
, the chalk instance
figlet()
Get access to the figlet
instance used by yargonaut. I mean, why not?
- Returns:
figlet
, the figlet instance
listFonts()
Get a list of all supported figlet fonts. Maybe you want to mix it up with a random font?
- Returns: array of strings, representing supported font names
printFont(font, [text], [throwErr])
Test print one figlet font to stdout using console.log()
.
- Returns: undefined
font
: string, the figlet font to test printtext
: string, optional text to print as font, defaults to font namethrowErr
: boolean, optional flag to throw any error that might occur, defaults tofalse
printFonts([text], [throwErr])
Test print every supported figlet font to stdout using console.log()
.
- Returns: undefined
text
: string, optional text to print as font, defaults to font namethrowErr
: boolean, optional flag to throw any error that might occur, defaults tofalse
License
Apache-2.0 © Andrew Goode