Raku Land

Text::ShellWords

cpan:SOFTMOTH

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:

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 siegeltr@gmail.com

COPYRIGHT AND LICENSE

Copyright 2020 Tim Siegel

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