NAME
String::Bash - Parameter expansion in strings
VERSION
version 1.110960
SYNOPSIS
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 Alexor if name is undefined or empty
Hello GuestDESCRIPTION
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.
REPLACEMENT VALUES
Replacements can be provided in four different ways:
Hash reference
my $hashref = { param1 => 'value1', ... };
print bash $format, $hashref;Key/value pairs
print bash $format, param1 => 'value1', ...;Object
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.
Lexical variables
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.
FORMAT SYNTAX
Please assume that following variables are visible in below examples:
my $param = 'hello';
my $not_set;
my $param2 = 'WELCOME';%{param}
print bash "%{param}"; # helloValue of $param is substituted.
%{param:-word}
print bash "%{param:-word}"; # hello
print bash "%{not_set:-word}"; # wordIf $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%{param:=word}
print bash "%{not_set:=word}"; # wordIf $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.
%{param:+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.
%{param:offset}
%{param:offset:length}
print bash "%{param:2}"; # llo
print bash "%{param:2:2}"; # llExpands 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.
%{#param}
print bash "%{#param}"; # 5The length in characters of the value of $param is substituted.
%{param#word}
%{param##word}
print bash "%{param#he*l}"; # lo
print bash "%{param##he*l}"; # oThe 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.
%{param%word}
%{param%%word}
print bash "%{param%l*o}"; # hel
print bash "%{param%%l*o}"; # heThe 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.
%{param/pattern/string}
print bash "%{param/l/t}"; # hetlo
print bash "%{param//l/t}"; # hetto
print bash "%{param/#h/t}"; # tello
print bash "%{param/%o/t}"; # helltThe 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.
%{param^pattern}
%{param^^pattern}
%{param,pattern}
%{param,,pattern}
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]}"; # weLCOMeThis 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.
NOTES
Pattern expansion
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.
COMPATIBILITY WITH BASH
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.
SEE ALSO
AUTHOR
Alex J. G. Burzyński <ajgb@cpan.org>
COPYRIGHT AND LICENSE
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.