diff --git a/plugins/printc/README.md b/plugins/printc/README.md new file mode 100644 index 000000000..59e0f1b2a --- /dev/null +++ b/plugins/printc/README.md @@ -0,0 +1,129 @@ +# printc + +With this plugin you can print any color within the rgb color space via an interface that +is as simple as a regular print statement. + +This simple tool provides an abstraction layer on top of terminal ANSI rgb escape codes, +making the addition of colorized output to your functions, shell scripts, and/or +interactive terminal in zsh a piece of cake. There is support for any of the colors which +can be achieved via the form R G B, where R, G and B are any numeric value +between 0 and 255, representing the red, green, blue color space values respectively. +Users of this plugin are able to issue a `printc` statement, followed by the previous +mentioned rgb values, followed by the text to be printed. There is also 36 built in colors +which can be accessed via tab auto-complete. And there is support for bold, italic, and +underline text. + +#### Table of Contents + - [Setup](#Setup) + - [Configuration](#Configuration) + - [Requirements](#Requirements) + - [Italics Setup](#Italics-Setup) + - [Usage](#Usage) + - [Options](#Options) + - [General Structure of Command](#General-Structure-of-Command) + - [Notes on Environment Setup and Script Usage](#Notes-on-Environment-Setup-and-Script-Usage) + + +## Setup +To use, add printc to the plugins array inside your `~/.zshrc` file: +``` +plugins=(... printc) +``` +## Configuration + +### Requirements +Your terminal emulator must support 256 color. If you want to leverage italic text, +depending on your terminal emulator you will likely need to add support for displaying +italic text. The process is very simple, and I'll include instruction on how to do so. As +long as your terminal emulator supports, and is set up for 256 color, which almost all are +now-a-days, you can use the color aspect of the plugin, even without the italic +functionality. + +At the least your TERM environment variable must be set as so: +``` +export TERM=xterm-256color +``` + +It is possible that this is all that will be needed for the italic functionality to work +as well. I do reccomend trying and seeing if italics work. It it does not, just follow the +simple steps below. + +### Italics Setup + 1) Create a directory `~/.terminfo` + + 2) Create a file inside `~/.terminfo` called `xterm-256color-italics.terminfo` + + 3) Place the follwing contents inside `xterm-256color-italics.terminfo` *exactly* as + they are shown: + + ``` + xterm-256color-italic|xterm with 256 colors and italic, + sitm=\E[3m, ritm=\E[23m, + use=xterm-256color, + ``` + + 4) Inside `~/.terminfo` run the command `tic xterm-256color-italics.terminfo` + + 5) Set your TERM environment variable as so: + ``` + export TERM=xterm-256color-italic + ``` + You can export TERM in your `~/.zshrc` or `~/.zshenv` or many other ways. If you're an + iTerm2 user you can do it through the GUI terminal emulator settings there. It doesn't + matter how you do it, as long as the TERM environment variable is set and exported to + one of the above mentioned values, most likely the latter if you want italics. + + As an aside, I have not tested this inside TMUX, but it should work there as long as the + environment is set up to properly handle color and italics. + +# Usage + +### Options + | Option | Function | + | :-----------------: | -------------- | + | -b | Bold | + | -u | Underline | + | -i | Italic | + | -C `color` | Specify built in color | + | -l | List built in colors | + | -n | No newline | + | -h | Display help page | + +### General Structure of Command + * `printc [-b] [-u] [-i] [-n] <0-255> <0-255> <0-255> "Colorized Text to Display"` + * This is the structure used when specifying a color with RGB values. + * Note the absense of quotes around the RGB numbers, this is required. + * Note the inclusion of quotes around the intended output, also required. + * As usual double quotes will allow parameter expansion. + * The RGB values must come after any options, and before the intended output. + * `printc [-b] [-u] [-i] [-n]> -C "Colorized Text to Display"` + * This is the structure used when specifying a color that is built in to the plugin. + * Quoting the intended output is not required when using built in color options. + * Options can be given in any order, and chained together, such as + `-buinC `, so long as `built in color` follows immediately after `-C`, + and in the case of using RGB values, they must come after any options that are given. + +# Notes on Environment Setup and Script Usage + Immediately after setup, the `printc` command will be available to use + interactively, or inside aliases and functions. You can create nice colorized, formatted + text for your output. In order to be used inside ZSH scripts, you will need to make the + `printc` tool available outside of your current shell. One easy way to do this is to add + the following lines to your `~/.zshenv` file. + + ``` + fpath=($HOME/.oh-my-zsh/plugins/printc $fpath)' + ZSH=$HOME/.oh-my-zsh/' + ``` + The first line makes the plugin itself available to shells that are forked from your + interactive session, and the second line is an environment variable provided by OMZ, + which is referenced inside of the `printc` plugin, and therefore needs to be exposed to + children shells who want access to the tool. This can be done manually, or there is an + included script, called `setup.sh` which will set everything up automatically if ran. It + only needs to be ran once. + + And finally, any script that uses the `printc` command will have to include the line + `autoload -Uz printc` near the top. + + If you only want to use `printc` interactively, and/or inside functions and aliases, then + the above environment setup is not needed. + diff --git a/plugins/printc/_printc b/plugins/printc/_printc new file mode 100644 index 000000000..525cf845c --- /dev/null +++ b/plugins/printc/_printc @@ -0,0 +1,23 @@ +#compdef printc + +_printc() { + local -a all_opts + + all_opts=( + "-b[bold]" + "-i[italic]" + "-u[underline]" + "-l[list built in colors]" + "-h[show help message]" + "-C[built in colors]:custom:(cayenne \ + mocha asparagus fern clover moss teal \ + ocean midnight eggplant plum maroon maraschino \ + tangerine lemon lime spring seafoam turquois \ + aqua blueberry grape magenta strawberry salmon \ + cantaloupe banana honeydew flora spindrift ice \ + sky orchid lavender bubblegum carnation)" + ) + + _arguments -s "$all_opts[@]" +} + diff --git a/plugins/printc/printc b/plugins/printc/printc new file mode 100644 index 000000000..87a5eed78 --- /dev/null +++ b/plugins/printc/printc @@ -0,0 +1,3 @@ +# ~/.oh-my-zsh/custom/plugins/printc/printc + +zsh $ZSH/plugins/printc/printc_scpt $@ diff --git a/plugins/printc/printc.plugin.zsh b/plugins/printc/printc.plugin.zsh new file mode 100644 index 000000000..732216d61 --- /dev/null +++ b/plugins/printc/printc.plugin.zsh @@ -0,0 +1,10 @@ +# load included completion function into existing +# ~/.zcompdump-${SHORT_HOST}-${ZSH_VERSION} file +autoload -Uz _printc && compinit -d $ZSH_COMPDUMP + +# Wrapper function to call included printc script +function printc() { + zsh $ZSH/plugins/printc/printc_scpt $@ +} + + diff --git a/plugins/printc/printc_scpt b/plugins/printc/printc_scpt new file mode 100644 index 000000000..62ffa8da0 --- /dev/null +++ b/plugins/printc/printc_scpt @@ -0,0 +1,176 @@ +#!/bin/zsh -f + +emulate -L zsh + +usage() { + local yellow="\033[38;5;003m" + local green="\033[38;5;002m" + + print """${green}printc ${RS} v0.1 + +${yellow}USAGE:${RS} + printc [FLAGS/OPTIONS] [] ['string to print'] + +${yellow}FLAGS:${RS} + ${green}-b${RS} \033[1mbold${RS} + ${green}-i${RS} \033[3mitalic${RS} + ${green}-u${RS} \033[4munderline${RS} + ${green}-n${RS} do not add newline to the result${RS} + ${green}-l${RS} list built in colors${RS} + ${green}-h${RS} show this help message${RS} + +${yellow}OPTIONS:${RS} + ${green}-C ${RS} + +${yellow}ARGS:${RS} + ${green}${RS} Red Green Blue values from 0 - 255 for each + +${yellow}Note:${RS} + Either the -C OPTION or ARGS can be used, + but not both. The flags -b -i -u can be used in any combination/order + or omitted completely. -C and/or can be omitted and the color + will default to white, still observering the flags -b -i -u. Text to + be printed should be quoted. Use double quotes if you want to expand + variables inside your string, single quotes otherwise. + +${yellow}Examples:${RS} + printc -bu -C maroon 'Some Cool String' + + printc -i 120 200 50 'Some Cool String' + """ +} + +showall() { + local all_colors=() + for color_v in $@; do + all_colors+=($(zsh $THIS_PROG -b -C $color_v $color_v)) + done + print -C 3 $all_colors +} + +THIS_PROG=$0:A +UL= +BD= +IT= +RS="\033[0m" +BUILT_IN_COLOR= +USED_BUILTIN=0 + +typeset -A built_in_colors +built_in_colors=( + cayenne '148 017 000' + mocha '148 082 000' + asparagus '146 144 000' + fern '079 143 000' + clover '000 143 000' + moss '000 144 081' + teal '000 145 147' + ocean '000 084 147' + midnight '001 025 147' + eggplant '083 027 147' + plum '148 033 147' + maroon '148 023 081' + maraschino '255 038 000' + tangerine '255 147 000' + lemon '255 251 000' + lime '142 250 000' + spring '000 249 000' + seafoam '000 250 146' + turquois '000 253 255' + aqua '000 150 255' + blueberry '004 051 255' + grape '148 055 255' + magenta '255 064 255' + strawberry '255 047 146' + salmon '255 126 121' + cantaloupe '255 212 121' + banana '255 252 121' + honeydew '212 251 121' + flora '115 250 121' + spindrift '115 252 214' + ice '115 253 255' + sky '118 214 255' + orchid '122 129 255' + lavender '215 131 255' + bubblegum '255 133 255' + carnation '255 138 216' +) + +bad_color_input() { + local yellow="\033[38;5;003m" + print """ +${yellow}\033[1mInvalid Color${RS} + +\"$1\" is not a recognized color. + +Run \`printc -l\` to see all valid colors. + """ 1>&2 + exit 1 +} + +test_input() { + [[ ! -n ${built_in_colors[(ie)$1]} ]] && \ + bad_color_input $1 +} + +zparseopts -D - \ + C:=color_flag u=u_flag b=b_flag i=i_flag l=l_flag h=h_flag n=n_flag + +if [[ $l_flag ]] || [[ $h_flag ]];then + [[ $h_flag ]] && usage || \ + { + all_colors=( ${(k)built_in_colors} ) + showall $all_colors + } + exit 0 +elif [[ $color_flag ]] || [[ $u_flag ]] || \ + [[ $b_flag ]] || [[ $i_flag ]]; then + + if [[ $color_flag ]]; then + test_input $color_flag[2] + USED_BUILTIN=1 + BUILT_IN_COLOR=$built_in_colors[$color_flag[2]] + fi + if [[ $u_flag ]]; then + UL="\033[4m" # underline + fi + if [[ $b_flag ]]; then + BD="\033[1m" # bold + fi + if [[ $i_flag ]]; then + IT="\033[3m" # italic + fi +else + echo + echo "\033[1m\033[38;5;001mInvalid Option${RS}" + echo + usage + exit 1 +fi + +if [[ $USED_BUILTIN == 1 ]]; then + R=$BUILT_IN_COLOR[1,3] + G=$BUILT_IN_COLOR[5,7] + B=$BUILT_IN_COLOR[9,11] + MSG=$@ +else + if [[ $# == 4 ]]; then + R=$1 + G=$2 + B=$3 + MSG=$4 + elif [[ $# == 1 ]]; then + R=255 + G=255 + B=255 + MSG=$1 + else + usage + fi +fi + +if [[ $n_flag ]]; then + echo -n "${UL}${BD}${IT}\033[38;2;${R};${G};${B}m${MSG}${RS}" +else + echo "${UL}${BD}${IT}\033[38;2;${R};${G};${B}m${MSG}${RS}" +fi diff --git a/plugins/printc/setup.sh b/plugins/printc/setup.sh new file mode 100755 index 000000000..2faf26d9d --- /dev/null +++ b/plugins/printc/setup.sh @@ -0,0 +1,21 @@ +#!/bin/sh + +ZSHENV_FILE=$HOME/.zshenv + +write_to_zshenv() { + { + echo + echo '# ---Auto generated by printc plugin---' + echo 'fpath=($HOME/.oh-my-zsh/plugins/printc $fpath)' + echo 'ZSH=$HOME/.oh-my-zsh' + echo '# -------------------------------------' + echo + } >> "$ZSHENV_FILE" +} + +if [ -e "$ZSHENV_FILE" ]; then + write_to_zshenv +else + touch "$HOME/.zshenv" + write_to_zshenv +fi