txt: ## dist_cpan-SOFTMOTH-Text-ShellWords.md
  # 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](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 [siegeltr@gmail.com](mailto: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](http://www.perlfoundation.org/artistic_license_2_0).
  