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/OS X, Linux, etc.) POSIX-compliant operating system that supports ANSI/VT100 Control Sequences. If you are using an up to date version of OS X 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/latest/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 &nbsp; 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

Argument Alias(es) Result
smiley 1F603 '=)' ':-)' ':)' ๐Ÿ˜„
innocent 1F607 halo ๐Ÿ˜‡
joy 1F602 lol laughing ๐Ÿ˜‚
=p 1F61B stuck_out_tongue =P ๐Ÿ˜›
worried 1F61F sadface sad ๐Ÿ˜Ÿ
cry 1F622 crying tear ๐Ÿ˜ข
rage 1F621 redface ๐Ÿ˜ก
wave 1F44B hello goodbye ๐Ÿ‘‹
ok_hand 1F44C perfect okay nice ๐Ÿ‘Œ
thumbsup 1F44D +1 like ๐Ÿ‘
thumbsdown 1F44E -1 no dislike ๐Ÿ‘Ž
smiley_cat 1F63A happycat ๐Ÿ˜บ
cat 1F431 kitten :3 kitty ๐Ÿฑ
dog 1F436 puppy ๐Ÿถ
bee 1F41D honeybee bumblebee ๐Ÿ
pig 1F437 pighead ๐Ÿท
monkey 1F437 monkey_face ๐Ÿต
cow 1F42E happycow ๐Ÿฎ
panda 1F43C panda_face shpanda ๐Ÿผ
sushi 1F363 raw sashimi ๐Ÿฃ
home 1F3E0 house ๐Ÿ 
eyeglases 1F453 bifocals eyeglasses ๐Ÿ‘“
smoke 1F6AC smoking cigarette ๐Ÿšฌ
fire 1F525 flame hot ๐Ÿ”ฅ
hankey 1F4A9 poop shit ๐Ÿ’ฉ
beer 1F37A homebrew brew ๐Ÿบ
cookie 1F36A biscuit chocolate ๐Ÿช
lock 1F512 padlock secure ๐Ÿ”’
unlock 1F513 openpadlock ๐Ÿ”“
star 2B50 yellowstar โญ
joker 1F0CF black_joker wild ๐Ÿƒ
check 2705 white_check_mark โœ…
x 274C cross xmark โŒ
toilet 1F6BD restroom loo ๐Ÿšฝ
bell 1F514 ringer ring ๐Ÿ””
search 1F50E mag_right magnify ๐Ÿ”Ž
dart 1F3AF bullseye darts ๐ŸŽฏ
cash 1F4B5 dollar cream ๐Ÿ’ต
thinking 1F4AD thought_balloon ๐Ÿ’ญ
luck 1F340 four_leaf_clover ๐Ÿ€

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


Designed and built by @jdorfman and mervinej.
Code licensed under MIT, documentation under CC BY 4.0.