vivid-cli

Vivid-CLI

Use functions, in-line style commands, or both, to add colors and styles to command-line output.

Download source from github repository or via npm:

> npm install vivid-cli

It's as easy as:

var vivid = require('vivid-cli')

//using vivid's methods...
vivid.red('Error message.')
vivid.red().bold('Serious error message!')

//using in-line style commands...
vivid.log('{yellow}{bold}Information:{/all}\nThis should probably be some sort of \nuseful information for the user. \n{italic}{magenta}If{/c}{/italic} you are into that kind of thing.')

//using both
vivid.bold().red('Error:{/c} A bold error message for the user. {/bold}\n{cyan}Then maybe a helpful suggestion in cyan.')

//chaining commands lets you add automatic new-lines between the output...
vivid.bold().green('A Sample Heading')
  .log('Secondary information related to the \nopening heading, in default, standard font.')
  .bgYellow().black('And then a closing note on a yellow background.')

Demo Output

API

General Methods

log(input)

• input : Text string you wish to have logged to the console.
• Result: Parses any in-line style commands included within the string and then logs the stylized output to the console.

convert(input)

• input : Text string you wish to have converted from a vivid template to an ANSI-coded string.
• Result: Returns an ANSI-coded string version of the input, able to produce the same stylized output as vivid.log(), even with non-vivid APIs and methods (like console.log(), for example).

toggleDefault()

• Result: Switches the default method called when one of the color, background, or effect methods (listed below) is used and called with input.
• Options: The two default methods toggleDefault() can switch between are the log and convert methods.
• Default: log (meaning when one of the style methods below is called with input, the result will be to log the input to the console)

Example:

vivid.red('This will be logged to the console in red.')

vivid.toggleDefault()
//the default is now 'convert'
//meaning an ANSI-coded string will be returned
//whenever a style method is called with input

var useLater = vivid.under().red('Use this later and it will still be shown in red colored text, plus it will be underlined.')

console.log(useLater)
//logs the above string in red, underlined text

If you have toggled the default method and are unsure what it currently is, you can return the current default setting by using: vivid.default

Example:

var vivid = require('vivid-cli')

vivid.default
//returns 'log'

vivid.toggleDefault()

vivid.default
//now returns 'convert'
//use vivid.toggleDefault() to switch back to 'log' again

Text Color Methods and In-Line Commands

(Note: For text, background, and effect style methods, calling the method, while including text content as input, will result in that input being passed to the default method, as outlined above. Calling the method without input will chain the style command to the next command method called, with chaining continued until a method is called with text input included.)

Below is a list of each major color available using the vivid-cli API, both in method-form and as an in-line command:

• Red:
  • vivid.red()
  • {red}
• Blue:
  • vivid.blue()
  • {blue}
• Yellow:
  • vivid.yellow()
  • {yellow}
• Green:
  • vivid.green()
  • {green}
• Magenta:
  • vivid.magenta()
  • {magenta}
• Cyan:
  • vivid.cyan()
  • {cyan}
• Black:
  • vivid.black()
  • {black}
• White:
  • vivid.white()
  • {white}
• Restore Default/Clear Current Color Command:
  • n/a
  • {/c} or {default}

Background Color Methods and In-Line Commands

Below is a list of each major background color available using the vivid-cli API, both in method-form and as an in-line command:

• Red:
  • vivid.bgRed()
  • {bgRed}
• Blue:
  • vivid.bgBlue()
  • {bgBlue}
• Yellow:
  • vivid.bgYellow()
  • {bgYellow}
• Green:
  • vivid.bgGreen()
  • {bgGreen}
• Magenta:
  • vivid.bgMagenta()
  • {bgMagenta}
• Cyan:
  • vivid.bgCyan()
  • {bgCyan}
• Black:
  • vivid.bgBlack()
  • {bgBlack}
• White:
  • vivid.bgWhite()
  • {bgWhite}
• Restore Default/Clear Current Background Command:
  • n/a
  • {/bg} or {bgDefault}

Effect Methods and In-Line Commands

Below is a list of each effect available using the vivid-cli API, both in method-form and as an in-line command.

It is also important to notice that effect commands vary slightly from text color and background color commands.

For example, while both text color and background color commands have a single closing command that can be used to clear any text color or background color command being applied ({/c} for color commands and {/bg} for background commands), effect commands do not have such a universal closing command (this difference mirrors differences found in the ANSI codes used for stylizing command-line output). Instead of a universal closing command, each effect command has its own individual closing variant that must be used if you desire to clear that effect. As such, each effect command is listed below with its opening and closing variants made available.

• Bold:
  • vivid.bold()
  • start: {bold}
  • end: {/bold}
• Italic:
  • vivid.italic()
  • start: {italic}
  • end: {/italic}
• Underline:
  • vivid.under()
  • start: {under}
  • end: {/under}
• Strikeout:
• vivid.strike()
• start: {strike}
• end: {/strike}
• Invert:
  • vivid.invert()
  • start: {invert}
  • end: {/invert}
• Blink(only available on some terminal interfaces):
  • vivid.blink()
  • start: {blink}
  • end: {/blink}

Clear all applied styles with {/all} or {clear}.

If you wish to clear all text color, background color, and effect styles being applied to a string, this can be accomplished using either the {/all} command or the {clear} command.

All styles are cleared at the end of user input.

You do not have to worry about closing or clearing out styles you want to apply to your string of text until its very end. vivid-cli automatically clears out text stylization at the end of each conversion/logging of user input, assuring that such effects do not leak over into later command-line output.

For questions or issues: https://github.com/mcullenlewis/vivid-cli/issues or email.