https://github.com/softmoth/raku-text-shellwords
Split a string into words like a command-line shell
https://github.com/softmoth/raku-text-shellwords
Last synced: 12 months ago
JSON representation
Split a string into words like a command-line shell
- Host: GitHub
- URL: https://github.com/softmoth/raku-text-shellwords
- Owner: softmoth
- License: artistic-2.0
- Created: 2020-07-11T12:18:03.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2020-07-12T08:43:59.000Z (almost 6 years ago)
- Last Synced: 2025-04-10T01:16:39.207Z (about 1 year ago)
- Language: Raku
- Size: 15.6 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project
README
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: «12 hello3 world4 .»
```
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<.parse>. Use C<.new(:keep)> 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 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
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).