formatter.md

formatter

utilities for shell output formatting.

usage

[env FORMAT=terminal|markdown|raw ;] source ./formatter

./formatter -h

flags

-h

shows this help message. works only when the script is executed (not sourced).

API

when the formatter is sourced, it exposes an API composed of two parts; tags and functions.

some tags or functions will only be applied in a certain format, e.g. terminal. in such cases, the available formats will be marked in the description body, with available in: <formats...>. if no available formats are mentioned, the rendering will apply on all formats.

tags

tags are predefined variables that can be used to format text terms. wrap the terms with a start tag in the form _f_<name>, and a close tag in the form _f_<name>_off.

the definitions below describe only the start tag, for brevity.

_f_bold

formats the text as bold.

_f_italics

formats the text as italics.

_f_strike

formats the text as strike-through.

_f_under

^{available in: terminal}
formats the text as underlined.

_f_code

formats the text as inline code.

_f_sub

^{available in: markdown}
formats the text as sub-text.

_f_sup

^{available in: markdown}
formats the text as super-text.

_f_fg_<color>

^{available in: terminal}
applies foreground color to the text.

_f_bg_<color>

^{available in: terminal}
applies background color to the text.

functions

most of the tag variables has equivalent functions. they all follow the f_<name>() convention.

formatter functions can be piped, or accept arguments. those that can do both, with no side effects, will be marked with composeable.

f_bold(string...)

^composeable
formats passed arguments as bold text.

f_italics(string...)

^composeable
formats passed arguments as italics text.

f_strike(string...)

^composeable
formats passed arguments as strike-through text.

f_under(string...)

^{composeable
available in: terminal}
formats passed arguments as underlined text.

f_code(string...)

^composeable
formats passed arguments as inline code.
note to always pass arguments with 'strong quoting', or properly escape them, to avoid arbitrary code being interpreted by the shell.

f_sub(string...)

^{composeable
available in: markdown}
formats passed arguments as sub-text.

f_sup(string...)

^{composeable
available in: markdown}
formats passed arguments as super-text.

f_link([name], target)

formats passed arguments as an inline link. if name is passed, it will be used in the markdown format to name the link. the target will be used as the link ref.

f_fg_<color>(string...)

^{composeable
available in: terminal}
applies foreground color to passed arguments. e.g. f_fg_red("my text").

f_bg_<color>(string...)

^{composeable
available in: terminal}
applies background color to passed arguments. e.g. f_bg_red("my text")

f_heading(string)

^composeable
formats the passed string as heading.

f_subheading(string)

^composeable
formats the passed string as subheading.

f_list_item([title], body)

formats passed arguments as a list item. if title is passed, it will appear as the list item's first line, and will be styled as bold.

f_definition(term, description)

formats passed arguments as a definition list item. term is used as the item's term, and description is used as the item's description (its body content).
note that only inline code and bold styles are allowed to be nested inside definition list items.

f_code_definition(term, description)

same as f_definition(), except term is formatted as inline code.

f_code_block([lang], body)

formats passed arguments as a code block. if lang is passed, it will be used in the markdown format to highlight the code block. allowed lang values are those allowed in github-flavored markdown code blocks.
note to always enclose the passed body in 'strong quotes', or properly escape it, to avoid arbitrary code being interpreted by the shell.

f_output(body)

formats passed arguments as an output block. in markdown this is the same as f_code_block, and in terminal every line of the body will be prefixed with an arrow, to mark code output.

f_if(format, content)

only renders the content if the current format matches the passed format.

colors

here are the available color names to be used with the color formatting tags and functions:

red
green
yellow
blue
magenta
cyan
lightred
lightgreen
lightyellow
lightblue
lightmagenta
lightcyan

examples

• wrapping with tags

  echo "${_f_bold}this text will be bold${_f_bold_off}"
  echo "text can be ${_f_under}underlined${_f_under_off} as well"
  echo "color me ${_f_fg_yellow}yellow${_f_fg_off}"

• using functions

  echo "$(f_heading "foo")"
  echo "$(echo "foo" | f_heading)"
  echo "$(echo "foo" | f_heading | f_fg_yellow)"

  you can also skip the inner echo, if you're using composeable functions:

  echo "$(f_heading "foo" | f_fg_yellow)"

  echo "$(f_fg_yellow "foo" | f_bold | f_under)"

  some formatter functions cannot be composed, but can still be used regardless:

  echo "$(f_fg_rainbow "the quick brown fox jumps over the lazy dog")"

gotcha's

• nesting formats may not behave as expected with the terminal format, as some closing tags reset all formatting.
• heavy use of formatter functions will impact performance, so use them wisely.

references

• the colors used here are based on the SMYCK color scheme.
• the hex color values from SMYCK were converted to their xterm-256 ansi approximations with colortrans.py.

^{created with styli.sh}