The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
String-Bash-1.110960
River stage one • 1 direct dependent • 1 total dependent
/ String::Bash

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 Alex

or if name is undefined or empty


            

              
              
Hello Guest

DESCRIPTION

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}"; # hello

Value of $param is substituted.

%{param:-word}


            

              
              
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

%{param:=word}


            

              
              
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.

%{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}";   # 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.

%{#param}


            

              
              
print bash "%{#param}";   # 5

The 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}";  # 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.

%{param%word}

%{param%%word}


            

              
              
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.

%{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}";  # 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.

%{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]}";   # 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.

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.