aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc_src
diff options
context:
space:
mode:
authorGravatar Michael Steed <msteed@saltstack.com>2015-09-12 12:59:40 -0700
committerGravatar ridiculousfish <corydoras@ridiculousfish.com>2015-09-21 16:41:25 -0700
commitd83ef07ca76c03852366e4e810053edc19796761 (patch)
tree93f671c5fe577128fd14a1f013fff764e5c5abba /doc_src
parente70ed961eab80dab41ebfda7b91d80d9ef041be7 (diff)
Merge new string builtin
This adds the new builtin 'string' which supports various string manipulation and matching algorithms, including PCRE based regular expressions. Fixes #2296 Squashed commit of the following: commit 4c3eaeb6e57d76463e9683c327142b0aeafb92b8 Author: ridiculousfish <corydoras@ridiculousfish.com> Date: Sat Sep 12 12:51:30 2015 -0700 Remove testdata and doc dirs from pcre2 source commit b2a8b4b50f2398b204fb72cfe4b5ba77ece2e1ab Merge: 11c8a47 7974aab Author: ridiculousfish <corydoras@ridiculousfish.com> Date: Sat Sep 12 12:32:40 2015 -0700 Merge branch 'string' of git://github.com/msteed/fish-shell into string-test commit 7974aab6d367f999f1140ab34c2535cef5cf3b00 Author: Michael Steed <msteed@saltstack.com> Date: Fri Sep 11 13:00:02 2015 -0600 build pcre2 lib only, no docs commit eb20b43d2d96b7e6d24618158ce71078de83c40b Merge: 1a09e70 5f519cb Author: Michael Steed <msteed68@gmail.com> Date: Thu Sep 10 20:00:47 2015 -0600 Merge branch 'string' of github.com:msteed/fish-shell into string commit 1a09e709d028393c9e9e6dc9a84278f399a15f3d Author: Michael Steed <msteed68@gmail.com> Date: Thu Sep 10 19:58:24 2015 -0600 rebase on master & address the fallout commit a0ec9772cd1a0a548a501a7633be05dab4e5ee46 Author: Michael Steed <msteed68@gmail.com> Date: Thu Sep 10 19:26:45 2015 -0600 use fish's wildcard_match() for glob matching commit 64c25a01e3f7234f220ba13545cf658a7492b1a4 Author: Michael Steed <msteed68@gmail.com> Date: Thu Aug 27 08:19:23 2015 -0600 some fixes from review - string_get_arg_stdin(): simplify and don't discard the argument when the trailing newline is absent - fix calls to pcre2 for e.g. string match -r -a 'a*' 'b' - correct test for args coming from stdin commit ece7f35ec5f4093763627d68d671b6c0c876896d Author: Michael Steed <msteed68@gmail.com> Date: Sat Aug 22 19:35:56 2015 -0600 fixes from review - Makefile.in: restore iwyu target - regex_replacer_t::replace_matches(): correct size passed to realloc() commit 9ff7477a926c4572e26171cab3cd42f8086be678 Author: Michael Steed <msteed68@gmail.com> Date: Thu Aug 20 13:08:33 2015 -0600 Minor doc improvements commit baf4e096b22dde3063b85b833795eb570d660ba7 Author: Michael Steed <msteed68@gmail.com> Date: Wed Aug 19 18:29:02 2015 -0600 another attempt to fix the ci build commit 896a2c2b279a419747bea26102229fbe84534a6f Author: Michael Steed <msteed68@gmail.com> Date: Wed Aug 19 18:03:49 2015 -0600 Updates after review comments - make match/replace without -a operate on the first match on each argument - use different exit codes for "no operation performed" and errors, as grep does - refactor regex compile code - use human-friendly error messages from pcre2 - improve error handling & reporting elsewhere - add a few tests - make some doc fixes - some simplification & cleanup - fix ci build failure (I hope) commit efd47dcbda2ca247d58bee56a7774cd75a1062fd Author: Michael Steed <msteed68@gmail.com> Date: Wed Aug 12 00:26:07 2015 -0600 fix dependencies for parallel make commit ed0850e2db467362066a3d94e3ececd17c1756cd Author: Michael Steed <msteed68@gmail.com> Date: Tue Aug 11 23:37:22 2015 -0600 Add missing pcre2 files + .gitignore commit 9492e7a7e929c03554336be1ddf80ca6b37f53c5 Author: Michael Steed <msteed68@gmail.com> Date: Tue Aug 11 22:44:05 2015 -0600 add pcre2-10.20 and update license.hdr commit 1a60b933718feb20c0bf7c9e257b8e495014ea1b Author: Michael Steed <msteed68@gmail.com> Date: Tue Aug 11 22:41:19 2015 -0600 add string builtin files - string builtin source, tests, & docs - changes to configure.ac & Makefile.in commit 5f519cb2a2c05213e0a88a7add7af288bc1c1352 Author: Michael Steed <msteed68@gmail.com> Date: Thu Sep 10 19:26:45 2015 -0600 use fish's wildcard_match() for glob matching commit 2ecd24f79500879e2de5bdf1b4c19dd44fc6ac85 Author: Michael Steed <msteed68@gmail.com> Date: Thu Aug 27 08:19:23 2015 -0600 some fixes from review - string_get_arg_stdin(): simplify and don't discard the argument when the trailing newline is absent - fix calls to pcre2 for e.g. string match -r -a 'a*' 'b' - correct test for args coming from stdin commit 45b777e4dc85c05cd4a186f4bdcae543c21aaf08 Author: Michael Steed <msteed68@gmail.com> Date: Sat Aug 22 19:35:56 2015 -0600 fixes from review - Makefile.in: restore iwyu target - regex_replacer_t::replace_matches(): correct size passed to realloc() commit 981cbb6ddf742a5fe8881af916e7b870b7e6422a Author: Michael Steed <msteed68@gmail.com> Date: Thu Aug 20 13:08:33 2015 -0600 Minor doc improvements commit ddb6a2a8fdb6aa31aad41e80d5481bb32c6ed8ff Author: Michael Steed <msteed68@gmail.com> Date: Wed Aug 19 18:29:02 2015 -0600 another attempt to fix the ci build commit 1e34e3191b028162863d263e9868052f75194aa5 Author: Michael Steed <msteed68@gmail.com> Date: Wed Aug 19 18:03:49 2015 -0600 Updates after review comments - make match/replace without -a operate on the first match on each argument - use different exit codes for "no operation performed" and errors, as grep does - refactor regex compile code - use human-friendly error messages from pcre2 - improve error handling & reporting elsewhere - add a few tests - make some doc fixes - some simplification & cleanup - fix ci build failure (I hope) commit 34232e152df17a3cfbf0a094dd51d148a4f04e6f Author: Michael Steed <msteed68@gmail.com> Date: Wed Aug 12 00:26:07 2015 -0600 fix dependencies for parallel make commit 00d7e781697f53454beb91c1d0fc4b2d28d6e034 Author: Michael Steed <msteed68@gmail.com> Date: Tue Aug 11 23:37:22 2015 -0600 Add missing pcre2 files + .gitignore commit 4498aa5f576e09634f7f619443e74d2f33c108e4 Author: Michael Steed <msteed68@gmail.com> Date: Tue Aug 11 22:44:05 2015 -0600 add pcre2-10.20 and update license.hdr commit 290c58c72e22db644ccf6fa9088051644980ed0a Author: Michael Steed <msteed68@gmail.com> Date: Tue Aug 11 22:41:19 2015 -0600 add string builtin files - string builtin source, tests, & docs - changes to configure.ac & Makefile.in
Diffstat (limited to 'doc_src')
-rw-r--r--doc_src/license.hdr19
-rw-r--r--doc_src/string.txt200
2 files changed, 219 insertions, 0 deletions
diff --git a/doc_src/license.hdr b/doc_src/license.hdr
index b9d5fc8c..9d3c1248 100644
--- a/doc_src/license.hdr
+++ b/doc_src/license.hdr
@@ -115,6 +115,25 @@ The precise terms and conditions for copying, distribution and modification foll
----
+## License for PCRE2
+
+`fish` contains code from the [PCRE2](http://www.pcre.org) library to support regular expressions. This code, created by Philip Hazel, is distributed under the terms of the BSD license. Copyright © 1997-2015 University of Cambridge.
+
+The BSD license follows.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+ -# Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+ -# Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+ -# Neither the name of the University of Cambridge nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+----
+
+
## License for wcslcat and wcslcpy, and code derived from tmux
`fish` also contains small amounts of code under the OpenBSD license, namely versions of the two functions strlcat and strlcpy, modified for use with wide character strings. This code is copyrighted by Todd C. Miller (1998). It also contains code from [tmux](http://tmux.sourceforge.net), copyrighted by Nicholas Marriott <nicm@users.sourceforge.net> (2007), and made available under an identical license.
diff --git a/doc_src/string.txt b/doc_src/string.txt
new file mode 100644
index 00000000..c7781473
--- /dev/null
+++ b/doc_src/string.txt
@@ -0,0 +1,200 @@
+\section string string - manipulate strings
+
+\subsection string-synopsis Synopsis
+\fish{synopsis}
+string length [(-q | --quiet)] [STRING...]
+string sub [(-s | --start) START] [(-l | --length) LENGTH]
+ [(-q | --quiet)] [STRING...]
+string split [(-m | --max) MAX] [(-r | --right)] [(-q | --quiet)]
+ SEP [STRING...]
+string join [(-q | --quiet)] SEP [STRING...]
+string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)]
+ [(-q | --quiet)] [STRING...]
+string escape [(-n | --no-quoted)] [STRING...]
+string match [(-a | --all)] [(-i | --ignore-case)] [(-r | --regex)]
+ [(-n | --index)] [(-q | --quiet)] PATTERN [STRING...]
+string replace [(-a | --all)] [(-i | --ignore-case)] [(-r | --regex)]
+ [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]
+\endfish
+
+
+\subsection string-description Description
+
+`string` performs operations on strings.
+
+STRING arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one STRING per line. It is an error to supply STRING arguments on the command line and on standard input.
+
+Arguments beginning with `-` are normally interpreted as switches; `--` causes the following arguments not to be treated as switches even if they begin with `-`. Switches and required arguments are recognized only on the command line.
+
+Most subcommands accept a `-q` or `--quiet` switch, which suppresses the usual output but exits with the documented status.
+
+In addition to the exit codes documented below, all the string subcommands exit with a value of 2 to indicate that an error occurred.
+
+The following subcommands are available:
+
+- `length` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
+
+- `sub` prints a substring of each string argument. The start of the substring can be specified with `-s` or `--start` followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with `-l` or `--length`. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise.
+
+- `split` splits each STRING on the separator SEP, which can be an empty string. If `-m` or `--max` is specified, at most MAX splits are done on each STRING. If `-r` or `--right` is given, splitting is performed right-to-left. This is useful in combination with `-m` or `--max`. Exit status: 0 if at least one split was performed, or 1 otherwise.
+
+- `join` joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
+
+- `trim` removes leading and trailing whitespace from each STRING. If `-l` or `--left` is given, only leading whitespace is removed. If `-r` or `--right` is given, only trailing whitespace is trimmed. The `-c` or `--chars` switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.
+
+- `escape` escapes each STRING such that it can be passed back to `eval` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If `-n` or `--no-quote` is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
+
+- `match` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless `-a` or `--all` is given, in which case all matches are reported. Matching can be made case-insensitive with `-i` or `--ignore-case`. If `-n` or `--index` is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. If `-r` or `--regex` is given, PATTERN is interpreted as a Perl-compatible regular expression. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. Exit status: 0 if at least one match was found, or 1 otherwise.
+
+- `replace` is similar to `match` but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. If `-r` or `--regex` is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape sequences like `\t` as well as references to capturing groups by number or name as `$n` or `${n}`. Exit status: 0 if at least one replacement was performed, or 1 otherwise.
+
+
+\subsection string-example Examples
+
+\fish
+string length 'hello, world'
+# Output:
+# 12
+
+string length -q $str
+# Equivalent to test -n $str
+\endfish
+
+\fish
+string sub --length 2 abcde
+# Output:
+# ab
+
+string sub -s 2 -l 2 abcde
+# Output:
+# bc
+
+string sub --start=-2 abcde
+# Output:
+# de
+\endfish
+
+\fish
+string split . example.com
+# Output:
+# example
+# com
+
+string split -r -m1 / /usr/local/bin/fish
+# Output:
+# /usr/local/bin
+# fish
+
+string split '' abc
+# Output:
+# a
+# b
+# c
+\endfish
+
+\fish
+seq 3 | string join ...
+# Output:
+# 1...2...3
+\endfish
+
+\fish
+string trim ' abc '
+# Output:
+# abc
+
+string trim --right --chars=yz xyzzy zany
+# Output:
+# x
+# zan
+\endfish
+
+\fish
+echo \\x07 | string escape
+# Output:
+# \\cg
+\endfish
+
+\fish
+# string match glob examples
+
+string match '?' a
+# Output:
+# a
+
+string match 'a*b' axxb
+# Output:
+# axxb
+
+string match -i 'a??B' Axxb
+# Output:
+# Axxb
+
+echo 'ok?' | string match '*\\?'
+# Output:
+# ok?
+
+# string match regex examples
+
+string match -r 'cat|dog|fish' 'nice dog'
+# Output:
+# dog
+
+string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56
+# Output:
+# 2:34:56
+# 2
+# 34
+# 56
+
+string match -r '^(\\w{2,4})\\g1$' papa mud murmur
+# Output:
+# papa
+# pa
+# murmur
+# mur
+
+string match -r -a -n at ratatat
+# Output:
+# 2 2
+# 4 2
+# 6 2
+
+string match -r -i '0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;'
+# Output:
+# 0xBadC0de
+\endfish
+
+\fish
+
+# string replace literal examples
+
+string replace is was 'blue is my favorite'
+# Output:
+# blue was my favorite
+
+string replace 3rd last 1st 2nd 3rd
+# Output:
+# 1st
+# 2nd
+# last
+
+string replace -a ' ' _ 'spaces to underscores'
+# Output:
+# spaces_to_underscores
+
+# string replace regex examples
+
+string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x'
+# Output:
+# 0 3.14 5
+
+string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right'
+# Output:
+# right left $
+
+string replace -r '\s*newline\s*' '\n' 'put a newline here'
+# Output:
+# put a
+# here
+\endfish