{"id":20162553,"url":"https://github.com/zdharma-continuum/zsh-string-lib","last_synced_at":"2025-09-13T16:12:39.409Z","repository":{"id":46119515,"uuid":"425829824","full_name":"zdharma-continuum/zsh-string-lib","owner":"zdharma-continuum","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-16T03:00:16.000Z","size":42,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-08T00:09:23.131Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zdharma-continuum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-08T12:32:27.000Z","updated_at":"2022-01-23T19:55:24.000Z","dependencies_parsed_at":"2024-11-14T00:27:16.661Z","dependency_job_id":"1818e58d-8b86-420d-9f1b-4814acb94281","html_url":"https://github.com/zdharma-continuum/zsh-string-lib","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zdharma-continuum/zsh-string-lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-string-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-string-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-string-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-string-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zdharma-continuum","download_url":"https://codeload.github.com/zdharma-continuum/zsh-string-lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-string-lib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274989931,"owners_count":25386552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T00:25:40.540Z","updated_at":"2025-09-13T16:12:39.387Z","avatar_url":"https://github.com/zdharma-continuum.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [zsh-string-lib](#zsh-string-lib)\n  - [List Of The Functions](#list-of-the-functions)\n    - [@str-parse-json](#str-parse-json)\n    - [@str-read-all](#str-read-all)\n    - [@str-ng-match](#str-ng-match)\n    - [@str-ng-matches](#str-ng-matches)\n    - [@str-read-ini](#str-read-ini)\n    - [@str-read-toml](#str-read-toml)\n    - [@str-dump](#str-dump)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# zsh-string-lib\n\nA string library for Zsh. Its founding function was parsing of JSON.\n\n## List Of The Functions\n\n### @str-parse-json\n\nParses the buffer (`$1`) with JSON and returns:\n\n1. Fields for the given key (`$2`) in the given hash (`$3`).\n\n1. The hash looks like follows:\n\n   ```\n   1/1 → strings at the level 1 of the 1st object\n   1/2 → strings at the level 1 of the 2nd object\n   …\n   2/1 → strings at 2nd level of the 1st object\n   …\n   ```\n\n   The strings are parseable with `\"${(@Q)${(@z)value}\"`, i.e.: they're concatenated and quoted strings found in the\n   JSON.\n\nExample:\n\n```json\n{\n    \"zinit-ices\":{\n        \"default\":{\n            \"wait\":\"1\",\n            \"lucid\":\"\",\n            \"as\":\"program\",\n            \"pick\":\"fzy\",\n            \"make\":\"\",\n        },\n        \"bgn\":{\n            \"wait\":\"1\",\n            \"lucid\":\"\",\n            \"as\":\"null\",\n            \"make\":\"\",\n            \"sbin\":\"fzy;contrib/fzy-*\"\n        }\n    }\n}\n```\n\nWill result in:\n\n```zsh\nlocal -A Strings\nStrings[1/1]=\"zinit-ices\"\nStrings[2/1]=\"default $'\\0'--object--$'\\0' bgn $'\\0'--object--$'\\0'\"\nStrings[3/1]='wait 1 lucid \\  as program pick fzy make \\ '\nStrings[3/2]='wait 1 lucid \\  as null make \\  sbin fzy\\;contrib/fzy-\\*'\n```\n\nSo that when you e.g.: expect a key `bgn` but don't know at which position, you can do:\n\n```zsh\nlocal -A Strings\n@str-parse-json \"$json\" \"zinit-ices\" Strings\n\ninteger pos\n# (I) flag returns index at which the `bgn' string\n# has been found in the array – the result of the\n# (z)-split of the Strings[2/1] string\npos=${${(@Q)${(@z)Strings[2/1]}}[(I)bgn]}\nif (( pos )) {\n  local -A ices\n  ices=( \"${(@Q)${(@z)Strings[3/$(( (pos+1) / 2 ))]}}\" )\n  # Use the `ices' hash holding the values of the `bgn' object\n  …\n}\n```\n\nNote that the `$'\\0'` is correctly dequoted by `Q` flag into the null byte.\n\nArguments:\n\n1. The buffer with JSON.\n1. 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\n   must be the first key in the object to map.\n1. The name of the output hash parameter.\n\n### @str-read-all\n\nConsumes whole data from given file descriptor and stores the string under the given (`$2`) parameter, which is `REPLY`\nby default.\n\nThe reason to create this function is speed – it's much faster than `read -d ''`.\n\nIt can try hard to read the whole data by retrying multiple times (`10` by default) and sleeping before each retry (not\ndone by default).\n\nArguments:\n\n1. File descriptor (a number; use `1` for stdin) to be read from.\n1. Name of output variable (default: `REPLY`).\n1. Numer of retries (default: `10`).\n1. Sleep time after each retry (a float; default: `0`).\n\nExample:\n\n```zsh\nexec {FD}\u003c =( cat /etc/motd )\n@str-read-all $FD\nprint -r -- $REPLY\n…\n```\n\n### @str-ng-match\n\nReturns a non-greedy match of the given pattern (`$2`) in the given string (`$1`).\n\n1. The string to match in.\n1. The pattern to match in the string.\n\nReturn value:\n\n- `$REPLY` – the matched string, if found,\n- return code: `0` if there was a match found, otherwise `1`.\n\nExample:\n\n```zsh\nif @str-ng-match \"abb\" \"a*b\"; then\n  print -r -- $REPLY\nfi\nOutput: ab\n```\n\n### @str-ng-matches\n\nReturns all non-greedy matches of the given pattern in the given list of strings.\n\nInput:\n\n- `$1` … `$n-1` - the strings to match in,\n- `$n` - the pattern to match in the strings.\n\nReturn value:\n\n- `$reply` – contains all the matches,\n- `$REPLY` - holds the first match,\n- return code: `0` if there was any match found, otherwise `1`.\n\nExample:\n\n```zsh\narr=( a1xx ayy a2xx )\nif @str-ng-matches ${arr[@]} \"a*x\"; then\n   print -rl -- $reply\nfi\n\nOutout:\na1x\na2x\n```\n\n### @str-read-ini\n\nReads an INI file.\n\nArguments:\n\n1. Path to the ini file to parse.\n1. Name of output hash (`INI` by default).\n1. Prefix for keys in the hash (can be empty).\n\nWrites to given hash under keys built in following way: `${3}\u003csection\u003e_field`. Values are the values from the ini file.\n\n### @str-read-toml\n\nReads a TOML file with support for single-level array.\n\n1. Path to the TOML file to parse.\n1. Name of output hash (`TOML` by default).\n1. Prefix for keys in the hash (can be empty).\n\nWrites to given hash under keys built in following way: `${3}\u003csection\u003e_field`. Values are the values from the TOML file.\n\nThe values can be quoted and concatenated strings if they're an array. For example:\n\n```ini\n[sec]\narray = [ val1, \"value 2\", value\u00263 ]\n```\n\nThen the fields of the hash will be:\n\n```zsh\nTOML[\u003csec\u003e_array]=\"val1 value\\ 2 value\\\u00263\"\n```\n\nTo retrieve the array stored in such way, use the substitution `\"${(@Q)${(@z)TOML[\u003csec\u003e_array]}}\"`:\n\n```zsh\nlocal -a array\narray=( \"${(@Q)${(@z)TOML[\u003csec\u003e_array]}}\" )\n```\n\n(The substitution first splits the input string as if Zsh would split it on the command line – with the `(z)` flag, and\nthen removes one level of quoting with the `(Q)` flag).\n\n### @str-dump\n\nDumps the contents of the variable, whether it's being a scalar, an array or a hash. The contents of the hash are sorted\non the keys numerically, i.e.: by using `(on)` flags.\n\nAn option `-q` can be provided: it'll enable quoting of the printed data with the `q`-flag (i.e.: backslash quoting).\n\nBasically, the function Is an alternative to `declare -p`, with a different output format, more dump-like.\n\nArguments:\n\n1. The name of the variable of which contents should be dumped.\n\nExample:\n\n```zsh\narray=( \"\" \"a value\" \"test\" )\n@str-dump -q array\n```\n\nOutput:\n\n```\n''\na\\ value\ntest\n```\n\n```zsh\ntypeset -A hash=( \"a key\" \"a value\" key value )\n@str-dump -q hash\n```\n\nOutput:\n\n```\na\\ key: a\\ value\nkey: value\n```\n\n\u003c!-- vim:set ft=markdown tw=80 fo+=an1 autoindent: --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzsh-string-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzdharma-continuum%2Fzsh-string-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzsh-string-lib/lists"}