Bashish Theme HOWTO
Thomas Eriksson
Version 1.0
Version 1.0
Index
1. About2. Prompt theming
2.1 Shell specific
characters
2.2 Helper libraries
3. Terminal theming2.2.1_bashish_prompt_cp437
2.2.2 _bashish_prompt_color
2.2.2 _bashish_prompt_color
4. Terminal manual
5. Examples (not written)
5.1 Bluesteel
5.2 Urbandawn
5.3 Box
5.2 Urbandawn
5.3 Box
About
This theme manual aims to describe the theme creating process for Bashish.As this manual incorporates parts from Wikipedia, Eterm technical reference, and the GNU Bash manual it is subject to the GNU Free Documentation License (GFDL).
Additionally this manual incorporates text from the "tcsh manual" and the "zsh manual" which are subject to the BSD and ZSH public licenses respecitively.
Comments and improvements are most welcome.
Prerequisits
Latest version of Bashish, availiable from http://bashish.sourceforge.netrxvt-unicode, kick-ass terminal emulator for theming:
http://software.schmorp.de/pkg/rxvt-unicode.html
The Eterm technical reference is a nicely formatted document almost vital for doing funky stuff with the terminal (even non-Eterm terminals): http://www.eterm.org/docs/view.php?doc=ref
Prompt theming
The prompt is an interesting part of the terminal. It's original purpose was to show the user that the system accepted input.Nowadays it can display all sorts of information, time, temperature, path, user, host etc.
Bash Prompt HOWTO differences
Giles Orr has written an extensive HOWTO on prompting in bash, see the Bash Prompt HOWTO.It has quite a few ideas and a general description of prompting, however, there are a few things that differ the Bash Prompt HOWTO and the way prompts are written in Bashish:
- Use of "tput" is discouraged since one can assume that themeable terminals are VT100 compatible.
- Calling external commands should be avoided if possible.
- prompt functions - if used - should be named "prompt", and called in the prompt.[SHELL] file.
Shell specific characters
Writing portable prompts requires some knowledges of the syntax of different shells.bash
Bash supports the following special characters in the promptBash allows these prompt strings to be customized by inserting a number of backslash-escaped
special characters that are decoded as follows:
\a an ASCII bell character (07)
\d the date in "Weekday Month Date" format (e.g., "Tue May 26")
\D{format}
the format is passed to strftime(3) and the result is inserted into the prompt
string; an empty format results in a locale-specific time representation. The
braces are required
\e an ASCII escape character (033)
\h the hostname up to the first ‘.’
\H the hostname
\j the number of jobs currently managed by the shell
\l the basename of the shell’s terminal device name
\n newline
\r carriage return
\s the name of the shell, the basename of $0 (the portion following the final
slash)
\t the current time in 24-hour HH:MM:SS format
\T the current time in 12-hour HH:MM:SS format
\@ the current time in 12-hour am/pm format
\A the current time in 24-hour HH:MM format
\u the username of the current user
\v the version of bash (e.g., 2.00)
\V the release of bash, version + patch level (e.g., 2.00.0)
\w the current working directory, with $HOME abbreviated with a tilde
\W the basename of the current working directory, with $HOME abbreviated with a
tilde
\! the history number of this command
\# the command number of this command
\$ if the effective UID is 0, a #, otherwise a $
\nnn the character corresponding to the octal number nnn
\\ a backslash
\[ begin a sequence of non-printing characters, which could be used to embed a
terminal control sequence into the prompt
\] end a sequence of non-printing characters
zsh
Special characters%% A ‘%’.
%) A ‘)’.
Login information
%l The line (tty) the user is logged in on, without ‘/dev/’ prefix. If the name starts
with ‘/dev/tty’, that prefix is stripped.
%M The full machine hostname.
%m The hostname up to the first ‘.’. An integer may follow the ‘%’ to specify how many
components of the hostname are desired. With a negative integer, trailing components
of the hostname are shown.
%n $USERNAME.
%y The line (tty) the user is logged in on, without ‘/dev/’ prefix. This does not treat
‘/dev/tty’ names specially.
Shell state
%# A ‘#’ if the shell is running with privileges, a ‘%’ if not. Equivalent to
‘%(!.#.%%)’. The definition of ‘privileged’, for these purposes, is that either the
effective user ID is zero, or, if POSIX.1e capabilities are supported, that at least
one capability is raised in either the Effective or Inheritable capability vectors.
%? The return code of the last command executed just before the prompt.
%_ The status of the parser, i.e. the shell constructs (like ‘if’ and ‘for’) that have
been started on the command line. If given an integer number that many strings will
be printed; zero or negative or no integer means print as many as there are. This is
most useful in prompts PS2 for continuation lines and PS4 for debugging with the
XTRACE option; in the latter case it will also work non-interactively.
%d
%/ Present working directory ($PWD). If an integer follows the ‘%’, it specifies a num‐
ber of trailing components of $PWD to show; zero means the whole path. A negative
integer specifies leading components, i.e. %-1d specifies the first component.
%~ As %d and %/, but if $PWD has a named directory as its prefix, that part is replaced
by a ‘~’ followed by the name of the directory. If it starts with $HOME, that part
is replaced by a ‘~’.
%h
%! Current history event number.
%i The line number currently being executed in the script, sourced file, or shell func‐
tion given by %N. This is most useful for debugging as part of $PS4.
%j The number of jobs.
%L The current value of $SHLVL.
%N The name of the script, sourced file, or shell function that zsh is currently execut‐
ing, whichever was started most recently. If there is none, this is equivalent to
the parameter $0. An integer may follow the ‘%’ to specify a number of trailing path
components to show; zero means the full path. A negative integer specifies leading
components.
%c
%.
%C Trailing component of $PWD. An integer may follow the ‘%’ to get more than one com‐
ponent. Unless ‘%C’ is used, tilde contraction is performed first. These are depre‐
cated as %c and %C are equivalent to %1~ and %1/, respectively, while explicit posi‐
tive integers have the same effect as for the latter two sequences.
Date and time
%D The date in yy-mm-dd format.
%T Current time of day, in 24-hour format.
%t
%@ Current time of day, in 12-hour, am/pm format.
%* Current time of day in 24-hour format, with seconds.
%w The date in day-dd format.
%W The date in mm/dd/yy format.
%D{string}
string is formatted using the strftime function. See strftime(3) for more details.
Three additional codes are available: %f prints the day of the month, like %e but
without any preceding space if the day is a single digit, and %K/%L correspond to
%k/%l for the hour of the day (24/12 hour clock) in the same way.
Visual effects
%B (%b)
Start (stop) boldface mode.
%E Clear to end of line.
%U (%u)
Start (stop) underline mode.
%S (%s)
Start (stop) standout mode.
%{...%}
Include a string as a literal escape sequence. The string within the braces should
not change the cursor position. Brace pairs can nest.
Conditional substrings
%v The value of the first element of the psvar array parameter. Following the ‘%’ with
an integer gives that element of the array. Negative integers count from the end of
the array.
%(x.true-text.false-text)
Specifies a ternary expression. The character following the x is arbitrary; the same
character is used to separate the text for the ‘true’ result from that for the
‘false’ result. This separator may not appear in the true-text, except as part of a
%-escape sequence. A ‘)’ may appear in the false-text as ‘%)’. true-text and
false-text may both contain arbitrarily-nested escape sequences, including further
ternary expressions.
The left parenthesis may be preceded or followed by a positive integer n, which
defaults to zero. A negative integer will be multiplied by -1. The test character x may be any of the following:
! True if the shell is running with privileges.
# True if the effective uid of the current process is n.
? True if the exit status of the last command was n.
_ True if at least n shell constructs were started.
C
/ True if the current absolute path has at least n elements relative to the root
directory, hence / is counted as 0 elements.
c
.
~ True if the current path, with prefix replacement, has at least n elements
relative to the root directory, hence / is counted as 0 elements.
D True if the month is equal to n (January = 0).
d True if the day of the month is equal to n.
g True if the effective gid of the current process is n.
j True if the number of jobs is at least n.
L True if the SHLVL parameter is at least n.
l True if at least n characters have already been printed on the current line.
S True if the SECONDS parameter is at least n.
T True if the time in hours is equal to n.
t True if the time in minutes is equal to n.
v True if the array psvar has at least n elements.
w True if the day of the week is equal to n (Sunday = 0).
%<string<
%>string>
%[xstring]
Specifies truncation behaviour for the remainder of the prompt string. The third,
deprecated, form is equivalent to ‘%xstringx’, i.e. x may be ‘<’ or ‘>’. The numeric
argument, which in the third form may appear immediately after the ‘[’, specifies the
maximum permitted length of the various strings that can be displayed in the prompt.
The string will be displayed in place of the truncated portion of any string; note
this does not undergo prompt expansion.
The forms with ‘<’ truncate at the left of the string, and the forms with ‘>’ trun‐
cate at the right of the string. For example, if the current directory is
‘/home/pike’, the prompt ‘%8<..<%/’ will expand to ‘..e/pike’. In this string, the
terminating character (‘<’, ‘>’ or ‘]’), or in fact any character, may be quoted by a
preceding ‘\’; note when using print -P, however, that this must be doubled as the
string is also subject to standard print processing, in addition to any backslashes
removed by a double quoted string: the worst case is therefore ‘print -P
"%<\\\\<<..."’.
If the string is longer than the specified truncation length, it will appear in full,
completely replacing the truncated string.
The part of the prompt string to be truncated runs to the end of the string, or to
the end of the next enclosing group of the ‘%(’ construct, or to the next truncation
encountered at the same grouping level (i.e. truncations inside a ‘%(’ are separate),
which ever comes first. In particular, a truncation with argument zero (e.g. ‘%<<’)
marks the end of the range of the string to be truncated while turning off truncation
from there on. For example, the prompt ’%10<...<%~%<<%# ’ will print a truncated rep‐
resentation of the current directory, followed by a ‘%’ or ‘#’, followed by a space.
Without the ‘%<<’, those two characters would be included in the string to be trun‐
cated.
tcsh
prompt The string which is printed before reading each command from the terminal. promptmay include any of the following formatting sequences (+), which are replaced by the
given information:
%/ The current working directory.
%~ The current working directory, but with one’s home directory represented by ‘~’
and other users’ home directories represented by ‘~user’ as per Filename substi‐
tution. ‘~user’ substitution happens only if the shell has already used ‘~user’
in a pathname in the current session.
%c[[0]n], %.[[0]n]
The trailing component of the current working directory, or n trailing compo‐
nents if a digit n is given. If n begins with ‘0’, the number of skipped compo‐
nents precede the trailing component(s) in the format ‘/<skipped>trailing’. If
the ellipsis shell variable is set, skipped components are represented by an
ellipsis so the whole becomes ‘...trailing’. ‘~’ substitution is done as in
‘%~’ above, but the ‘~’ component is ignored when counting trailing components.
%C Like %c, but without ‘~’ substitution.
%h, %!, !
The current history event number.
%M The full hostname.
%m The hostname up to the first ‘.’.
%S (%s)
Start (stop) standout mode.
%B (%b)
Start (stop) boldfacing mode.
%U (%u)
Start (stop) underline mode.
%t, %@
The time of day in 12-hour AM/PM format.
%T Like ‘%t’, but in 24-hour format (but see the ampm shell variable).
%p The ‘precise’ time of day in 12-hour AM/PM format, with seconds.
%P Like ‘%p’, but in 24-hour format (but see the ampm shell variable).
\c c is parsed as in bindkey.
^c c is parsed as in bindkey.
%% A single ‘%’.
%n The user name.
%j The number of jobs.
%d The weekday in ‘Day’ format. %D The day in ‘dd’ format.
%w The month in ‘Mon’ format.
%W The month in ‘mm’ format.
%y The year in ‘yy’ format.
%Y The year in ‘yyyy’ format.
%l The shell’s tty.
%L Clears from the end of the prompt to end of the display or the end of the line.
%$ Expands the shell or environment variable name immediately after the ‘$’.
%# ‘>’ (or the first character of the promptchars shell variable) for normal users,
‘#’ (or the second character of promptchars) for the superuser.
%{string%}
Includes string as a literal escape sequence. It should be used only to change
terminal attributes and should not move the cursor location. This cannot be the
last sequence in prompt.
%? The return code of the command executed just before the prompt.
%R In prompt2, the status of the parser. In prompt3, the corrected string. In
history, the history string.
‘%B’, ‘%S’, ‘%U’ and ‘%{string%}’ are available in only eight-bit-clean shells; see
the version shell variable.
The bold, standout and underline sequences are often used to distinguish a superuser
shell. For example,
> set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
tut [37] [2:54pm] [/usr/accts/sys] you rang? _
If ‘%t’, ‘%@’, ‘%T’, ‘%p’, or ‘%P’ is used, and noding is not set, then print
‘DING!’ on the change of hour (i.e, ‘:00’ minutes) instead of the actual time.
Set by default to ‘%# ’ in interactive shells.
prompt2 (+)
The string with which to prompt in while and foreach loops and after lines ending in
‘\’. The same format sequences may be used as in prompt (q.v.); note the variable
meaning of ‘%R’. Set by default to ‘%R? ’ in interactive shells.
prompt3 (+)
The string with which to prompt when confirming automatic spelling correction. The
same format sequences may be used as in prompt (q.v.); note the variable meaning of
‘%R’. Set by default to ‘CORRECT>%R (y|n|e|a)? ’ in interactive shells.
promptchars (+)
If set (to a two-character string), the ‘%#’ formatting sequence in the prompt shell
variable is replaced with the first character for normal users and the second char‐
acter for the superuser.
csh
"prompt" is the string that is printed before eachcommand is read from an interactive
terminal input. If a ‘!’ appears in
the string it will be replaced by the
current event number unless a preced‐
ing ‘\’ is given. Default is “%”, or
“#” for the superuser.
ksh
PS1 The value of this variable is expanded for parameter expansion, command sub‐stitution, and arithmetic substitution to define the primary prompt string
which by default is ‘‘$’’. The character ! in the primary prompt string is
replaced by the command number (see Command Re-entry below). Two successive
occurrences of ! will produce a single ! when the prompt string is printed.
PS2 Secondary prompt string, by default ‘‘> ’’.
PS3 Selection prompt string used within a select loop, by default ‘‘#? ’’.
PS4 The value of this variable is expanded for parameter evaluation, command sub‐
stitution, and arithmetic substitution and precedes each line of an execution
trace. By default, PS4 is ‘‘+ ’’. In addition when PS4 is unset, the execu‐
tion trace prompt is also ‘‘+ ’’.
sh
rc
Theme function
In the BashPrompt Howto functions are used extensively, this is a good thing since variabels can be declared local.Where Bashish differs from BashPrompt is that it does not expect to run the function contained within the prompt.[shell] file. Thus if writing a function, one must remember to execute that function too :)
An example:
function myprompt {
typeset LOCAL_VARIABEL=human
PS1="hello $LOCAL_VARIABEL>"The prompt will look like this:
unset -f myprompt
}
myprompt
hello human>LOCAL_VARIABEL is declared as local by the "typeset" definition.
This function will work on bash, ksh93, pdksh and zsh.
Other shells are out of scope for this simple howto.
Helper libraries
Helper libraries are shared code which can be used among all shells.These are called directly from the shell with a specified set of arguments. On "bash", "zsh", "ksh93" and "pdksh", these helpers loads as functions for performance reasons.
Helper libraries:
- _bashish_prompt_fillx - fills the terminal in horizontal row by repeating a specified string.
- _bashish_prompt_filly - fills the terminal in vertical column up to the cursor with a specified string.
- _bashish_prompt_cwd - prints the string, color / escape codes can be put between each directory delimiter.
- _bashish_prompt_color - converts a simple human readable syntax to ansi color codes.
- _bashish_prompt_testloc - forces the prompt to stay above a certain row.
- _bashish_prompt_cp437 - prints characters in the old Codepage 437 DOS charset, either as CP437 or as UTF-8.
_bashish_prompt_cp437
In ASCII art, often the DOS codepage is used to create semi-graphical text.The DOS codepage (named Code page 437, CP437 or OEM) is today however completely obsolete, and due to technical difficulties it might be problematic to use these characters in terminals with more recent encodings.
However the 2.0.6 release of Bashish includes a compatibility library - _bashish_prompt_cp437 - where one give the hexadecimal character (in uppercase) of codepage 437 and _bashish_prompt_cp437 either prints a CP437 or UTF-8 encoded character. This method makes nearly all terminals able to display ASCII-art written in the DOS CP437 charset.
Here is a table taken from http://en.wikipedia.org/wiki/Code_page_437
| .0 | .1 | .2 | .3 | .4 | .5 | .6 | .7 | .8 | .9 | .A | .B | .C | .D | .E | .F | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0. |
NULL 0 |
☺ 263A |
☻ 263B |
♥ 2665 |
♦ 2666 |
♣ 2663 |
♠ 2660 |
• 2022 |
◘ 25D8 |
○ 25CB |
◙ 25D9 |
♂ 2642 |
♀ 2640 |
♪ 266A |
♫ 266B |
☼ 263C |
| 1. |
► 25BA |
◄ 25C4 |
↕ 2195 |
‼ 203C |
¶ B6 |
§ A7 |
▬ 25AC |
↨ 21A8 |
↑ 2191 |
↓ 2193 |
→ 2192 |
← 2190 |
∟ 221F |
↔ 2194 |
▲ 25B2 |
▼ 25BC |
| 2. |
20 |
! 21 |
" 22 |
# 23 |
$ 24 |
% 25 |
& 26 |
' 27 |
( 28 |
) 29 |
* 2A |
+ 2B |
, 2C |
- 2D |
. 2E |
/ 2F |
| 3. |
0 30 |
1 31 |
2 32 |
3 33 |
4 34 |
5 35 |
6 36 |
7 37 |
8 38 |
9 39 |
: 3A |
; 3B |
< 3C |
= 3D |
> 3E |
? 3F |
| 4. |
@ 40 |
A 41 |
B 42 |
C 43 |
D 44 |
E 45 |
F 46 |
G 47 |
H 48 |
I 49 |
J 4A |
K 4B |
L 4C |
M 4D |
N 4E |
O 4F |
| 5. |
P 50 |
Q 51 |
R 52 |
S 53 |
T 54 |
U 55 |
V 56 |
W 57 |
X 58 |
Y 59 |
Z 5A |
[ 5B |
\ 5C |
] 5D |
^ 5E |
_ 5F |
| 6. |
` 60 |
a 61 |
b 62 |
c 63 |
d 64 |
e 65 |
f 66 |
g 67 |
h 68 |
i 69 |
j 6A |
k 6B |
l 6C |
m 6D |
n 6E |
o 6F |
| 7. |
p 70 |
q 71 |
r 72 |
s 73 |
t 74 |
u 75 |
v 76 |
w 77 |
x 78 |
y 79 |
z 7A |
{ 7B |
| 7C |
} 7D |
~ 7E |
⌂ 2302 |
| 8. |
Ç C7 |
ü FC |
é E9 |
â E2 |
ä E4 |
à E0 |
å E5 |
ç E7 |
ê EA |
ë EB |
è E8 |
ï EF |
î EE |
ì EC |
Ä C4 |
Å C5 |
| 9. |
É C9 |
æ E6 |
Æ C6 |
ô F4 |
ö F6 |
ò F2 |
û FB |
ù F9 |
ÿ FF |
Ö D6 |
Ü DC |
¢ A2 |
£ A3 |
¥ A5 |
₧ 20A7 |
ƒ 192 |
| A. |
á E1 |
í ED |
ó F3 |
ú FA |
ñ F1 |
Ñ D1 |
ª AA |
º BA |
¿ BF |
⌐ 2310 |
¬ AC |
½ BD |
¼ BC |
¡ A1 |
« AB |
» BB |
| B. |
░ 2591 |
▒ 2592 |
▓ 2593 |
│ 2502 |
┤ 2524 |
╡ 2561 |
╢ 2562 |
╖ 2556 |
╕ 2555 |
╣ 2563 |
║ 2551 |
╗ 2557 |
╝ 255D |
╜ 255C |
╛ 255B |
┐ 2510 |
| C. |
└ 2514 |
┴ 2534 |
┬ 252C |
├ 251C |
─ 2500 |
┼ 253C |
╞ 255E |
╟ 255F |
╚ 255A |
╔ 2554 |
╩ 2569 |
╦ 2566 |
╠ 2560 |
═ 2550 |
╬ 256C |
╧ 2567 |
| D. |
╨ 2568 |
╤ 2564 |
╥ 2565 |
╙ 2559 |
╘ 2558 |
╒ 2552 |
╓ 2553 |
╫ 256B |
╪ 256A |
┘ 2518 |
┌ 250C |
█ 2588 |
▄ 2584 |
▌ 258C |
▐ 2590 |
▀ 2580 |
| E. |
α 3B1 |
ß DF |
Γ 393 |
π 3C0 |
Σ 3A3 |
σ 3C3 |
µ B5 |
τ 3C4 |
Φ 3A6 |
Θ 398 |
Ω 3A9 |
δ 3B4 |
∞ 221E |
φ 3C6 |
ε 3B5 |
∩ 2229 |
| F. |
≡ 2261 |
± B1 |
≥ 2265 |
≤ 2264 |
⌠ 2320 |
⌡ 2321 |
÷ F7 |
≈ 2248 |
° B0 |
∙ 2219 |
· B7 |
√ 221A |
ⁿ 207F |
² B2 |
■ 25A0 |
A0 |
You get the hex value by combining the character in the left column with the character in the top column, excluding the dots.
_bashish_prompt_cp437 accepts multiple space delimited arguments, the outputted string will not have any spaces in it (except if you give it 20 as argument that is ;))
Usage example:
FADE="$( _bashish_prompt_cp437 B0 B1 B2)"sets the variabel $FADE to ░▒▓
Another example:
SUN="$(_bashish_prompt_cp437 0F)"
sets
the variabel $SUN to ☼_bashish_prompt_color
ANSI colors are available for most modern terminal emulators.On unsupported terminals _bashish_prompt_color does not output escape sequencies which would otherwise be printed.
The RGB values may be changed, see COLOR in the terminal theming section below.
However, by doing so, the theme may render unusuable on terminals which do not support changing the RGB values, eg "putty".
If you use the predefined colors, your theme will look roughly the same on nearly all terminal emualtors.
_bashish_prompt_color is a helper library which translate the colors specified to ansi codes each terminal can understand.
| Color | Num | Foreground | Background | Notes |
| 0 | fgblack | bgblack | (1) | |
| 1 | fgred | bgred | ||
| 2 | fggreen | bggreen | ||
| 3 | fgyellow | bgyellow | ||
| 4 | fgblue | bgblue | ||
| 5 | fgmagenta | bgmagenta | ||
| 6 | fgcyan | bgcyan | ||
| 7 | fgwhite | bgwhite | (1) | |
| 8 | fgbrightblack | bgbrightblack | (2)(3) | |
| 9 | fgbrightred | bgbrightred | (2)(3) | |
| 10 | fgbrightgreen | bgbrightgreen | (2)(3) | |
| 11 | fgbrightyellow | bgbrightyellow | (2)(3) | |
| 12 | fgbrightblue | bgbrightblue | (2)(3) | |
| 13 | fgbrightmagenta | bgbrightmagenta | (2)(3) | |
| 14 | fgbrightcyan | bgbrightcyan | (2)(3) | |
| 15 | fgbrightwhite | bgbrightwhite | (2)(3) |
1: Linux console cannot change colors for fgwhite, bgwhite, fgblack, bgblack, these are set to original background respectively foreground colors.
2: bgbright* is only available on XTerm and rxvt-unicode. On other terminals, the foreground enables "bold" attribute to simulate the bright colors.
_bashish_prompt_cwd
A subtle, yet elegant and usability enhancing feature.The _bashish_prompt_cwd library takes three arguments:
first is a escape sequence to print before each directory delimiter
second is the escape sequence to print before each directory name
third is the cutoff, $COLUMNS - cutoff
_bashish_prompt_testloc
The CSR (cursor scrolling region) sequence can be useful when prompting.In the "c64" theme, it is used as emulating the borders of the Commodore 64 - unfortually, setting the top region as non-scrollable kills the scrollback buffer - the C64 theme is not aimed to be useful however :)
_bashish_prompt_filly
Filly fills the terminal from the bottom up to the cursor with a specified string for each line.This gives a warm fuzzy feeling when the prompt can be moved around on the screen :)
Filly calls _bashish_prompt_testloc since it needs to know where the prompt is located on the screen, it is thus not recommended to also run testloc in a prompt.
_bashish_prompt_fillx
Fillx fills a row in the terminal with a repeated string. The user may specify a cutoff of n characters.Terminal theming
Customizing
To describe how to configure the apperance of Bashish one must be vaugely familiar with how Bashish themes the terminal.Bashish repaints the terminal at different times:
- at terminal startup
- when a themed application launches
- when a themed application ends
- when suspending a themed application
- $HOME/.bashish/bt/defaults/theme
- $HOME/.bashish/bt/prompt/theme
- $HOME/.bashish/bt/overrides/theme
- a themed application launches
- a suspended themed application restarts
- $HOME/.bashish/bt/defaults/theme
- $HOME/.bashish/bt/prompt/theme
- $HOME/.bashish/bt/app/[APPNAME]/theme
- $HOME/.bashish/bt/overrides/theme
defaults/theme sets the default values for Bashish, these are the variables that will be in use if the theme nor the override/theme overrides them.
prompt/theme is the loaded prompt for Bashish, this theme is chosen by running the 'bashishtheme' command.
overrides/theme overrides the values set by defaults/theme, prompt/theme and app/[APPNAME]/theme
All 'theme' files are valid ksh scripts, thus features as arrays and conditionals are supported.
Variable reference
Definitions
Each section of the variable reference consists of a titel and a description.the titel have two fields, the first which is always uppercase is the name of the variable:
VARIABLE
VARIABLE[]
if the variable have a pair of brackets at the end, it is an array.
a normal variable is defined on it's own line as following:
variable="this is a string"
each element is defined by the variable name and the index:
VARIABLE[0]="this is the first element"
VARIABLE[1]="this is the second element"
VARIABLE[1023]="yay, the 1024th element"
elements do not need to be defined in any order, though for readability it is recommended to define them in ascending order.
Do not go further than index 1023, if you do, you might be eaten by a grue (at least when using pdksh).
If a variable is defined, it can be undefined by running
unset VARIABLE
an array can be undefined by running
unset VARIABLE[*]
(note: that trying to undefine a variable as an array may give an error)
If a variable is unset, it's value will default to "" - null.
Datatypes
The second word in the title is the datatype.The datatypes defined in this document are one of the following:
(bool)
(int)
(string)
(string:hexcolor)
(string:file)
Note that Bashish do not validate input for correctness, thus, giving an erronous datatype might in rare cases produce an error, but more oftenly it will only fail silently for that particular theming part.
(bool) is a numerical yesno value, where 0=no and 1=yes
eg.
VARIABLE=0 ## false
VARIABLE=1 ## true
(int) is an integer, eg.
VARIABLE=1234 ## the numerical value of 1234
(string) is a text string of a specified format
(string:hexcolor) is a '#' followed by a hex triplet of red green and blue, eg:
VARIABLE="#ff00cc" ## purple
VARIABLE="#000000" ## black
VARIABLE="#007700" ## dark green
(string:file) is a filename relative to one of the Bashish theme directories which are one of $HOME/.bashish/bt/defaults/ $HOME/.bashish/bt/prompt/ $HOME/.bashish/bt/overrides/ or $HOME/.bashish/bt/app/[APPNAME]/
do note that filenames can be overridden or set to defaults by placing a similary named file in either the defaults or overrides directories.
eg:
VARIABLE=file.png ## points to file.png
Title and icon
TITLE (string)
This text string is visible in the window title of the terminal (at consoles a bar at the top of the terminal containing the text will appear). see below for format.
ICON (string)
This text string is shown at the minimized icon in X. if unset it will default to the TITLE string. Note. Some windowmanagers does not show the icontext.
Font
FONTNAME[] (string)
The first element of FONTNAME is an XFT font in the XFT font cache.This variable is supported on gnome-terminal and rxvt-unicode.
Furthermore, on rxvt-unicode, it's possible to specify several fonts.
FONTSIZE[] (int)
FONTSIZE_BOLD[] (int)
FONTSIZE_ITALIC[] (int)
FONTNAME_BOLD[] (string)
FONTNAME_ITALIC[] (string)
XFONT[] (string)
XFONT_BOLD[] (string)
XFONT_ITALIC[] (string)
A string describing an exported font given by the X-server. (note. xfontsel can be used to preview the avaliable fonts)
SIZE_X (int)
Horizontal size in number of character rows (positive integer)
SIZE_Y (int)
Vertical size in number of character lines (positive integer).
POSITION_X (int)
Horizontal integer position of the terminal window in pixels (including window borders).
This theme property will come in effect when a theme is initialized or for individual applications.
POSITION_Y (int)
Vertical integer position of the terminal window in pixels (including window borders)
This theme property will come in effect when a theme is initialized or for individual applications.
ICONIFY (bool)
if ICONIFY is set to 1, the terminal will be iconified. if ICONIFY is unset or set to any other value the terminal will be deiconified.
BGCOLOR (string:hexcolor)
background color the format for these color values are rgb color in hexadecimal. eg. #4f55aa
FGCOLOR (string:hexcolor)
foreground color the format for these color values are rgb color in hexadecimal. eg. #4f55aa
COLOR[] (string:hexcolor)
These are the ANSI color values seen in the console eg. by the output of (GNU) ls --color=auto, or by ncurses text programs.
For most terminals, the array elements 0-15 can be used.
- XTerm supports 0-255 color elements.
- The linux console only support elements 1-6 and 8-15, the ignored elements are black and white which in the linux console implementation corresponds to foreground and background.
BGMOUSECOLOR FGMOUSECOLOR (string:hexcolor)
changes color of the mouse cursor.
BOLDCOLOR (string:hexcolor)
changes highlighted color the format for this color value is rgb color in hexadecimal. eg. #4f55aa
UNDERLINECOLOR (string:hexcolor)
changes underlined text color the format for this color value is rgb color in hexadecimal. eg. #4f55aa
BGTRANSPARENCY (string:hexcolor)
"1" to enable or "0" to disable. Enables terminal transperancy. BGVIEWPORT "1" to enable or "0" to disable. This must be set in conjugation with IMAGEFILE
BGVIEWPORT (string:hexcolor)
From the Eterm man page: "
This activates a special Eterm mode which is hard to describe in words. Basically, imagine the effect you get with pseudo-transparency, where the desktop background moves through the Eterm window as you move the window, so that it always aligns with the desktop image. Now, imagine the same effect, but the image used isn't the desktop image but any pixmap you choose. The image is scaled or tiled up to the size of the desktop, and dragging the Eterm around the screen reveals different portions of the image as you move, much like a small viewport window in a ship or submarine does. The effect is especially keen if you open several Eterms in this mode with the same image."
Eterm only.
Variables for images
The following variables are only supported on rxvt and Eterm.
IMAGEFILE (string:file)
Takes a filename without directory structure. Note that rxvt's only supports XPM files, hence this format is recommended.
IMAGELOGO (string:file)
same as the above, but is only shown at startup for a number of seconds specified by the IMAGELOGOWAIT variable
IMAGELOGOWAIT (int)
how many (integer) seconds to show the image in IMAGELOGO
IMAGESCALE (string)
the image scale value as avaliable from the Eterm manual (applies to rxvt and aterm and wterm too) IMAGESCALE may be omitted.
Many "scaling strings" may be given and separated by semicolons (;). String Function Adjusting scaling and position
Adjusting position only
Adjusting scale only
Pixmap Operations
(note: on rxvt all images is tiled automaticly, unpropornally, there is no way of turning this behaviour off)
IMAGELOGOSCALE (string)
same as above, but applies to graphical startup logos
EICON (string:file)
Takes a filename without directory structure. An image that is shown as the icon for Eterm. image formats: jpg/gif/png Note. It's recommended to use an icon similar to the window manager icon size(eg a 16x16 for kwm and a 64x64 for windowmaker)
DTICON (string)
Takes a filename without directory structure. only CDE image pixmaps are supported, ".pm", ImageMagick and xv are able to convert those. An image that is sho
ASCII art and startup messages
WELCOMEMESSAGE (string)
a welcome text that will be shown each time the terminal is loaded.
LOGO (string:file)
An ascii logo that will be 'cat':ed in the console bashish is started. Takes a filename without directory structure.
Theme information
the following variables are shown when "changetheme" w/o arguments is issued. They are only meta variables and has no effect on the terminal layout.
THEME_NAME (string)
name of the theme (if unset the $THEME value will be shown)
THEME_AUTHOR (string)
author of the theme
THEME_COMMENT (string)
any comment about the theme can be in here.
THEME_URL (string)
where the newest version of the theme can be found, or the authors homepage.
THEME_VERSION (string)
version of the theme
THEME_MADEWITH (string)
in which program this theme were made
Terminal Technical Reference
Following is the Eterm technical reference with Eterm specifics cut out, only covering sequencies which can be considered safe on vt100 and xterm compatible terminals.For information on more specific terminal sequencies, it is recommended to read the terminal documentation.
Table of Contents
Document Conventions
| Convention | Meaning |
| c | A literal. It should be typed as shown. |
| SYM | A symbol. Replace with the proper character. See the symbol table below for a listing of the symbols used and their meanings. |
| text | A parameter. Replace the italicized text with a parameter. The text itself generally describes the type of parameter needed. |
| [ ... ] | Items enclosed in brackets are optional. |
| { ... | ... } | Items inclosed in braces and separated by pipes indicate that exactly one of the items should be chosen. |
Symbols
| Symbol | Meaning |
| BEL | Bell (Ctrl-G) |
| BS | Backspace (Ctrl-H) |
| CR | Carriage Return (Ctrl-M) |
| ENQ | Enquiry (Ctrl-E), Send Device Attributes (DA). Eterm ignores ENQ if NO_ENQ_ANS is defined, which it is by default in src/feature.h. |
| ESC | Escape (Ctrl-[) |
| FF or NP | Form Feed or New Page(Ctrl-L) |
| LF or NL | Line Feed or New Line (Ctrl-J) |
| SO | Shift Out (Ctrl-N), invokes the G1 (alternate) character set |
| SI | Shift In (Ctrl-O), invokes the G0 (default) character set |
| SPC | Space |
| TAB or HT | Horizontal Tab (Ctrl-I) |
| VT | Vertical Tab (Ctrl-K) |
Escape Sequences
| Sequence | Function |
| ESC { ( | ) | * | + | $ } { 0 | A | B } | Select ISO 2022 character sets.
|
| ESC 7 | Save cursor (SC) |
| ESC 8 | Restore cursor (RC) |
| ESC = | Application Keypad (SMKX) |
| ESC > | Numeric Keypad (RMKX) |
| ESC @ | Discards the subsequent character |
| ESC D | Index (IND) |
| ESC E | Next Line (NEL) |
| ESC G | Graphics (an rxvt extension). Eterm replies to ESC G Q (query graphics) with ESC G 0 (no graphics available) and ignores all other graphics sequences. |
| ESC H | Tab Set (HTS) |
| ESC M | Reverse Index (RI) |
| ESC Z | Obselete form of Send Device Attributes (DA), which is ESC [ c |
| ESC [ [ n ] @ | Insert n blank Characters (ICH). Default for n is 1. |
| ESC [ [ n ] A | Cursor Up n times (CUU), default 1 |
| ESC [ [ n ] B | Cursor Down n times (CUD), default 1 |
| ESC [ [ n ] C | Cursor Forward n times (CUF), default 1 |
| ESC [ [ n ] D | Cursor Backward n times (CUB), default 1 |
| ESC [ [ n ] E | Cursor Down n times and to first column, default 1 |
| ESC [ [ n ] F | Cursor Up n times and to first column, default 1 |
| ESC [ [ n ] G | Cursor to Column n (HPA) |
| ESC [ [ r ; c ] H | Cursor Position [row;column] (CUP), default 1;1 |
| ESC [ [ n ] I | Move forward n tab stops, default 1 |
| ESC [ [ n ] J | Erase in Display (ED)
|
| ESC [ [ n ] K | Erase in Line (EL)
|
| ESC [ [ n ] L | Insert n lines (IL), default 1 |
| ESC [ [ n ] M | Delete n lines (DL), default 1 |
| ESC [ [ n ] P | Delete n characters (DCH), default 1 |
| ESC [ [ n ] W | Tabulator functions
|
| ESC [ [ n ] X | Erase n characters (ECH), default 1 |
| ESC [ [ n ] Z | Move backward n tabstops, default 1 |
| ESC [ [ n ] ` | Same as ESC [ n G (HPA) |
| ESC [ [ n ] a | Same as ESC [ n C (CUF) |
| ESC [ [ n ] c | Send Device Attributes (DA), default of 0 returns "ESC[?1;2c" indicating a VT100 with advanced video option |
| ESC [ [ n ] d | Cursor to line n (VPA) |
| ESC [ [ n ] e | Same as ESC [ n A (CUU) |
| ESC [ [ r ; c ] f | Horizontal and Vertical Position (HVP), default 1;1 |
| ESC [ [ n ] g | Tab Clear
|
| ESC [ [ n ] i | Printing
|
| ESC [ n [ ; n ... ] { h | l } |
|
| ESC [ n [ ; n ... ] m | Character Attributes (SGR)
|
| ESC [ [ n ] n | Device Status Report (DSR)
|
| ESC [ [ t ; b ] r | Set Scrolling Region (CSR), where t is the top row and b is the bottom row, defaults to the full screen |
| ESC [ ? n [ ; n ... ] { h | l | s | r | t } | DEC Private Modes (shown as set/reset)
|
| ESC ] n ; string BEL | Set X Terminal Parameters
|
| ESC c | Full Reset (RIS) |
| ESC n | Invoke the G2 character set (LS2) |
| ESC o | Invoke the G3 character set (LS3) |
Known Escape Codes
| Escaped String | Meaning |
| Backslash-Escaped Characters (case is ignored) | |
| \a | BEL (Alert) |
| \b | BS |
| \cX | Interpreted as Ctrl-X. Analogous to ^X. |
| \e | ESC |
| \f | FF |
| \n | LF |
| \r | CR |
| \t | TAB |
| \v | VT |
| \nnn | nnn is interpreted as an octal number, and the corresponding character is inserted. |
| Convenience Shortcuts | |
| ^X | Interpreted as Ctrl-X. X can be any character between @ and _. Case is ignored. |
| C-X | Interpreted as Ctrl-X. Analogous to ^X. |
| M-X | Interpreted as ESC followed by X. Analogous to \eX. If the string begins with M-, a CR is automatically appended to the end of the string if not already present. |
Key Sequences
| Cursor Keys | ||||
| Key Pressed | What Eterm Sends | |||
| Normal | Shift | Control | Application | |
| Up | ESC [ A | ESC [ a | ESC O a | ESC O A |
| Down | ESC [ B | ESC [ b | ESC O b | ESC O B |
| Right | ESC [ C | ESC [ c | ESC O c | ESC O C |
| Left | ESC [ D | ESC [ d | ESC O d | ESC O D |
| Special Keys | ||||
| Key Pressed | Normal | Shift | Control | Control+Shift |
| Tab | ^I | ESC [ Z | ^I | |
| Backspace | ^H | ^? | ^? | |
| Home (Find) | ESC [ 1 ~ | ESC [ 1 $ | ESC [ 1 ^ | ESC [ 1 @ |
| End (Select) | ESC [ 4 ~ | ESC [ 4 $ | ESC [ 4 ^ | ESC [ 4 @ |
| Insert | ESC [ 2 ~ | Paste mouse selection | ESC [ 2 ^ | ESC [ 2 @ |
| Delete (Execute) | ESC [ 3 ~ | ESC [ 3 $ | ESC [ 3 ^ | ESC [ 3 @ |
| PageUp (Prior) | ESC [ 5 ~ | Scroll up one page | ESC [ 5 ^ | ESC [ 5 @ |
| PageDown (Next) | ESC [ 6 ~ | Scroll down one page | ESC [ 6 ^ | ESC [ 6 @ |
| Function Keys (Note: Shift-F1 through F10 sends F11-F20) | ||||
| Key Pressed | Normal | Shift | Control | Control+Shift |
| F1 | ESC [ 11 ~ | ESC [ 23 ~ | ESC [ 11 ^ | ESC [ 23 ^ |
| F2 | ESC [ 12 ~ | ESC [ 24 ~ | ESC [ 12 ^ | ESC [ 24 ^ |
| F3 | ESC [ 13 ~ | ESC [ 25 ~ | ESC [ 13 ^ | ESC [ 25 ^ |
| F4 | ESC [ 14 ~ | ESC [ 26 ~ | ESC [ 14 ^ | ESC [ 26 ^ |
| F5 | ESC [ 15 ~ | ESC [ 28 ~ | ESC [ 15 ^ | ESC [ 28 ^ |
| F6 | ESC [ 17 ~ | ESC [ 29 ~ | ESC [ 17 ^ | ESC [ 29 ^ |
| F7 | ESC [ 18 ~ | ESC [ 31 ~ | ESC [ 18 ^ | ESC [ 31 ^ |
| F8 | ESC [ 19 ~ | ESC [ 32 ~ | ESC [ 19 ^ | ESC [ 32 ^ |
| F9 | ESC [ 20 ~ | ESC [ 33 ~ | ESC [ 20 ^ | ESC [ 33 ^ |
| F10 | ESC [ 21 ~ | ESC [ 34 ~ | ESC [ 21 ^ | ESC [ 34 ^ |
| F11 | ESC [ 23 ~ | ESC [ 23 $ | ESC [ 23 ^ | ESC [ 23 @ |
| F12 | ESC [ 24 ~ | ESC [ 24 $ | ESC [ 24 ^ | ESC [ 24 @ |
| F13 | ESC [ 25 ~ | ESC [ 25 $ | ESC [ 25 ^ | ESC [ 25 @ |
| F14 | ESC [ 26 ~ | ESC [ 26 $ | ESC [ 26 ^ | ESC [ 26 @ |
| F15 (Help) | ESC [ 28 ~ | ESC [ 28 $ | ESC [ 28 ^ | ESC [ 28 @ |
| F16 (Menu) | ESC [ 29 ~ | ESC [ 29 $ | ESC [ 29 ^ | ESC [ 29 @ |
| F17 | ESC [ 31 ~ | ESC [ 31 $ | ESC [ 31 ^ | ESC [ 31 @ |
| F18 | ESC [ 32 ~ | ESC [ 32 $ | ESC [ 32 ^ | ESC [ 32 @ |
| F19 | ESC [ 33 ~ | ESC [ 33 $ | ESC [ 33 ^ | ESC [ 33 @ |
| F20 | ESC [ 34 ~ | ESC [ 34 $ | ESC [ 34 ^ | ESC [ 34 @ |
| Keypad | ||||
| Key Pressed | Normal | Application | ||
| KP_Enter | ^M | ESC O M | ||
| KP_F1 | ESC O P | ESC O P | ||
| KP_F2 | ESC O Q | ESC O Q | ||
| KP_F3 | ESC O R | ESC O R | ||
| KP_F4 | ESC O S | ESC O S | ||
| XK_KP_Multiply | * | ESC O j | ||
| XK_KP_Add | + | ESC O k | ||
| XK_KP_Separator | , | ESC O l | ||
| XK_KP_Subtract | - | ESC O m | ||
| XK_KP_Decimal | . | ESC O n | ||
| XK_KP_Divide | / | ESC O o | ||
| XK_KP_0 | 0 | ESC O p | ||
| XK_KP_1 | 1 | ESC O q | ||
| XK_KP_2 | 2 | ESC O r | ||
| XK_KP_3 | 3 | ESC O s | ||
| XK_KP_4 | 4 | ESC O t | ||
| XK_KP_5 | 5 | ESC O u | ||
| XK_KP_6 | 6 | ESC O v | ||
| XK_KP_7 | 7 | ESC O w | ||
| XK_KP_8 | 8 | ESC O x | ||
| XK_KP_9 | 9 | ESC O y | ||