Getting Started

An overview of SHML, how to download, install and use, syntax overview with examples.

To use SHML you must have unix-like (Darwin/macOS, Linux, etc.) POSIX-compliant operating system that supports ANSI/VT100 Control Sequences. If you are using an up to date version of macOS or any Linux distribution you should be good to go. If you run into issues please report it here.

Install

Unix-like

$ sudo bash -c 'curl -L https://raw.githubusercontent.com/odb/shml/1.1.0/shml.sh -o /usr/local/bin/shml && chmod +x /usr/local/bin/shml'

npm

$ npm install -g shml

Homebrew

$ brew install shml

You can also just download SHML without installing it...

Git

$ git clone git@github.com:odb/shml.git

Wget

$ wget https://github.com/odb/shml/archive/master.zip

Sourcing

In order to use SHML you must tell your shell environment where it is located. Lets assume that we are writing a BASH script and want to use SHML.

If you installed in using the 1-liner above you would do:

#!/usr/bin/env bash
source $(which shml)

If you downloaded SHML using git or wget you would do:

#!/usr/bin/env bash
source ./shml.sh

Foreground

To set the foreground color of any string or object you need to call the fgcolor method followed by an argument.

Arguments

Colors

Fifteen different colors to choose from:
black red green yellow blue magenta cyan gray white darkgray lightgreen lightyellow lightblue lightmagenta lightcyan

Termination

Following a string or object you must terminate the fgcolor method to ensure color doesn’t bleed. You can use any of the following termination arguments:

end off or reset

Code Samples

Here we will demonstrate how the fgcolor method can be used on a single line.

echo $(fgcolor green "RZA GZA") $(fgcolor end)

Some times one-line is not enough.

echo "
$(fgcolor yellow)
Inspectah Deck
Ghostface Killah
$(fgcolor end)
"

You can also use fgc as an alias for fgcolor.

echo $(fgc red "Killa Beez on a swarm") $(fgc end)

Results

Here is what the output should look like. Style may differ slightly depending on your terminal emulator settings.

Background

To set the background color of any string or object you need to call the bgcolor method followed by an argument.

Arguments

Colors

Fifteen different colors to choose from:
black red green yellow blue magenta cyan gray white darkgray lightgreen lightyellow lightblue lightmagenta lightcyan

Termination

Following a string or object you must terminate the background method to ensure color doesn’t bleed. You can use any of the following termination arguments:

end off reset

Code Samples

Here we will demonstrate how the background method can be used on a single line.

echo $(bgcolor red "I'm the O-D-B") $(bgcolor end)

Some times one-line is not enough.

echo "
$(bgcolor cyan)
...as you can see
F.B.I. don't you be watching me
$(bgcolor end)
"

You can also use bgc as an alias for bgcolor

echo "$(bgc green)NUH you know name, now give me my money!$(bgc end)"

Results

Here is what the output should look like. Style may differ slightly depending on your terminal emulator settings.

Attributes

The attribute method lets you stylize your text in 5 different ways.

Arguments

bold dim underline invert hidden

Termination

You can use any of the following termination arguments:

end off reset

Following a string or object you must terminate the attribute method. Typing $(attribute end) turns off everything, including foreground and background color methods.

Code Samples

echo "$(attribute underline "So Underlined") $(attribute end)"

echo "$(attribute bold "Such Bold") $(attribute end)"

echo "$(attribute invert "Why this inverted?") $(attribute end)"

You can also use a as an alias for attribute

echo "$(a bold "such BOLD shorter") $(a end)"

Results

Here is what the output should look like. Style may differ slightly depending on your terminal emulator settings.

Elements

Elements are methods that work a lot like <hr> & <br> HTML element tags. There is also a tab & indent method that acts like a   character entity. They are empty which means that they have no termination ends like the foreground color, background and attribute methods.

Arguments

The only method that allows arguments is hr:

~ # * + and/or any number e.g. 50

Code Samples (hr)

echo "$(hr)"

echo "$(hr 40)"

echo "$(hr '~' 30)"

echo "$(hr '#' 20)"

echo "$(hr '*' 10)"

echo "$(hr '+' 5)"

Results (hr)

Code Samples (br, indent, tab)

Break Line

echo "Wu$(br)Wu Tang$(br)Wu Tang$(br)Killah Beez$(br)We on a swarm"

Indent

echo "W$(indent)U$(indent)T$(indent)A$(indent)N$(indent)G"

You can also use i as an alias for indent

echo "F$(i)O$(i)R$(i)E$(i)V$(i)A"

Tab

echo "W$(tab)U$(tab)T$(tab)A$(tab)N$(tab)G"

Results (br, indent, tab)

Icons

Icons are flat ascii characters that are supported by most unix-like systems. If you run into compatibility issues please report it here.

Arguments

checkmark xmark heart sun star darkstar umbrella flag snowflake music scissors trademark copyright apple smile

Code Samples

Peter, a software engineer likes to use the xmark icon in his programs:

echo "$(icon xmark)TPS Reports $(icon xmark)Lumbergh $(icon xmark)Working"

When he is in a better mood, he tends to use the check icon:

echo "$(icon check)Kung Fu $(icon check)Fishing $(icon check)Sleep"

Sometimes he even uses the foreground color method to add some emphasis:

echo "$(color red)$(icon xmark)$(color end)TPS Reports $(color green)$(icon check)$(color end)Fishing"

Results

Emojis

To add an emoji you need to call the emoji method followed by an argument. Each emoji added to SHML was approved as part of Unicode® 6.0.0 Standard in 2010.

Arguments

Code Samples

echo "Couldn't peep it with a pair of $(emoji bifocals)"
echo "I'm no $(emoji joker) play me as a $(emoji joker)"
echo "$(emoji bee) on you like a $(emoji house) on $(emoji fire), $(emoji smoke) ya"

Results

Color Bar

To add a color bar you need to call the color-bar method followed by an (optional) argument.

Arguments

Fifteen different colors to choose from:

black red green yellow blue magenta cyan gray white darkgray lightgreen lightyellow lightblue lightmagenta lightcyan

Code Samples

echo "$(color-bar)"

echo "
$(color-bar red green yellow blue magenta \
cyan lightgray darkgray lightred \
lightmagenta lightcyan)
"

echo "Yeah ahuh, you know what it is $(color-bar black yellow black yellow)"

You can also use bar as an alias for color-bar

echo "I put it down from the whip to my diamonds, I'm in $(bar black yellow black yellow)"

Results

Confirm

Confirm allows you to simply ask end-users questions.

Usage

confirm QUESTION [SUCCESS_FUNCTION] [FAILURE_FUNCTION]

Code Samples

on_human() {
  dialog "What is your name?" "on_dialog"
}

on_dialog() {
  echo "$(color green "Hello, $1! $(emoji beer)")"
}

on_not_human() {
  confirm "$(color red "Do you come in peace?")" "on_friend" "on_enemy"
}

on_friend() {
  echo "$(emoji '=)') $(emoji beer)"
}

on_enemy() {
  echo "$(emoji rage) $(emoji poop)"
}

confirm "$(color blue "Are you human?")" "on_human" "on_not_human"
exit 0

Results