1 unstable release
0.1.0 | Aug 29, 2023 |
---|
43KB
447 lines
Termal
Rust library for terminal features with ansi escape codes.
Currently the library contains the ansii codes, and a special macro works only for colors.
Example
With macro
use termal::*;
// you can use a special macro to inline the color codes, this will write
// italic text with yellow foreground and reset at the end.
printcln!("{'yellow italic}hello{'reset}");
// the macro also supports standard formatting
printcln!("{'yellow italic}{}{'reset}", "hello");
// you can also use short versions of the codes
printcln!("{'y i}{}{'_}", "hello");
// you can also use true colors with their hex codes
printcln!("{'#dd0 i}{}{'_}", "hello");
Without macro
// Move cursor to position column 5 on line 7 and write 'hello' in italic
// yellow
use termal::codes::*;
println!("{}{YELLOW_FG}{ITALIC}hello{RESET}", move_to!(5, 7));
The macros such as move_to!
can accept either literals or dynamic values.
Its main feature is that if you supply literals, it expands to a string
literal with the ansi code.
If you however supply dynamic values it expands to a format!
macro:
use termal::codes::*;
let a = move_to!(5, 7);
// expands to:
let a = "\x1b[5;7H";
let b = move_to!(2 + 3, 7);
// expands to:
let a = format!("\x1b[{};{}H", 2 + 3, 7);
Gradients
Youn can create gradients with the function termal::gradient
:
use termal::*;
// This will create foreground gradient from the rgb color `(250, 50, 170)`
// to the rgb color `(180, 50, 240)`
printcln!(
"{}{'_}",
gradient("BonnyAD9", gradient("BonnyAD9", (250, 50, 170), (180, 50, 240)))
)
Macro syntax
In there are now 3 macros: formatc
, printc
and printcln
. They are
equivalent to format
, print
and println
respectively.
In all of them the same sintax applies:
- braces starting with
'
are color formats (e.g.{'yellow}
) - other braces are interpreted by the macro
format
The color format can contain
- names with ascii letters (e.g.
yellow
) - hex colors (e.g.
#FF125C
)
the names and hex colors are separated by spaces
Hex colors
The hex colors may have either 1, 2, 3 or 6 digits. They are interpreted as follows:
- Single digit colors are interpreted as the digit repeated 6 times (e.g.
#B
is same as#BBBBBB
) - Two digit colors are interpreted as the two digits repeated 3 times (e.g.
#AB
is same as#ABABAB
) - Three digit colors are interpreted as each digit being repeated once (e.g.
#ABC
is same as#AABBCC
) - Six digit colors are interpreted as typical rgb value (that is
#RRGGBB
)
If you want to set the foreground color you just type the hex code (e.g.
#ABCDEF
), if you want to set the background color you immidietly follow the
hex color by uncerscore (_
) (e.g. #ABCDEF_
)
List of names
Most of the names have aliases (e.g. writing white
and w
is the same).
Some can be reset, that is done by the same name but starting with underscore
(_
). Some names may/must have arguments. These are numbers and are supplied
by directly writing them after the name, multiple arguments are separated by
commas. If the argument is optional it will have the default value written
next to it. The commas must be present even if there are no arguments. (e.g.
mt5,7
is valid, mt,7
is valid, mt5,
is valid, mt,
is valid, but mt
is not valid)
Ascii
bell
: console bell (create sound)backspace
: move left by onehtab
,tab
: horizontal tabulatormove_down_scrl
,mds
: move down by one line scrolling if needednewline
,nl
: move to the start of the next linevtab
: vertical tabulatorcarriage_return
|cr
: move to the start of the current line
Moving the cursor
move_to
,mt
: moves the cursor to the given position, has two arguments, default values are0
.move_up
,mu
: moves the cursor up by the given amount, has one argument, default value is1
move_down
,md
: moves the cursor down by the given amount, has one argument, default value is1
move_right
,mr
: moves the cursor right by the given amount, has one argument, default value is1
move_left
,ml
: moves the cursor left by the given amount, has one argument, default value is1
set_down
,sd
: moves the cursor to the start of line n lines down, has one argument, default value is1
set_up
,su
: moves the cursor to the start of line n lines up, has one argument, default value is1
move_to_column
,mc
: moves the cursor to the given x coordinate, has one argument, default value is0
move_up_scrl
,mus
: moves the cursor up by one line, scrolling if neededsave_cur
,save
,s
: saves the current cursor position (single slot, not lifo)load_cur
,loat
,l
: loads the last saved cursor position
Erasing
erase_to_end
,e_
: erases from the cursor to the end of the screenerase_from_start
,_e
: erases from the start of the screen to the cursorerase_screen
,_e_
: erases the whole screenerase_all
,e
: erases the whole screen and the scroll buffererase_ln_end
,el_
: erases from the cursor to the end of the lineerase_ln_start
,_el
: erases from the start of the line to the cursorerase_line
,erase_ln
,_el_
,el
: erases the current line
Styles and colors
reset
,_
: resets all colors and styles
bold
: sets style to boldfaint
,f
: sets style to faintitalic
,i
: sets style to italicunderline
,u
: sets style to underlineblinking
,blink
: sets style to blinkinginverse
: sets style to inverse (swap background and foreground)invisible
,invis
: sets the style to invisible (foreground and background are same)striketrough
,strike
: sets the style to striketroughdouble_underline
,dunderline
,dun
: sets the style to double underline
_bold
: resets bold and faint_italic
,_i
: resets italic_underline
,_u
: resets underline and double underline_blinking
,_blink
: resets blinking_inverse
: resets inverse_invisible
,_invis
: resets invisible_striketrough
,_strike
: resets striketrough
black_fg
,black
,bl
: sets the foreground to blackwhite_fg
,white
,w
: sets the foreground to whitegray_fg
,gray
,gr
: sets the foreground to greenbright_gray_fg
,bgray
,bgr
: sets the foreground to bright gray
red_fg
,red
,r
: sets the foreground to redgreen_fg
,green
,g
: sets the foreground to greenyellow_fg
,yellow
,y
: sets the foreground to yellowmagenta_fg
,magenta
,m
: sets the foreground to magentacyan_fg
,cyan
,c
: sets the foreground to cyan
dark_red_fg
,dred
,dr
: sets the foreground to dark reddark_green_fg
,dgreen
,dg
: sets the foreground to dark greendark_yellow_fg
,dyellow
,dy
: sets the foreground to dark yellowdark_magenta_fg
,dmagenta
,dm
: sets the foreground to dark magentadark_cyan_fg
,dcyan
,dc
: sets the foreground to dark cyan
_fg
: resets the foreground color
black_bg
,blackb
,blb
: sets the background to blackwhite_bg
,whiteb
,wb
: sets the background to whitegray_bg
,grayb
,grb
: sets the background to greenbright_gray_bg
,bgrayb
,bgrb
: sets the background to bright gray
red_bg
,redb
,rb
: sets the background to redgreen_bg
,greenb
,gb
: sets the background to greenyellow_bg
,yellowb
,yb
: sets the background to yellowmagenta_bg
,magentab
,mb
: sets the background to magentacyan_bg
,cyanb
,cb
: sets the background to cyan
dark_red_bg
,dredb
,drb
: sets the background to dark reddark_green_bg
,dgreenb
,dgb
: sets the background to dark greendark_yellow_bg
,dyellowb
,dyb
: sets the background to dark yellowdark_magenta_bg
,dmagentab
,dmb
: sets the background to dark magentadark_cyan_bg
,dcyanb
,dcb
: sets the background to dark cyan
_bg
: resets the background
fg
: sets the foreground color to one of the 256 colors, has one argumentbg
: sets the background color to one of the 256 colors, has one argument
Other
line_wrap
,wrap
: enable line wrapping_line_wrap
,_wrap
: disable line wrapping
hide_cursor
,nocur
: hide the cursorshow_cursor
,_nocur
: show the cursorsave_screen
,sscr
: saves the screen viewload_screen
,lscr
: restores the last saved screen viewalt_buf
,abuf
: enable alternative buffer_alt_buf
,_abuf
: disable alternative buffer
Compound
clear
,cls
: erases the screen and the buffer and moves the cursor to the topleft position (equivalent ofe mt,
)
Dependencies
~225KB