NAME

Prompt::Expand - provide prompt expansion logic

SYNOPSIS

use Prompt::Expand;

say expand(":time: >");                     # 19:24:11 >

say expand(":yellow,date,reset: >", "NL");  # zon 19 jan 2025 >

DESCRIPTION

The Prompt::Expand distribution provides the logic to expand a string (usually intended to be used as a prompt for user input) according to number of escape sequences (\x) or placeholder specifications :text:. As such it exports an expand subroutine that takes such a format, and returns the expanded string.

Placeholders are specified by an initial semi-colon (:), followed by one or more identifiers separated by commas, and ended with a final semi-colon.

Expansion currently provided are:

ANSI color / formatting codes
strftime escape codes
emoji escape codes
other generally useful escapes

Expansions involving date / time values, can be localized by specifying the language to be used, either as a string (e.g. "NL") or as a custom Locale::Dates object.

EXPANSIONS

ANSI color codes

Note that not all of these are supported everywhere!

:text:	function
normal	reset to default
bold	switch on bold characters
dim	switch on dimmer characters
italic	switch on italic characters
underline	switch on underlined characters
blink	switch on blinking characters
inverse	switch on inverted characters
hidden	switch on showing spaces instead of characters
strikethrough	switch on strikethrough characters
unbold	switch off bold characters
unitalic	switch off italic characters
ununderline	switch off underlined characters
uninverse	switch off inverse characters
black	switch to black foreground
red	switch to red foreground
green	switch to green foreground
yellow	switch to yellow foreground
blue	switch to blue foreground
magenta	switch to magenta foreground
cyan	switch to cyan foreground
white	switch to white foreground
default	switch to default foreground
BLACK	switch to black background
RED	switch to red background
GREEN	switch to green background
YELLOW	switch to yellow background
BLUE	switch to blue background
MAGENTA	switch to magenta background
CYAN	switch to cyan background
WHITE	switch to white background
DEFAULT	switch to default background

Raku escape sequences

Besides most of the standard Raku escape sequences with an associated :text: equivalent, also some other more interactive prompt related :text sequences:

:text:	escape	function
bell	\a	audible / visible alert
bksp	\b	backspace
escape	\e	initiate ANSI escape sequence
formfeed	\f	form feed (FF)
reset	\c	reset to all ANSI defaults
lf	\n	line feed (LF, newline, $?NL)
cr	\r	Carriage Return (CR)
tab	\t	tab
bslash	\\	backslash
index		$*INDEX value
symbol		$*SYMBOL value
language		language version
release		compiler release
compiler		compiler version

From DateTime::strftime:

Code	:text:	Value
%a	wkdname	abbreviated weekday name
%A	weekdayname	full weekday name
%b	mnthname	abbreviated month name
%B	monthname	full month name
%c	datetime	preferred date/time representation
%C	century	century number (year div 100)
%d	0day	day of month ("01" .. "31")
%D	usadate	short for: %m/%d/%y
%e	day	day of month (" 1" .. "31")
%f	minute	same as %M
%F	isodate	short for: %Y/%m/%d
%g	weekYY	YY of this week ("00" .. "99")
%G	weekYYYY	full year of this week
%h	mnthname	same as %b
%H	0hour	24-hour hour ("00" .. "23")
%I	0amhour	12-hour hour ("01" .. "12")
%j	yearday	day of the year ("001" .. "366")
%k	hour	24-hour hour (" 1" .. "23")
%l	amhour	12-hour hour (" 1" .. "12")
%L	year	same as %Y
%m	month	month ("01" .. "12")
%M	minute	minute ("00" .. "59")
%n	newline	"\n"
%p	AMPM	"AM" \| "PM"
%P	ampm	"am" \| "pm"
%r	amtime	short for: %I:%M:%S %p
%R	HHMM	short for: %H:%M
%s	epoch	seconds since epoch (midnight 1970-01-01 UTC)
%S	second	second ("00" .. "59")
%t	tab	"\t"
%T	HHMMSS	short for: %H:%M:%S
%u	weekday	weekday (1 .. 7)
%U	weekSun	week number (first Sunday) ("00" .. "53")
%v	DD-MON-YYYY	short for: %e-%b-%Y
%V	weekISO	week number (ISO 8601) ("00" .. "53")
%w	0weekday	weekday (0 .. 6)
%W	weekMon	week number (first Monday) ("00" .. "53")
%x	date	preferred date representation
%X	time	preferred time representation
%y	YY	year without century ("00" .. "99")
%Y	year	year (yyyy)
%z	tzoffset	numeric timezone (±HHMM)
%Z	timezone	timezone (no name: %z)
%+	unixdate	short for: %a %b %e %T %Z %G
%%	percent	"%"

From Text::Emoji, all of the 1870 conversions are supported.

AUTHOR

Elizabeth Mattijsen liz@raku.rocks

Source can be located at: https://github.com/lizmat/Prompt-Expand . Comments and Pull Requests are welcome.

If you like this module, or what I'm doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.