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:

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