<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">NAME
====

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

SYNOPSIS
========

```raku
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`).

```raku
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&lt;.parse&gt;. Use C&lt;.new(:keep)&gt; to keep quoting characters in the made words

shell-words
-----------

### sub shell-words

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

Split a string into its shell-quoted words. If C&lt;keep&gt; 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](https://metacpan.org/pod/Text::ParseWords) and [Text::Shellwords](https://metacpan.org/pod/Text::Shellwords).

The [Bash manual page](https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Quoting) describes the three quoting mechanisms copied by this module.

AUTHOR
======

Tim Siegel &lt;siegeltr@gmail.com&gt;

COPYRIGHT AND LICENSE
=====================

Copyright 2020 Tim Siegel

This library is free software; you can redistribute and modify it under the [Artistic License 2.0](http://www.perlfoundation.org/artistic_license_2_0).

</pre></body></html>