https://github.com/zdharma-continuum/zsh-string-lib
https://github.com/zdharma-continuum/zsh-string-lib
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/zdharma-continuum/zsh-string-lib
- Owner: zdharma-continuum
- License: other
- Created: 2021-11-08T12:32:27.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-16T03:00:16.000Z (about 2 years ago)
- Last Synced: 2025-01-13T14:19:20.036Z (5 months ago)
- Language: Shell
- Size: 41 KB
- Stars: 1
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [zsh-string-lib](#zsh-string-lib)
- [List Of The Functions](#list-of-the-functions)
- [@str-parse-json](#str-parse-json)
- [@str-read-all](#str-read-all)
- [@str-ng-match](#str-ng-match)
- [@str-ng-matches](#str-ng-matches)
- [@str-read-ini](#str-read-ini)
- [@str-read-toml](#str-read-toml)
- [@str-dump](#str-dump)
# zsh-string-lib
A string library for Zsh. Its founding function was parsing of JSON.
## List Of The Functions
### @str-parse-json
Parses the buffer (`$1`) with JSON and returns:
1. Fields for the given key (`$2`) in the given hash (`$3`).
1. The hash looks like follows:
```
1/1 → strings at the level 1 of the 1st object
1/2 → strings at the level 1 of the 2nd object
…
2/1 → strings at 2nd level of the 1st object
…
```
The strings are parseable with `"${(@Q)${(@z)value}"`, i.e.: they're concatenated and quoted strings found in the
JSON.
Example:
```json
{
"zinit-ices":{
"default":{
"wait":"1",
"lucid":"",
"as":"program",
"pick":"fzy",
"make":"",
},
"bgn":{
"wait":"1",
"lucid":"",
"as":"null",
"make":"",
"sbin":"fzy;contrib/fzy-*"
}
}
}
```
Will result in:
```zsh
local -A Strings
Strings[1/1]="zinit-ices"
Strings[2/1]="default $'\0'--object--$'\0' bgn $'\0'--object--$'\0'"
Strings[3/1]='wait 1 lucid \ as program pick fzy make \ '
Strings[3/2]='wait 1 lucid \ as null make \ sbin fzy\;contrib/fzy-\*'
```
So that when you e.g.: expect a key `bgn` but don't know at which position, you can do:
```zsh
local -A Strings
@str-parse-json "$json" "zinit-ices" Strings
integer pos
# (I) flag returns index at which the `bgn' string
# has been found in the array – the result of the
# (z)-split of the Strings[2/1] string
pos=${${(@Q)${(@z)Strings[2/1]}}[(I)bgn]}
if (( pos )) {
local -A ices
ices=( "${(@Q)${(@z)Strings[3/$(( (pos+1) / 2 ))]}}" )
# Use the `ices' hash holding the values of the `bgn' object
…
}
```
Note that the `$'\0'` is correctly dequoted by `Q` flag into the null byte.
Arguments:
1. The buffer with JSON.
1. The key in the JSON that should be mapped to the result (i.e.: it's possible to map only a subset of the input). It
must be the first key in the object to map.
1. The name of the output hash parameter.
### @str-read-all
Consumes whole data from given file descriptor and stores the string under the given (`$2`) parameter, which is `REPLY`
by default.
The reason to create this function is speed – it's much faster than `read -d ''`.
It can try hard to read the whole data by retrying multiple times (`10` by default) and sleeping before each retry (not
done by default).
Arguments:
1. File descriptor (a number; use `1` for stdin) to be read from.
1. Name of output variable (default: `REPLY`).
1. Numer of retries (default: `10`).
1. Sleep time after each retry (a float; default: `0`).
Example:
```zsh
exec {FD}< =( cat /etc/motd )
@str-read-all $FD
print -r -- $REPLY
…
```
### @str-ng-match
Returns a non-greedy match of the given pattern (`$2`) in the given string (`$1`).
1. The string to match in.
1. The pattern to match in the string.
Return value:
- `$REPLY` – the matched string, if found,
- return code: `0` if there was a match found, otherwise `1`.
Example:
```zsh
if @str-ng-match "abb" "a*b"; then
print -r -- $REPLY
fi
Output: ab
```
### @str-ng-matches
Returns all non-greedy matches of the given pattern in the given list of strings.
Input:
- `$1` … `$n-1` - the strings to match in,
- `$n` - the pattern to match in the strings.
Return value:
- `$reply` – contains all the matches,
- `$REPLY` - holds the first match,
- return code: `0` if there was any match found, otherwise `1`.
Example:
```zsh
arr=( a1xx ayy a2xx )
if @str-ng-matches ${arr[@]} "a*x"; then
print -rl -- $reply
fi
Outout:
a1x
a2x
```
### @str-read-ini
Reads an INI file.
Arguments:
1. Path to the ini file to parse.
1. Name of output hash (`INI` by default).
1. Prefix for keys in the hash (can be empty).
Writes to given hash under keys built in following way: `${3}_field`. Values are the values from the ini file.
### @str-read-toml
Reads a TOML file with support for single-level array.
1. Path to the TOML file to parse.
1. Name of output hash (`TOML` by default).
1. Prefix for keys in the hash (can be empty).
Writes to given hash under keys built in following way: `${3}_field`. Values are the values from the TOML file.
The values can be quoted and concatenated strings if they're an array. For example:
```ini
[sec]
array = [ val1, "value 2", value&3 ]
```
Then the fields of the hash will be:
```zsh
TOML[_array]="val1 value\ 2 value\&3"
```
To retrieve the array stored in such way, use the substitution `"${(@Q)${(@z)TOML[_array]}}"`:
```zsh
local -a array
array=( "${(@Q)${(@z)TOML[_array]}}" )
```
(The substitution first splits the input string as if Zsh would split it on the command line – with the `(z)` flag, and
then removes one level of quoting with the `(Q)` flag).
### @str-dump
Dumps the contents of the variable, whether it's being a scalar, an array or a hash. The contents of the hash are sorted
on the keys numerically, i.e.: by using `(on)` flags.
An option `-q` can be provided: it'll enable quoting of the printed data with the `q`-flag (i.e.: backslash quoting).
Basically, the function Is an alternative to `declare -p`, with a different output format, more dump-like.
Arguments:
1. The name of the variable of which contents should be dumped.
Example:
```zsh
array=( "" "a value" "test" )
@str-dump -q array
```
Output:
```
''
a\ value
test
```
```zsh
typeset -A hash=( "a key" "a value" key value )
@str-dump -q hash
```
Output:
```
a\ key: a\ value
key: value
```