StringManipulation.jl
This package has the purpose to provide several functions to manipulate strings with ANSI escape sequences.
Alignment
The function align_string
can be used to align the string in a field with a
specific size to the left, center, or right.
julia> align_string(
"A string with emojis ๐๐ and \e[4mdecoration\e[0m to be aligned",
80,
:c
) |> print
A string with emojis ๐๐ and decoration to be aligned
julia> align_string(
"A string with emojis ๐๐ and \e[4mdecoration\e[0m to be aligned",
80,
:r
) |> print
A string with emojis ๐๐ and decoration to be aligned
If the string has multiple lines, then all can be aligned at once using the
function align_string_per_line
.
julia> str = """
We have \e[38;5;231;48;5;243mhere\e[0m ๐
๐ the first line
We now have the ๐ \e[38;5;231;48;5;243msecond\e[0m ๐ line""";
julia> align_string_per_line(str, 80, :r) |> print
We have here ๐
๐ the first line
We now have the ๐ second ๐ line
Cropping
Fit string in a field
The function fit_string_in_field
crop the string so that it has a number of
printable characters that fits in a field.
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> fit_string_in_field(str, 9)
"Test ๐
โฆ\e[38;5;231;48;5;243m\e[38;5;201;48;5;243m\e[0m"
The function fit_string_in_field
has many options. For more information,
please, see the built-in help (type textview
in REPL).
Left cropping
The function left_crop
can be used to crop a field of specific width to the
left of the string. In this case, the function return the ANSI escape sequence
(non-printable string) in the cropped field, and the cropped string.
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> left_crop(str, 9)
("\e[38;5;231;48;5;243m", "est ๐
\e[38;5;201;48;5;243mTest\e[0m")
Right cropping
The function right_crop
can be used to crop a field of specific width to the
right of the string. In this case, the function return the cropped string, and
the ANSI escape sequence (non-printable string) in the cropped field.
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> right_crop(str, 5)
("Test ๐
\e[38;5;231;48;5;243mTest ๐
", "\e[38;5;201;48;5;243m\e[0m")
If the keyword keep_escape_seq
is set to false
, then the ANSI escape
sequence in the cropped field will not be computed. This can lead to a
substantial increase in the performance for very long string.
julia> right_crop(str, 5; keep_escape_seq = false)
("Test ๐
\e[38;5;231;48;5;243mTest ๐
", "")
Decorations
This package contains some functions to work with ANSI escape sequences that decorate the text.
Get decorations
All the decorations in a string can be retrieved using get_decorations
:
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> get_decorations(str)
"\e[38;5;231;48;5;243m\e[38;5;201;48;5;243m\e[0m"
Remove the decorations
It is possible to remove all the decorations in a string using the functions
remove_decorations
:
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> remove_decorations(str)
"Test ๐
Test ๐
Test"
Get and remove decorations
If someone wants to get all the decorations in a string, and the undecorated
string, the function get_and_remove_decorations
can be used to improve the
performance:
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> get_and_remove_decorations(str)
("\e[38;5;231;48;5;243m\e[38;5;201;48;5;243m\e[0m", "Test ๐
Test ๐
Test")
Parsing decorations
The ANSI escape sequences that decorates the text can be parsed using the
function parse_decoration
. The result is an object of type Decoration
with
the combined decoration created by the ANSI escape sequence.
julia> parse_decoration("\e[38;5;201;48;5;243;4;27m") |> dump
Decoration
foreground: String "38;5;201"
background: String "48;5;243"
bold: StringManipulation.DecorationState StringManipulation.unchanged
underline: StringManipulation.DecorationState StringManipulation.active
reset: Bool false
reversed: StringManipulation.DecorationState StringManipulation.inactive
Updating decorations
A decoration (object of type Decoration
) can be updated given another ANSI
escape sequence using update_decoration
:
julia> decoration = parse_decoration("\e[38;5;201;48;5;243;4;27m");
julia> update_decoration(decoration, "\e[33;1m") |> dump
Decoration
foreground: String "33"
background: String "48;5;243"
bold: StringManipulation.DecorationState StringManipulation.active
underline: StringManipulation.DecorationState StringManipulation.active
reset: Bool false
reversed: StringManipulation.DecorationState StringManipulation.inactive
Highlight search matches
The function highlight_search
can be used to highlight search matches, given
by a Regex
, in a string.
julia> str = """
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque tempor
risus vel diam ultrices volutpat. Nullam id tortor ut dolor rutrum cursus
aliquam sed lorem. Donec interdum, risus eu scelerisque posuere, purus magna
auctor purus, in faucibus nisi quam ac erat. Nulla facilisi. Aenean et augue
augue. Donec ut sem posuere, venenatis est quis, ultrices elit. Vivamus elit
sapien, ullamcorper quis dui ut, suscipit varius nibh. Duis varius arcu id
ipsum egestas aliquam. Pellentesque eget sem ornare turpis fringilla fringilla
id ac turpis.
""";
julia> highlight_search(str, r"ing"; active_match = 2) |> println
The function highlight_search
has many options. For more information, please,
see the built-in help (type ?highlight_search
in REPL).
Printable text width
The printable text width of a string can be computed using the function
printable_textwidth
:
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> printable_textwidth(str)
20
If the string has multiple lines, then the function
printable_textwidth_per_line
can be used to compute the printable text width
of each one of them:
julia> str = """
Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m
Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest Test\e[0m
Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest Test Test\e[0m""";
julia> printable_textwidth_per_line(str)
3-element Vector{Int64}:
20
25
30
Splitting
The function split_string
can be used to split a string given a desired size
(printable characters width).
julia> str = "Test ๐
\e[38;5;231;48;5;243mTest ๐
\e[38;5;201;48;5;243mTest\e[0m";
julia> split_string(str, 8)
("Test ๐
\e[38;5;231;48;5;243m", "Test ๐
\e[38;5;201;48;5;243mTest\e[0m")
Text view
The function textview
can be used to create a view of a text.
julia> str = """
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque tempor
risus vel diam ultrices volutpat. Nullam id tortor ut dolor rutrum cursus
aliquam sed lorem. Donec interdum, risus eu scelerisque posuere, purus magna
auctor purus, in faucibus nisi quam ac erat. Nulla facilisi. Aenean et augue
augue. Donec ut sem posuere, venenatis est quis, ultrices elit. Vivamus elit
sapien, ullamcorper quis dui ut, suscipit varius nibh. Duis varius arcu id
ipsum egestas aliquam. Pellentesque eget sem ornare turpis fringilla fringilla
id ac turpis.
""";
julia> textview(str, (1, 3, 10, 50))[1] |> println
um dolor sit amet, consectetur adipiscing
diam ultrices volutpat. Nullam id tortor
ed lorem. Donec interdum, risus eu sceler
Notice that it correctly considers all the ANSI escape sequences that decorate the text, yielding to a view that matches all the characteristics of the original text (foreground color, background color, underline, etc.).
The function textview
has many options. For more information, please, see the
built-in help (type ?textview
in REPL).