String::Bash - Parameter expansion in strings
version 1.110960
use String::Bash qw( bash ); # pass hashref print bash "Hello %{name:-Guest}!", { name => 'Alex' }; # or key/value pairs print bash "Hello %{name:-Guest}!", name => 'Alex'; # or object which can('name'); my $user = My::Users->new( name => 'Alex' ); print bash "Hello %{name:-Guest}!", $user; # or use lexical vars my $name = 'Alex'; print bash "Hello %{name:-Guest}!";
all will print
Hello Alex
or if name is undefined or empty
Hello Guest
String::Bash is based on shell parameter expansion from Bash, thus it allows to provide default values, substrings and in-place substitutions, changing case of characters and nesting.
The String::Bash provides bash exported with Sub::Exporter.
bash
Replacements can be provided in four different ways:
my $hashref = { param1 => 'value1', ... }; print bash $format, $hashref;
print bash $format, param1 => 'value1', ...;
print bash $format, $object;
Please note that $object needs to implement read/write accessors (if "%{param:=word}" is used, otherwise read-only are sufficient) for all parameters used in $format.
$object
$format
my $param1 = ...; our $param2 = ...; print bash $format;
Lexical (my) and package (our) scalar variables visible at the scope of bash caller are available as replacement.
my
our
Please assume that following variables are visible in below examples:
my $param = 'hello'; my $not_set; my $param2 = 'WELCOME';
print bash "%{param}"; # hello
Value of $param is substituted.
$param
print bash "%{param:-word}"; # hello print bash "%{not_set:-word}"; # word
If $param is unset or null, the expansion of word is substituted. Otherwise, the value of $param is substituted.
The word can be another parameter so nesting is possible:
print bash "%{not_set:-%{param2}}"; # WELCOME
print bash "%{not_set:=word}"; # word
If $param is unset or null, the expansion of word is assigned to $param. The value of $param is then substituted.
Notes on replacement syntax:
If "Object" is passed as replacement than assignment will execute following code:
$obj->$param( 'word' );
If "Key/value pairs" are passed as replacement then the assignment will be applied to occurrences of param after the assignment has been done, and will be disregarded after parsing is done.
If "Lexical variables" are used, then their value will be set to word.
print bash "%{param:+word}"; # word print bash "%{not_set:+word}"; #
If $param is null or unset, nothing is substituted, otherwise the expansion of word is substituted.
print bash "%{param:2}"; # llo print bash "%{param:2:2}"; # ll
Expands to up to length characters of $param starting at the character specified by offset. If length is omitted, expands to the substring of $param starting at the character specified by offset.
print bash "%{#param}"; # 5
The length in characters of the value of $param is substituted.
print bash "%{param#he*l}"; # lo print bash "%{param##he*l}"; # o
The word is expanded to produce a pattern (see "Pattern expansion"). If the pattern matches the beginning of the value of $param, then the result of the expansion is the expanded value of $param with the shortest matching pattern (the '#' case) or the longest matching pattern (the '##' case) deleted.
print bash "%{param%l*o}"; # hel print bash "%{param%%l*o}"; # he
The word is expanded to produce a pattern (see "Pattern expansion"). If the pattern matches a trailing portion of the value of $param, then the result of the expansion is the value of $param with the shortest matching pattern (the '%' case) or the longest matching pattern (the '%%' case) deleted.
print bash "%{param/l/t}"; # hetlo print bash "%{param//l/t}"; # hetto print bash "%{param/#h/t}"; # tello print bash "%{param/%o/t}"; # hellt
The pattern is expanded to produce a pattern (see "Pattern expansion"). The longest match of pattern against $param value is replaced with string. If pattern begins with '/', all matches of pattern are replaced with string. Normally only the first match is replaced. If pattern begins with '#', it must match at the beginning of the value of $param. If pattern begins with '%', it must match at the end of the $param. If string is null, matches of pattern are deleted and the / following pattern may be omitted.
print bash "%{param^}"; # Hello print bash "%{param^^}"; # HELLO print bash "%{param2,}"; # wELCOME print bash "%{param2,,}"; # welcome print bash "%{param^[hl]}"; # Hello print bash "%{param^^[hl]}"; # HeLLo print bash "%{param2,[WE]}"; # wELCOME print bash "%{param2,,[WE]}"; # weLCOMe
This expansion modifies the case of alphabetic characters in $param. The pattern is expanded to produce a pattern (see "Pattern expansion"). The '^' operator converts lowercase letters matching pattern to uppercase; the ',' operator converts matching uppercase letters to lowercase. The '^^' and ',,' expansions convert each matched character in $param; the '^' and ',' expansions match and convert only the first character in the value of $param. If pattern is omitted, it is treated like a '?', which matches every character.
Pattern expansion is performed using following rules (based on filename expansion):
# Character # Replacement (perl syntax) * .* ? . [a-z] [a-z]
Please do not use perl regular expression syntax in pattern substitutions, or you may get unexpected results.
String::Bash provides only syntax described above and some of Bash features (like expansions of arrays) are not available - but please let me know if you need them.
Shell Parameter Expansion in Bash
Alex J. G. Burzyński <ajgb@cpan.org>
This software is copyright (c) 2011 by Alex J. G. Burzyński <ajgb@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install String::Bash, copy and paste the appropriate command in to your terminal.
cpanm
cpanm String::Bash
CPAN shell
perl -MCPAN -e shell install String::Bash
For more information on module installation, please visit the detailed CPAN module installation guide.