Help language development. Donate to The Perl Foundation

Text::ShellWords cpan:SOFTMOTH last updated on 2020-07-12

NAME

Text::ShellWords - Split a string into words like a command-line shell

SYNOPSIS

use Text::ShellWords;

my $input = Q{printf "%s\n" 1 "2 hello" '3 world' 4\ .};
my @output = run(:out, shell-words $input).out.lines(:close);
.put for @output;       # OUTPUT: «1␤2 hello␤3 world␤4 .␤»

DESCRIPTION

Text::ShellWords provides routines to split a string into words, respecting the Unix Bourne Shell (/bin/sh) quoting rules. From the bash manual page:

• There are three quoting mechanisms: the escape character, single quotes, and double quotes.

  A non-quoted backslash (\) is the escape character. It preserves the literal value of the next character that follows, with the exception of newline. If a \newline pair appears, and the backslash is not itself quoted, the \newline is treated as a line continuation (that is, it is removed from the input stream and effectively ignored).

  Enclosing characters in single quotes preserves the literal value of each character within the quotes. A single quote may not occur between single quotes, even when preceded by a backslash.

  Enclosing characters in double quotes preserves the literal value of all characters within the quotes, with the exception of \. The backslash retains its special meaning only when followed by one of the following characters: ", \, or newline. A double quote may be quoted within double quotes by preceding it with a backslash.

• Unlike the Bourne Shell, the characters $, `, and ! have no special meaning to this module.

class Text::ShellWords::Grammar

Parsing grammar for a shell-input string

class Text::ShellWords::WordFailure

Error indicator for an incomplete parse

Incomplete parsing

When the input string is malformed, or intended to continue on another line, the last word is made a WordFailure object, rather than a Str. This object behaves just like any Failure, but it stringifies to the final piece of input text if it has been handled (by testing if it is True or defined).

my @words = shell-words 'hello, "world';
put @words[0];      # OUTPUT «hello,␤»
try put @words[1];  # OUTPUT «»
put $!.message;     # OUTPUT «Input is malformed or incomplete, ends with '"world'␤»
# Now that it's been handled, it can used as a Str
put @words[1];      # OUTPUT «"world␤»
# But it is still a Failure
say @words[1].^name if not @words[1];   # OUTPUT: «Text::ShellWords::WordFailure␤»

class Text::ShellWords::Actions

Actions class for C<.parse>. Use C<.new(:keep)> to keep quoting characters in the made words

shell-words

sub shell-words

sub shell-words(
    Cool:D $input,
    Bool :$keep = Bool::False
) returns Mu

Split a string into its shell-quoted words. If C is True, the quote characters are preserved in the returned words. By default they are removed.

SEE ALSO

This module is inspired by, but has different behavior than, Perl's Text::ParseWords and Text::Shellwords.

The Bash manual page describes the three quoting mechanisms copied by this module.

AUTHOR

Tim Siegel [email protected]

COPYRIGHT AND LICENSE

Copyright 2020 Tim Siegel

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