Help language development. Donate to The Perl Foundation

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

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


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 .␤»


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


### 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<keep> is True, the quote characters are preserved in the returned words. By default they are removed.


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.


Tim Siegel <[email protected]>


Copyright 2020 Tim Siegel

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