DEV Community: Sall

✨〰️Feature-rich Syntax Highlighting〰️✨

Sall — Sat, 04 Jun 2022 08:24:46 +0000

Fast-Syntax-Highlighting Themes

Recursive fast-syntax-highlighting, highlights code passed to sh -c

Switch themes via fast-theme {theme-name}.

Run fast-theme -t {theme-name} option to obtain the snippet above.

Run fast-theme -l to list available themes.

Variables

Comparing to the project zsh-users/zsh-syntax-highlighting (the upper line):

Brackets

Conditions

Comparing to the project zsh-users/zsh-syntax-highlighting (the upper line):

Strings

Exact highlighting that recognizes quotings.

here-strings

`exec` descriptor-variables

Comparing to the project zsh-users/zsh-syntax-highlighting (the upper line):

for-loops and alternate syntax (brace `{`/`}` blocks)

Function definitions

Comparing to the project zsh-users/zsh-syntax-highlighting (the upper 2 lines):

Recursive `eval` and `$( )` highlighting

Comparing to the project zsh-users/zsh-syntax-highlighting (the upper line):

Chroma functions

Highlighting that is specific for a given command.

The chromas that are enabled by default can be found here.

Math-mode highlighting

Zcalc highlighting

Performance

Performance differences can be observed in this Asciinema recording, where a 10 kB function is being edited.

Installation

Post install try: fast-theme -t z-shell. To enable: fast-theme z-shell.

Manual

Clone the Repository.

git clone https://github.com/z-shell/F-Sy-H ~/path/to/fsh

And add the following to your zshrc file.

source ~/path/to/fsh/F-Sy-H.plugin.zsh

ZI

Add the following to your zshrc file.

zi light z-shell/F-Sy-H

Here's an example of how to load the plugin together with a few other popular ones with the use of Turbo mode, i.e.: speeding up the Zsh startup by loading the plugin right after the first prompt, in background:

zi wait lucid for \
 atinit"ZI[COMPINIT_OPTS]=-C; zicompinit; zicdreplay" \
    z-shell/F-Sy-H \
 blockf \
    zsh-users/zsh-completions \
 atload"!_zsh_autosuggest_start" \
    zsh-users/zsh-autosuggestions

✨〰️A Swiss Army Knife for Zsh〰️Unix Shell〰️✨

Sall — Tue, 31 May 2022 07:54:58 +0000

❮ ZI ❯ 🧙‍‍♀️ A Swiss Army Knife for Zsh.

Designed to glue everything together. 🔗

https://z.digitalclouds.dev | GitHub | Discussions | Localize

⚡️ Fast and feature-rich

✴️ 🌀Meta-plugins installs a group of complex plugins via a simple label, curated and optimal settings which are automatically applied.

✴️ 🌀Packages offloads from complex configurations and stores them as an easy to swap & share profiles.

✴️ 🌀Annexes are extensions that are installed when required to provide additional functionality, and capabilities.

✴️ 🌀Turbo mode yields 50–80% faster Zsh startup, just because no one likes to wait for someone :)

🥵 Currently biggest issue is that it seems to be too complex for new users and recently made some adjustments which are now starting to provide the results.

☑️ Neat and flexible

✴️ Customize the paths, use multiple prompts in the same sessions by setting the triggers or create your own plugins to simplify or improve the routine.

✴️ Supports Oh My Zsh and Prezto plugins and libraries. ( migration).

✴️ Does not use $FPATH, loading multiple plugins doesn't clutter $FPATH with the same number of entries, e.g: 10, 15, even, or more.

✴️ Code is immune to KSH_ARRAYS and other options, which typically cause compatibility problems.

✴️ Do not require sudo, and provide many ways & workarounds to set up a clean and safe environment. e.g: setting so-called shims locally.

If there is something that is not supported yet, I am pretty confident that if there will be reasonable demand - it will be implemented. 🔨

📈 Familiarize and control

✴️ Quickly familiarize oneself with a new plugin and provides rich and easy-to-digest information that might be helpful on various occasions.

✴️ Load, unload plugins when required, use the ability to manage completions.

✴️ Docker playground to test, view, or propose configurations.

✴️ 💫Gallery of the user favorites.

Is only limited to your own 🤦‍♂️ imagination… 🧙‍‍♀️ We need the support to make it better and more approachable to new users, become a 💞 friend of the DEV 💞, and more ☁️ cloud-native ☁️.

✨〰️ ZI 〰️✨ Vim Syntax

Sall — Thu, 28 Apr 2022 08:52:53 +0000

❮ ZI ❯ 🧙‍‍♀️ A Swiss Army Knife for Zsh.

Designed to glue everything together. 🔗

https://z.digitalclouds.dev | GitHub | Discussions | Localize

A Vim syntax definition for ZI commands in any file of type zsh.

📥 Installation

Load as a Vim plugin. E.g. when using vim-plug, add to ~/.vimrc:

Plug 'z-shell/zi-vim-syntax'

and then issue the :PlugInstall command.

📕 Manual Installation

To install the syntax copy the file after/syntax/zsh.vim under the path ~/.vim/syntax/after.

✍️ Examples

✴️ The default theme:

✴️ The theme flrnprz/plastic.vim:

✴️ The theme slate:

✴️ The theme murphy:

✴️ The theme lucasprag/simpleblack:

⚙️ ❮ ZSH Native Scripting Handbook ❯

Sall — Tue, 01 Mar 2022 21:33:52 +0000

❮ ZI ❯

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

Information
- @ is about keeping array form
- extended_glob
Constructs
- Reading a file
- Skipping dirname basename
- Resolve Symlinks
- Skipping grep
- Multi-line matching like with grep
- Pattern matching in AND-fashion
- Skipping tr
- Ternary expressions with +,-,:+,:- substitutions
- Ternary expressions with :# substitution
- Using built-in regular expressions engine
- Skipping uniq
- Skipping awk
- Searching arrays
- Code execution in // substitution
- Serializing data
- Tip: serializing with Bash
Real-world examples
- Testing for Git subcommand
- Counting unquoted-only apostrophes
Tips and Tricks
- Parsing INI file

Information

@ is about keeping array form

How to access all array elements in a shell? The standard answer: use @ subscript, i.e. ${array[@]}. However, this
is the Bash & Ksh way (and with the option KSH_ARRAYS, Zsh also works this way, i.e. needs @ to access the whole
array). Z shell is different: it is $array that refers to all elements anyway. There is no need for the @
subscript.

So what use has @ in the Zsh-world? It is: "keep array form" or "do not join". When is it activated? When the user
quotes the array, i.e. invokes "$array", he induces joining of all array elements (into a single string). @ is to
have elements still quoted (so empty elements are preserved), but not joined.

Two forms are available, "$array[@]" and "${(@)array}". The first form has an additional effect – when an option
KSH_ARRAYS is set, it indeed induces referencing to the whole array instead of a first element only. It should then
use braces, i.e. ${array[@]}, "${array[@]}" (KSH_ARRAYS requirement).

In practice, if you'll use @ as a subscript – [@], not as a flag – ${(@)...}, then you'll make the code
KSH_ARRAYS-compatible.

extended_glob

Glob-flags #b and #m require setopt extended_glob. Patterns utilizing ~ and ^ also require it. Extended-glob
is one of the main features of Zsh.

Constructs

Reading a file

declare -a lines; lines=( "${(@f)"$(<path/file)"}" )

This preserves empty lines because of double-quoting (the outside one). @-flag is used to obtain an array instead of a
scalar. If you don't want empty lines preserved, you can also skip @-splitting, as is explained in the
Information section:

declare -a lines; lines=( ${(f)"$(<path/file)"} )

Note: $(<...) construct strips trailing empty lines.

Reading from stdin

This topic is governed by the same principles a the previous paragraph (Reading a file), with the single difference
that instead of the substitution "$(<file-path)" the substitution that should be used is "$(command arg1 ...)",
i.e.:

declare -a lines; lines=( ${(f)"$(command arg1 ...)"} )

This will read the command's output into the array lines. The version that does @ splitting and retains any empty
lines are:

declare -a lines; lines=( "${(f@)$(command arg1 ...)}" )

Note that instead of four double-quotes ", an idiom that is justified (simply suggested) by the Zsh documentation (and
was used in the previous paragraph, in the snippet ... "${(@f)"$(<path/file)"}" ...), only two double-quotes are
being used. I've investigated this form with the main Zsh developers on the zsh-workers@zsh.org mailing list and it
was clearly stated that single, outside quoting of ${(f@)...} substitution works as if it was also separately applied
to $(command ...) (or to $(<file-path)) inner substitution, so the second double-quoting isn't needed.

Skipping dirname basename

dirname and basename can be skipped by:

local dirname="${PWD:h}"
local basename="${PWD:t}"

Resolve Symlinks

Symbolic links can be turned into an absolute path with:

local absolute_path="${PWD:A}"

Skipping grep

declare -a lines; lines=( "${(@f)"$(<path/file)"}" )
declare -a grepped; grepped=( ${(M)lines:#*query*} )

To have the grep -v effect, skip the M-flag. To grep case-insensitively, use \#i glob flag (...:#(#i)\*query*}).

As it can be seen, ${...:#...} substitution is filtering of the array, which by default filters-out elements ((M)
flag induces the opposite behavior). When used with string, not an array, it behaves similarly: returns an empty string
when {input_string_var:#pattern} matches the whole input string.

Side-note: (M) flag can be used also with ${(M)var#pattern} and other substitutions, to retain what's matched by the
pattern instead of removing that.

Multi-line matching like with grep

Suppose you have a Subversion repository and want to check if it contains files being not under version control. You
could do this in Bash style like follows:

local svn_status="$(svn status)"
if [[ -n "$(echo "$svn_status" | \grep \^\?)" ]]; then
    echo found
fi

Those are 3 forks: for svn status, for echo, and for grep. This can be solved by the :# substitution and (M)
flag described above in this section (just check if the number of matched lines is greater than 0). However, there's a
more direct approach:

local svn_status="$(svn status)" nl=$'\n'
if [[ "$svn_status" = *((#s)|$nl)\?* ]]; then
  echo found
fi

This requires extendedglob. The (#s) means: "start of the string". So ((#s)|$nl) means "start of the string OR
preceded by a new-line".

If the extendedglob option cannot be used for some reason, this can be achieved also without it, but essentially it
means that alternative (i.e. |) of two versions of the pattern will have to be matched:

setopt localoptions noextendedglob
local svn_status="$(svn status)" nl=$'\n'
if [[ "$svn_status" = (\?*|*$nl\?*) ]]; then
  echo found
fi

In general, multi-line matching falls into the following idiom (extended glob version):

local needle="?" required_preceding='[[:space:]]#'
[[ "$(svn status)" = *((#s)|$nl)${~required_preceding}${needle}* ]] && echo found

It does a single fork (calls svn status). The ${~variable} means (the~ init): "the variable is holding a pattern,
interpret it". All in all, instead of regular expressions we were using patterns (globs) (see
this section).

Pattern matching in AND-fashion

[[ "abc xyz efg" = *abc*~^*efg* ]] && print Match found

The ~ is a negation -- match \*abc* but not .... Then, ^ is also a negation. The effect is:
\*ABC* but not those that don't have \*efg* which equals to: \*ABC* but those that have also \*efg*. This is a
regular pattern and it can be used with :# above to search arrays, or with the R-subscript flag to search hashes
(${hsh[\(R)\*pattern*]}), etc. The inventor of those patterns is Mikael Magnusson.

Skipping tr

declare -A map; map=( a 1 b 2 );
text=( "ab" "ba" )
text=( ${text[@]//(#m)?/${map[$MATCH]}} )
print $text ▶ 12 21

#m flag enables the $MATCH parameter. At each // substitution, $map is queried for character-replacement. You
can substitute a text variable too, just skip [@] and parentheses in the assignment.

Ternary expressions with `+,-,:+,:-` substitutions

HELP="yes"; print ${${HELP:+help enabled}:-help disabled} ▶ help enabled
HELP=""; print ${${HELP:+help enabled}:-help disabled} ▶ help disabled

Ternary expression is known from C language but exists also in Zsh, but directly only in a math context, i.e.
\(( a = a > 0 ? b : c )). The flexibility of Zsh allows such expressions also in a normal context. Above is an
example. :+ is "if not empty, substitute …" :- is "if empty, substitute …". You can save a great number of lines of
code with those substitutions, it's normally at least 4-lines if condition or lengthy &&/|| use.

Ternary expressions with `:#` substitution

var=abc; print ${${${(M)var:#abc}:+is abc}:-not abc} ▶ is abc
var=abcd; print ${${${(M)var:#abc}:+is abc}:-not abc} ▶ not abc

A one-line "if var = x, then …, else …". Again, can spare a great amount of boring code that makes a 10-line function a
20-line one.

[#built-in-regular-expressions-engine]

Using built-in regular expressions engine

[[ "aabbb" = (#b)(a##)*(b(#c2,2)) ]] && print ${match[1]}-${match[2]} ▶ aa-bb

\## is: "1 or more". (#c2,2) is: "exactly 2". A few other constructs: # is "0 or more", ? is "any character",
(a|b|) is "a or b or empty match". #b enables the $match parameters. There's also #m but it has one parameter
$MATCH for whole matched text, not for any parenthesis.

Zsh patterns are a custom regular expressions engine. They are slightly faster than the zsh/regex module (used for
=~ operator) and don't have that dependency (regex module can be not present, e.g. in default static build of Zsh).
Also, they can be used in substitutions, for example in // substitution.

Skipping uniq

declare -aU array; array=( a a b ); print $array ▶ a b
declare -a array; array=( a a b ); print ${(u)array} ▶ a b

Enable -U flag for array so that it guards elements to be unique, or use u-flag to make unique elements of an array.

Skipping awk

declare -a list; list=( "a,b,c,1,e" "p,q,r,2,t" );
print "${list[@]/(#b)([^,]##,)(#c3,3)([^,]##)*/${match[2]}}" ▶ 1 2

The pattern specifies 3 blocks of [^,]##, so 3 "not-comma multiple times, then comma", then the single block of
"not-comma multiple times" in second parentheses -- and then replaces this with second parentheses. The result is the
4th column extracted from multiple lines of text, something awk is often used for. Another method is the use of the
s-flag. For a single line of text:

text="a,b,c,1,e"; print ${${(s:,:)text}[4]} ▶ 1

Thanks to in-substitution code-execution capabilities it's possible to use s-flag to apply it to multiple lines:

declare -a list; list=( "a,b,c,1,e" "p,q,r,2,t" );
print "${list[@]/(#m)*/${${(s:,:)MATCH}[4]}}" ▶ 1 2

There is a problem with the (s::) flag that can be solved if Zsh is version 5.4 or higher: if there will be single
input column, e.g. list=( "column1" "a,b") instead of two or more columns (i.e. list=( "column1,column2" "a,b" )),
then (s::) will return string instead of 1-element array. So the index [4] in the above snippet will index a
string, and show its 4-th letter. Starting with Zsh 5.4, thanks to a patch by Bart Schaefer
(40640: the (A) parameter flag forces array result even if...), it is possible to force array-kind of result even
for a single column, by adding (A) flag, i.e.:

declare -a list; list=( "a,b,c,1,e" "p,q,r,2,t" "column1" );
print "${list[@]/(#m)*/${${(As:,:)MATCH}[4]}}" ▶ 1 2
print "${list[@]/(#m)*/${${(s:,:)MATCH}[4]}}" ▶ 1 2 u

Side-note: (A) flag is often used together with ::= assignment-substitution and (P) flag, to assign arrays and
hashes by-name.

Searching arrays

declare -a array; array=( a b " c1" d ); print ${array[(r)[[:space:]][[:alpha:]]*]} ▶ c1

\[[:space:]] contains unicode spaces. This is often used in conditional expression like [[ -z ${array[(r)...]} ]].

Note that Skipping grep that uses :# substitution can also be used to search arrays.

Code execution in `//` substitution

append() { gathered+=( $array[$1] ); }
functions -M append 1 1 append
declare -a array; array=( "Value 1" "Other data" "Value 2" )
declare -a gathered; integer idx=0
: ${array[@]/(#b)(Value ([[:digit:]]##)|*)/$(( ${#match[2]} > 0 ? append(++idx) : ++idx ))}
print $gathered ▶ Value 1 Value 2

Use of #b glob flag enables math-code execution (and not only) in / and // substitutions. Implementation is very
fast.

Serializing data

declare -A hsh deserialized; hsh=( key value )
serialized="${(j: :)${(qkv@)hsh}}"
deserialized=( "${(Q@)${(z@)serialized}}" )
print ${(kv)deserialized} ▶ key value

j-flag means join -- by spaces, in this case. Flags kv mean: keys and values, interleaving. Important q-flag
means: quote. So what is obtained is each key and value quoted, and put into a string separated by spaces.

z-flag means: split as if Zsh parser would split. So quoting (with backslashes, double quoting, and others) is
recognized. Obtained is array ( "key" "value") which is then de-quoted with Q-flag. This yields original data,
assigned to hash deserialized. Use this to e.g. implement an array of hashes.

Note: to be compatible with setopt ksharrays, use [@] instead of (@), e.g.:
...( "${(Q)${(z)serialized[@]}[@]}" )

Tip: serializing with Bash

array=( key1 key2 )
printf -v serialized "%q " "${array[@]}"
eval "deserialized=($serialized)"

This method works also with Zsh. The drawback is the use of eval, however, no problem may occur unless someone
compromises variable's value, but as always, eval should be avoided if possible.

Real-world examples

Testing for Git subcommand

Following code checks, if there is a git subcommand $mysub:

if git help -a | grep "^  [a-z]" | tr ' ' '\n' | grep -x $mysub > /dev/null > /dev/null; then

Those are 4 forks. The code can be replaced according to this guide:

local -a lines_list
lines_list=( ${(f)"$(git help -a)"} )
lines_list=( ${(M)${(s: :)${(M)lines_list:#   [a-z]*}}:#$mysub} )
if (( ${#lines_list} > 0 )); then
    …
fi

The result is just 1 fork.

Counting unquoted-only apostrophes

A project was needing this to do some Zle line-continuation tricks (when you put a backslash-\ at the end of the line
and press enters – it is the line-continuation that occurs at that moment).

The required functionality is: in the given string, count the number of apostrophes, but only the unquoted ones. This
means that only apostrophes with null or an even number of preceding backslashes should be accepted into the count:

buf="word'continue\'after\\\'afterSecnd\\''afterPair"
integer count=0
: ${buf//(#b)((#s)|[^\\])([\\][\\])#(\'\'#)/$(( count += ${#match[3]} ))}
echo $count ▶ 3

The answer (i.e. the output) to the above presentation and example is: 3 (there are 3 unquoted apostrophes in total
in the string kept in the variable $buf).

Below follows a variation of the above snippet that doesn't use math-code execution:

buf="word'continue\'after\\\'afterSecnd\\''afterPair"
buf="${(S)buf//(#b)*((#s)|[^\\])([\\][\\])#(\'\'#)*/${match[3]}}"; buf=${buf%%[^\']##}
integer count=${#buf}
echo $count ▶ 3

This is possible thanks to (S) flag – non-greedy matching, ([\\][\\])# trick – it matches only unquoted following
(\'\'##) characters (which are the apostrophes) and a general strategy to replace anything-apostrope(s) (unquoted
ones) with the-apostrope(s) (and then count them with ${#buf}).

Tips and Tricks

Parsing INI file

With Zshell's extended_glob parsing an ini file is an easy task. It will not result in a nested-arrays data
structure (Zsh doesn't support nested hashes), but the hash keys like $DB_CONF[db1_<connection>_host] is actually
intuitive.

The code should be placed in a file named read-ini-file, in $fpath, and autoload read-ini-file should be invoked.

# $1 - path to the ini file to parse
# $2 - the name of output hash
# $3 - prefix for keys in the hash
#
# Writes to given hash under keys built-in following way: ${3}<section>_field.
# Values are values from the ini file. Example invocation:
#
# read-ini-file ./database1-setup.ini DB_CONF db1_
# read-ini-file ./database2-setup.ini DB_CONF db2_
#

setopt localoptions extendedglob

local __ini_file="$1" __out_hash="$2" __key_prefix="$3"
local IFS='' __line __cur_section="void" __access_string
local -a match mbegin mend

[[ ! -r "$__ini_file" ]] && { builtin print -r "read-ini-file: an ini file is unreadable ($__ini_file)"; return 1; }

while read -r -t 1 __line; do
    if [[ "$__line" = [[:blank:]]#\;* ]]; then
        continue
    # Match "[Section]" line
    elif [[ "$__line" = (#b)[[:blank:]]#\[([^\]]##)\][[:blank:]]# ]]; then
        __cur_section="${match[1]}"
    # Match "string = string" line
    elif [[ "$__line" = (#b)[[:blank:]]#([^[:blank:]=]##)[[:blank:]]#[=][[:blank:]]#(*) ]]; then
        match[2]="${match[2]%"${match[2]##*[! $'\t']}"}" # severe trick - remove trailing whitespace
        __access_string="${__out_hash}[${__key_prefix}<$__cur_section>_${match[1]}]"
        : "${(P)__access_string::=${match[2]}}"
    fi
done < "$__ini_file"

return 0

⚙️ ❮ ZSH Plugin Standard ❯

Sall — Sat, 26 Feb 2022 02:50:09 +0000

❮ ZI ❯

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

Table of Contents:

What Is A Zsh Plugin?
1. Standardized $0 Handling
- Adopted [ zero-handling ]
2. Functions Directory
- Adopted [ functions-directory ]
3. Binaries Directory
- Adopted [ binaries-directory ]
4. Unload Function
- Adopted [ unload-function ]
5. @zsh-plugin-run-on-unload Call
- Adopted [ run-on-unload-call ]
6. @zsh-plugin-run-on-update Call
- Adopted [ run-on-update-call ]
7. Plugin Manager Activity Indicator
- Adopted [ activity-indicator ]
8. Global Parameter With PREFIX For Make, Configure, Etc
- Adopted [ global-parameter-with-prefix ]
9. Global Parameter holding the plugin manager’s capabilities
- Adopted [ global-parameter-with-capabilities ]
Zsh Plugin-Programming Best practices
Use Of add-zsh-hook To Install Hooks
Use Of add-zle-hook-widget To Install Zle Hooks
Standard Parameter Naming
Standard Plugins Hash
Standard Recommended Options
Standard Recommended Variables
Standard Function Name-Space Prefixes
The Problems Solved By The Proposition
The Proposed Function-Name Prefixes
Example Code Utilizing The Prefixes
Preventing Function Pollution
Preventing Parameter Pollution

What Is A Zsh Plugin?

Historically, Zsh plugins were first defined by Oh My Zsh. They provide a way to package together files that extend or configure the shell’s functionality in a particular way.

At a simple level, a plugin:

Has its directory added to $fpath (Zsh documentation). This is being done either by a plugin manager or by the plugin itself (see 5th section for more information).
Has it's first *.plugin.zsh file sourced (or *.zsh, init.zsh, *.sh, these are non-standard).

2.1 The first point allows plugins to provide completions and functions that are loaded via Zsh’s autoload mechanism (a single function per file).

From a more broad perspective, a plugin consists of:

3.1. A directory containing various files (the main script, autoload functions, completions, Makefiles, backend programs, documentation).

3.2. A sourceable script that obtains the path to its directory via $0 (see the next section for a related enhancement proposal).

3.3. A Github (or another site) repository identified by two components username/pluginname.

3.4. A software package containing any type of command line artifacts – when used with advanced plugin managers that have hooks, can run Makefiles, add directories to $PATH.

Below follow the proposed enhancements and codifications of the definition of a "Zsh the plugin" and the actions of plugin managers – the proposed standardization.

They cover the information on how to write a Zsh plugin.

1. Standardized `$0` Handling

[ zero-handling ]

To get the plugin’s location, plugins should do:

0="${ZERO:-${${0:#$ZSH_ARGZERO}:-${(%):-%N}}}"
0="${${(M)0:#/*}:-$PWD/$0}"

Then ${0:h} to get the plugin’s directory.

The one-line code above will:

Be backward-compatible with normal $0 setting and usage.
Use ZERO if it’s not empty,

the plugin manager will be easily able to alter effective $0 before loading a plugin,
this allows e.g. eval "$(<plugin)", which can be faster than source (comparison note that it’s not for a compiled script).

Use $0 if it doesn’t contain the path to the Zsh binary,

plugin manager will still be able to set $0, although more difficultly (requires unsetopt function_argzero before sourcing plugin script, and 0=… assignment),
unsetopt function_argzero will be detected (it causes $0 not to contain a plugin-script path, but the path to Zsh binary, if not overwritten by a 0=… assignment),
setopt posix_argzero will be detected (as above).

Use %N prompt expansion flag, which always gives absolute path to script,

plugin manager cannot alter this (no advanced loading of plugin is possible), but simple plugin-file sourcing (without a plugin manager) will be saved from breaking caused by the mentioned *_argzero options, so this is a very good last-resort fallback.

Finally, in the second line, it will ensure that $0 contains an absolute path by prepending it with $PWD if necessary.

The goal is flexibility, with essential motivation to support eval "$(<plugin)" and definitely solve setopt no_function_argzero and setopt posix_argzero cases.

A plugin manager will be even able to convert a plugin to a function (author implemented such proof of concept functionality, it’s fully possible – also in an automatic fashion), but performance differences of this are yet unclear.

It might however provide a use case.

The last, 5th point also allows using the $0 handling in scripts (i.e. runnable with the hashbang #!…) to get the directory in which the script file resides.

The assignment uses quoting to make it resilient to the combination of GLOB_SUBST and GLOB_ASSIGN options. It’s a standard snippet of code, so it has to be always working.

When you’ll set e.g.: the zsh emulation in a function, you in general don’t have to quote assignments.

Adopted [ zero-handling ]

Plugin managers: ZI, Zinit, Zpm, Zgenom, Zgen (after and if the PR will be merged).
Plugins: GitHub search

2. Functions Directory

[ functions-directory ]

Despite that, the current-standard plugins have their main directory added to $fpath, a more clean approach is being proposed:

that the plugins use a subdirectory called functions to store their completions and autoload functions. This will allow a much cleaner design of plugins.

The plugin manager should add such a directory to $fpath.

The lack of support of the current plugin managers can be easily resolved via the indicator:

if [[ ${zsh_loaded_plugins[-1]} != */kalc && -z ${fpath[(r)${0:h}/functions]} ]] {
    fpath+=( "${0:h}/functions" )
}

or, via use of the PMSPEC parameter:

if [[ $PMSPEC != *f* ]] {
    fpath+=( "${0:h}/functions" )
}

The above snippet added to the plugin.zsh file will add the directory to the $fpath with the compatibility with any new plugin managers preserved.

The existence of the functions subdirectory cancels the normal adding of the main plugin directory to $fpath.

Adopted [ functions-directory ]

Plugin managers: Zpm, ZI, Zinit, Zgenom.

3. Binaries Directory

[ binaries-directory ]

Plugins sometimes provide a runnable script or program, either for their internal use or for the end-user.

It is proposed that for the latter, the plugin shall use a bin/ subdirectory inside its main dir (it is recommended, that for internal use, the runnable be called via the $0 value obtained as described above).

The runnable should be put into the directory with a +x access right assigned.

The task of the plugin manager should be:

Before sourcing the plugin’s script it should test, if the bin/ directory exists within the plugin directory.
If it does, it should add the directory to $PATH.
The plugin manager can also, instead of extending the $PATH, create a shim (i.e.: a forwarder script) or a symbolic link inside a common directory that’s already added to $PATH (to limit extending it).
The plugin manager is permitted to do optional things like ensuring +x access rights on the directory contents.

The $PMSPEC code letter for the feature is b, and it allows for the plugin to handle the $PATH extending itself, via, e.g.:

if [[ $PMSPEC != *b* ]] {
    path+=( "${0:h}/bin" )
}

Adopted [ binaries-directory ]

Plugin managers: Zpm, Zgenom (when you set ZGENOM_AUTO_ADD_BIN=1).

4. Unload Function

[ unload-function ]

If a plugin is named e.g. kalc (and is available via an-user/kalc plugin-ID), then it can provide a function, kalc_plugin_unload, that can be called by a plugin manager to undo the effects of loading that plugin.

A plugin manager can implement its tracking of changes made by a plugin so this is in general optional. However, to properly unload e.g. a prompt, dedicated tracking (easy to do for the plugin creator) can provide better, predictable results.

Any special, uncommon effects of loading a plugin are possible to undo only by a dedicated function.

However, an interesting compromise approach is available – to withdraw only the special effects of loading a plugin via the dedicated, plugin-provided function and leave the rest to the plugin manager. The value of such an approach is that maintaining such function (if it is to withdraw all plugin side-effects) can be a daunting task requiring constant monitoring of it during the plugin development process.

Note that the unload function should contain unfunction $0 (or better unfunction kalc_plugin_unload etc., for compatibility with the *_argzero options), to also delete the function itself.

Adopted [ unload-function ]

ZI, implements plugin unloading and calls the function.
romkatv/powerlevel10k, is using the function to execute a specific task: shutdown of the binary, background gitstatus demon, with a very good results,
agkozak/agkozak-zsh-prompt is using the function to completely unload the prompt,
agkozak/zsh-z is using the function to completly unload the plugin,
agkozak/zhooks is using the function to completely unload the plugin.

5. `@zsh-plugin-run-on-unload` Call

[ run-on-unload-call ]

The plugin manager can provide a function @zsh-plugin-run-on-unload which has the following call syntax:

@zsh-plugin-run-on-unload "{code-snippet-1}" "{code-snippet-2}" …

The function registers pieces of code to be run by the plugin manager on unload of the plugin.

The execution of the code should be done by the eval built-in in the same order as they are passed to the call.

The code should be executed in the plugin’s directory, in the current shell.

The mechanism thus provides another way, side to the unload function, for the plugin to participate in the process of unloading it.

Adopted [ run-on-unload-call ]

Plugin managers: ZI, Zinit.

6. `@zsh-plugin-run-on-update` Call

[ run-on-update-call ]

The plugin manager can provide a function @zsh-plugin-run-on-update which has the following call syntax:

@zsh-plugin-run-on-update "{code-snippet-1}" "{code-snippet-2}" …

The function registers pieces of code to be run by the plugin manager on an update of the plugin.

The execution of the code should be done by the eval built-in in the same order as they are passed to the call.

The code should be executed in the plugin’s directory, possibly in a subshell After downloading any new commits to the repository.

Adopted [ run-on-update-call ]

Plugin managers: ZI, Zinit.

7. Plugin Manager Activity Indicator

[ activity-indicator ]

Plugin managers should set the $zsh_loaded_plugins array to contain all previously loaded plugins and the plugin currently being loaded (as the last element).

This will allow any plugin to:

Check which plugins are already loaded.
Check if it is being loaded by a plugin manager (i.e. not just sourced).

The first item allows a plugin to e.g. issue a notice about missing dependencies.

Instead of issuing a notice, it may be able to satisfy the dependencies from resources it provides.

For example, the pure prompt provides a zsh-async dependency library within its source tree, which is normally a separate project. Consequently, the prompt can decide to source its private copy of zsh-async, having also reliable $0 defined by the previous section (note: pure doesn’t normally do this).

The second item allows a plugin to e.g. set up $fpath, knowing that plugin manager will not handle this:

if [[ ${zsh_loaded_plugins[-1]} != */kalc && -z ${fpath[(r)${0:h}]} ]] {
    fpath+=( "${0:h}" )
}

This will allow the user to reliably source the plugin without using a plugin manager.

The code uses the wrapping braces around variables (i.e.: e.g.: ${fpath…}) to make it compatible with the KSH_ARRAYS option and the quoting around ${0:h} to make it compatible with the SH_WORD_SPLIT option.

Adopted [ activity-indicator ]

Plugin managers: ZI, Zinit, Zpm, Zgenom, Zgen (after and if the PR will be merged).
Plugins: GitHub search

8. Global Parameter With PREFIX For Make, Configure, Etc

[ global-parameter-with-prefix ]

Plugin managers may export the parameter $ZPFX which should contain a path to a directory dedicated for user-land software, i.e. for directories $ZPFX/bin, $ZPFX/lib, $ZPFX/share, etc.

The suggested name of the directory is polaris (e.g.: ZI uses this name and places this directory at ~/.zi/polaris by default).

Users can then configure hooks (a feature of e.g. zplug and ZI) to invoke e.g. make PREFIX=$ZPFX install at clone & update of the plugin to install software like e.g. tj/git-extras. This is the developing role of Zsh plugin managers as package managers, where .zshrc has a similar role to Chef or Puppet configuration and allows to declare system state, and have the same state on different accounts/machines.

No-narration facts-list related to $ZPFX:

export ZPFX="$HOME/polaris" (or e.g. $HOME/.zi/polaris)
make PREFIX=$ZPFX install
./configure --prefix=$ZPFX
cmake -DCMAKE_INSTALL_PREFIX=$ZPFX .
zi ice make"PREFIX=$ZPFX install"
zi … hook-build:"make PREFIX=$PFX install"

Adopted [ global-parameter-with-prefix ]

Plugin managers: ZI, Zinit, Zpm, Zgenom.

9. Global Parameter holding the plugin manager’s capabilities

[ global-parameter-with-capabilities ]

The above paragraphs of the standard spec each constitute a capability, a feature of the plugin manager.

It would make sense that the capabilities are somehow discoverable. To address this, a global parameter called PMSPEC (from plugin-manager specification) is proposed.

It can hold the following Latin letters each informing the plugin, that the plugin manager has support for a given feature:

0 – the plugin manager provides the ZERO parameter,
f - … supports the functions/ subdirectory,
b - … supports the bin/ subdirectory,
u - … the unload function,
U - … the @zsh-plugin-run-on-unload call,
p – … the @zsh-plugin-run-on-update call,
i – … the zsh_loaded_plugins activity indicator,
P – … the ZPFX global parameter,
s – … the PMSPEC global parameter itself (i.e.: should be always present).

The contents of the parameter describing a fully-compliant plugin manager should be: 0fuUpiPs.

The plugin can then verify the support by, e.g.:

if [[ $PMSPEC != *f* ]] {
    fpath+=( "${0:h}/functions" )
}

Adopted [ global-parameter-with-capabilities ]

Plugin managers: ZI, Zinit, Zpm, Zgenom.

Zsh Plugin-Programming Best practices

The document is to define a Zsh-plugin but also to serve as an information source for plugin creators.

Therefore, it covers also best practices information in this section.

Use Of `add-zsh-hook` To Install Hooks

Zsh ships with the function add-zsh-hook. It has the following invocation syntax:

add-zsh-hook [ -L | -dD ] [ -Uzk ] hook function

The command installs a function as one of the supported zsh hook entries. which are one of: chpwd, periodic, precmd, preexec, zshaddhistory, zshexit, zsh_directory_name. For their meaning refer to the Zsh documentation.

Use Of `add-zle-hook-widget` To Install Zle Hooks

The zle editor is the part of the Zsh that is responsible for receiving the text from the user.

It can be said that it’s based on widgets, which are nothing more than Zsh functions that are allowed to be run in Zle context, i.e. from the Zle editor (plus a few minor differences, like e.g.: the $WIDGET parameter that’s automatically set by the Zle editor).

The syntax of the call is:

add-zle-hook-widget [ -L | -dD ] [ -Uzk ] hook widgetname

The call resembles the syntax of the add-zsh-hook function. The only difference is that it takes a widgetname, not a function name and that the hook is being one of: isearch-exit, isearch-update, line-pre-redraw, line-init, line-finish, history-line-set, or keymap-select.

Their meaning is explained in the Zsh documentation.

The use of this function is recommended because it allows the installation multiple hooks per each hook entry. Before introducing the add-zle-hook-widget function the "normal" way to install a hook was to define a widget with the name of one of the special widgets.

Now, after the function has been introduced in Zsh 5.3 it should be used instead.

Standard Parameter Naming

There’s a convention already present in the Zsh world – to name array variables lowercase and scalars uppercase. It’s being followed by e.g.: the Zsh manual and the Z shell itself (e.g.: REPLY scalar and reply array, etc.).

The requirement for the scalars to be uppercase should be, in my opinion, kept only for the global parameters. I.e.: it’s fine to name local parameters inside a function lowercase even when they are scalars, not only arrays.

An extension to the convention is being proposed: to name associative arrays (i.e.: hashes) capitalized, i.e.: with only first letter uppercase and the remaining letters lowercase.

See the next section for an example of such hash. In the case of the name consisting of multiple words each of them should be capitalized, e.g.: typeset -A MyHash.

This convention will increase code readability and bring order to it.

Standard `Plugins` Hash

The plugin often has to declare global parameters that should live throughout a Zsh session. Following the namespace pollution prevention the plugin could use a hash to store the different values.

Additionally, the plugins could use a single hash parameter – called Plugins – to prevent the pollution even more:

…
typeset -gA Plugins
# An example value needed by the plugin
Plugins[MY_PLUGIN_REPO_DIR]="${0:h}"

This way all the data of all plugins will be kept in a single parameter, available for easy examination and overview (via e.g.: varied Plugins) and also not polluting the namespace.

Standard Recommended Options

The following code snippet is recommended to be included at the beginning of each of the main functions provided by the plugin:

emulate -L zsh
setopt extended_glob warn_create_global typeset_silent \
        no_short_loops rc_quotes no_auto_pushd

It resets all the options to their default state according to the zsh emulation mode, with the use of the local_options option – so the options will be restored to their previous state when leaving the function.

It then alters the emulation by 6 different options:

extended_glob – enables one of the main Zshell features – the advanced, built-in regex-like globing mechanism,
warn_create_global – enables warnings to be printed each time a (global) the variable is defined without being explicitly defined by a typeset, local, declare, etc. call; it allows to catch typos and missing localizations of the variables and thus prevent from writing a bad code,
typeset_silent – it allows to call typeset, local, etc. multiple times on the same variable; without it, the second call causes the variable contents to be printed first; using this option allows declaring variables inside loops, near the place of their use, which sometimes helps to write a more readable code,
no_short_loops – disables the short-loops syntax; this is done because when the syntax is enabled it limits the parser’s ability to detect errors (see this zsh-workers post for the details),
rc_quotes – adds useful ability to insert apostrophes into an apostrophe-quoted string, by use of '' inside it, e.g.: 'a string’s example' will yield the string a string’s example,
no_auto_pushd - disables the automatic push of the directory passed to cd builtin onto the directory stack; this is useful because otherwise, the internal directory changes done by the plugin will pollute the global directory stack.

Standard Recommended Variables

It’s good to localize the following variables at the entry of the main function of a plugin:

local MATCH REPLY; integer MBEGIN MEND
local -a match mbegin mend reply

The variables starting with m and M are being used by the substitutions utilizing (#b) and (#m) flags, respectively. They should not leak to the global scope. Also, their automatic creation would trigger the warning from the warn_create_global option.

The reply and REPLY parameters are being normally used to return an array or a scalar from a function, respectively – it’s the standard way of passing values from functions.

Their use is naturally limited to the functions called from the main function of a plugin – they should not be used to pass data around e.g.: in between prompts, thus it’s natural to localize them in the main function.

Standard Function Name-Space Prefixes

The recommendation is the purely subjective opinion of the author.

It can evolve – if you have any remarks, don’t hesitate to fill them.

The Problems Solved By The Proposition

However, when adopted, the proposition will solve the following issues:

Using the underscore _ to namespace functions – this isn’t the right thing to do because the prefix is being already used by the completion functions, so the namespace is already filled up greatly and the plugin functions get lost in it.
Not using a prefix at all – this is also an unwanted practice as it pollutes the command namespace (an example of such issue appearing).
It would allow to quickly discriminate between function types – e.g.: seeing the : prefix informs the user that it’s a hook-type function while seeing the @ prefix informs the user that it’s an API-like function, etc.
It also provides an improvement during programming, by allowing to quickly limit the number of completions offered by the editor, e.g.: for Vim’s Ctrl-P completing, when entering +<Ctrl-P>, then only a subset of the functions are being completed (see below for the type of the functions). Note: the editor has to be configured so that it accepts such special characters as part of keywords, for Vim it’s: :set isk+=@-@,.,+,/,: for all of the proposed prefixes.

The Proposed Function-Name Prefixes

The proposition of the standard prefixes is as follows:

.: for regular private functions. Example function: .prompt_zinc_get_value.
→: for hook-like functions, so it should be used e.g.: for the Zsh hooks and the Zle hooks, but also any other, custom hook-like mechanism in the plugin. Example function name: →prompt_zinc_precmd.

2.1. the previous version of the document recommended colon (:) for the prefix, however, it was problematic, because Windows doesn’t allow colons in file names, so it wasn’t possible to name an autoload function this way.

2.2. the arrow has a rationale behind it - it denotes the execution coming back to the function at a later time after it has been registered as a callback or a handler,

2.3. the arrow is easy to type on most keyboard layouts – it is Right-Alt+I; in case of problems with typing the character can be always copied – handler functions do occur in the code rarely,

2.4. Zsh supports any string as a function name because absolutely any string can be a file name – if there would be an exception in the name of the callables, then how would it be possible to run a script called "→abcd"? There are no exceptions, the function can be called even as the sequence of null bytes:

    ❯ $'\0'() { print hello }
    ❯ $'\0'
    hello

+: for output functions, i.e.: for functions that print to the standard output and error or a log, etc. Example function name: +prompt_zinc_output_segment.
/: for debugging functions, i.e: for functions that output debugs messages to the screen or a log or e.g.: gather some debug data. Note: the slash makes it impossible for such functions to be auto-loaded via the autoload mechanism. It is somewhat risky to assume, that this will never be needed for the functions, however, the limited number of available ASCII characters justifies such allocation. Example function name: /prompt_zinc_dmsg.
@: for API-like functions, i.e: for functions that are on a boundary to a subsystem and expose its functionality through a well-defined, in the generally fixed interface. For example, this plugin standard defines the function @zsh-plugin-run-on-update, which is exposing a plugin manager’s functionality in a well-defined way.

Example Code Utilizing The Prefixes

.zinc_register_hooks() {
    add-zsh-hook precmd :zinc_precmd
    /zinc_dmsg "Installed precmd hook with result: $?"
    @zsh-plugin-run-on-unload "add-zsh-hook -d precmd :zinc_precmd"
    +zinc_print "Zinc initialization complete"
}

Preventing Function Pollution

When writing a larger autoload function, it very often is the case that the function contains definitions of other functions.

When the main function finishes executing, the functions are being left defined. This might be undesired, e.g.: because of the command namespace pollution. The following snippet of code, when added at the beginning of the main function will automatically unset the sub-functions when leaving the main function:

# Don't leak any functions into the global namespace
typeset -g prjef
prjef=( ${(k)functions} )
trap "unset -f -- \"\${(k)functions[@]:|prjef}\" &>/dev/null; unset prjef" EXIT
trap "unset -f -- \"\${(k)functions[@]:|prjef}\" &>/dev/null; unset prjef; return 1" INT

Replace the prj* prefix with your project name, e.g.: rustef for a rust-related plugin. The *ef stands for "entry functions". The snippet works as follows:

The line prjef=( ${(k)functions} ) remembers all the functions that are currently defined – which means that the list excludes the functions that are to be yet defined by the body of the main function.
The code unset -f — "${(k)functions[@]:|prjef}" first does a subtraction of array contents – the :| substitution operator – of the functions that are defined at the moment of leaving of the function (the trap-s invoke the code in this moment) with the list of functions from the start of the main function – the ones stored in the variables $prjef.
It then unsets the resulting list of the functions – being only the newly defined functions in the main function – by passing it to unset -f ….

This way the functions defined by the body of the main (most often an autoload) function will be only set during the execution of the function.

Preventing Parameter Pollution

When writing a plugin one often needs to keep a state during the Zsh session. To do this it is natural to use global parameters. However, when the number of the parameters grows one might want to limit it.

With the following method, only a single global parameter per plugin can be sufficient:

typeset -A PlgMap
typeset -A SomeMap
typeset -a some_array

# Use

PlgMap[state]=1
SomeMap[state]=1
some_array[1]=state

can be converted into:

typeset -A PlgMap

# Use

PlgMap[state]=1
PlgMap[SomeMap__state]=1
PlgMap[some_array__1]=state

The use of this method is very unproblematic.

The author reduced the number of global parameters in one of the projects by 21 by using an automatic conversion with Vim substitution patterns with backreferences without any problems.

Following the Standard Plugins Hash section, the plugin could even use a common hash name – Plugins – to lower the pollution even more.
patterns with backreferences without any problems.

Following the Standard Plugins Hash section, the plugin could even use a common hash name – Plugins – to lower the pollution even more.

⚙️ ❮ ZBrowse ❯

Sall — Sat, 19 Feb 2022 20:17:55 +0000

https://z.digitalclouds.dev | GitHub | Twitter

When doing shell work, it is often the case that echo $variable is invoked multiple times, to check result of a loop, etc. With ZBrowse, you just need to press Ctrl-B, which invokes the ZBrowse – Zshell variable browser:

(you can resize the video like any web page)

Install zbrowse

First install the ZUI plugin (it's an UI library).

The plugin is "standalone", which means that only sourcing it is needed. So to install, unpack zbrowse somewhere and add

source {where-zbrowse-is}/zbrowse.plugin.zsh

to zshrc.

If using a plugin manager, then ZI is recommended, but you can use any other too, and also install with Oh My Zsh (by copying directory to ~/.oh-my-zsh/custom/plugins).

ZI

Add zi load z-shell/zbrowse to your .zshrc file. ZI will handle cloning the plugin for you automatically the next time you start zsh. To update run zi update z-shell/zbrowse (update-all can also be used).

Antigen

Add antigen bundle z-shell/zbrowse to your .zshrc file. Antigen will handle cloning the plugin for you automatically the next time you start zsh.

Oh-My-Zsh

cd ~/.oh-my-zsh/custom/plugins
git clone git@github.com:z-shell/zbrowse.git
Add zbrowse to your plugin list

Zgen

Add zgen load z-shell/zbrowse to your .zshrc file in the same place you're doing your other zgen load calls.

⚙️ ❮ ZI Crasis ❯

Sall — Sat, 19 Feb 2022 13:41:02 +0000

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

Introduction
Installation & Basic Use
Key Bindings
Screenshots
Code Documentation

Introduction

Crasis – semigraphical interface to ZI

Zsh exposes its parser via (z) substitution flag.

Parsing .zshrc is totally possible.

This way Crasis lets you edit your ZI commands located in .zshrc.

All in pure Zshell code.

No more commenting-out a line with a text editor to disable plugin, cluttering .zshrc, now you can just press a button.

Crasis uses pure-Zshell ZUI library to create ncurses interface.

Installation & Basic Use

Install ZI and add following commands to .zshrc:

zi light z-shell/zui
zi light z-shell/zi-crasis

To use, invoke crasis [optional zshrc path] or press Ctrl-o-k.

Global variables CRASIS_THEME and CRASIS_LAYOUT can be used to override configuration file crasis.conf (located in plugin's
tree), i.e.:

CRASIS_THEME="zdharma-256" CRASIS_LAYOUT="contract" crasis

256-color themes require Zsh 5.3 or later.

Key Bindings

Key(s)	Description
`<`,`>` or `{`,`}`	Horizontal scroll (i.e. left or right)
`Ctrl-L`	Redraw of whole display
`Ctrl-U`	Half page up
`Ctrl-D`	Half page down
`Ctrl-P`	Previous line, centered
`Ctrl-N`	Next line, centered
`[`, `]`	Jump to next and previous section (e.g. next plugin or snippet)
`g`, `G`	Jump to beginning and end of whole interface
`/`	Show incremental search
`F1`	Jump to result (in incremental search) and back
`Esc`	Exit incremental search, clearing query
`Ctrl-W`	Delete whole word (in incremental search)
`Ctrl-K`	Delete whole line (in incremental search)
Up and down	Resize text field when editing it (e.g. to make the text fit in)

Screenshots

Code Documentation

Crasis is a ZUI application.

ZUI is a pure-Zshell library where user generates simple text with hyperlinks, which is then turned into active document with buttons.

Check out Crasis code documentation: Asciidoc, PDF.

⚙️ ❮ ZConvey ❯

Sall — Sat, 19 Feb 2022 05:08:29 +0000

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

ZConvey integrates multiple Zsh sessions. They are given an ID, optionally a NAME (both unique), and can send commands to each other.

Use this to switch all your Zshells to given directory, via zc-all cd $PWD! Also, there's zc-bg-notify script (not a function), that will show notification under prompt of every active Zsh session.

You can call this script from any program, Bash or GUI.

Video – view on asciinema. You can resize the video by pressing Ctrl-+ or Cmd-+.

Zstyles for ZConvey values being set are the defaults. They must be set before loading the plugin.

zstyle ":plugin:zconvey" check_interval "2"         # How often to check if there are new commands (in seconds)
zstyle ":plugin:zconvey" expire_seconds "22"        # If shell is busy for 22 seconds, the received command will expire and not run
zstyle ":plugin:zconvey" greeting "logo"            # Display logo at Zsh start ("text" – display text, "none" – no greeting)
zstyle ":plugin:zconvey" ask "0"                    # zc won't ask for missing data ("1" has the same effect as always using -a option)
zstyle ":plugin:zconvey" ls_after_rename "0"        # Don't execute zc-ls after doing rename (with zc-rename or zc-take)
zstyle ":plugin:zconvey" use_zsystem_flock "1"      # Should use faster zsystem's flock when it's possible?
                                                    # (default true on Zsh >= 5.3, will revert to mixed zsystem/flock on older Zshells)
zstyle ":plugin:zconvey" output_method "feeder"     # To put commands on command line, ZConvey can use small program "feeder". Or "zsh"
                                                    # method, which currently doesn't automatically run the command – to use when e.g.
                                                    # feeder doesn't build (unlikely) or when occurring any problems with it
zstyle ":plugin:zconvey" timestamp_from "datetime"  # Use zsh/datetime module for obtaining timestamp. "date" – use date command (fork)

ZConvey commands

Command	Description
`zc`	Sends to other session; use "-a" option to be asked for target and a command to send
`zc-ls`	Lists all active and named sessions
`zc-id`	Shows ID and NAME of current session
`zc-all`	The same as `zc`, but targets are all other active sessions (with `-f` also busy sessions)
`zc-take`	Takes a name for current or selected sessions, schematically renames any conflicting sessions
`zc-logo`	The same as `zc-id`, but in a form of an on-screen logo; bound to Ctrl-O Ctrl-I
`zc-rename`	Assigns name to current or selected session; won't rename if there's a session with the same name
`zc-bg-notify`	In subdirectory `cmds`, link it to `/usr/local/bin`, etc. or load with e.g. ZI

The main command is zc (yet it is rather rarely used, I'm always sending to all sessions with zc-all). It is used to execute commands on other sessions. zc-ls is the main tool to obtain overall information on sessions. zc-take is a nice rename tool to quickly name a few sessions. Keyboard shortcut Ctrl-O Ctrl-I will show current session's ID and NAME in form of an on-screen logo.

Install ZConvey with ZI

Add zi load z-shell/zconvey to your .zshrc file. ZI will clone the plugin the next time you start zsh. To update issue zi update z-shell/zconvey.

ZI can load in turbo-mode, below is an example configuration.

zi ice wait"0"
zi light z-shell/zconvey

Adding zc-bg-notify to $PATH:

zi ice wait"0" as"command" pick"cmds/zc-bg-notify" silent
zi light z-shell/zconvey

Manual ZConvey installation

The plugin is "standalone", which means that only sourcing it is needed. So to install, unpack zconvey somewhere and add

source {where-zconvey-is}/zconvey.plugin.zsh

to zshrc.

If using a plugin manager, then ZI is recommended, but you can use any other too, and also install with Oh My Zsh (by copying directory to ~/.oh-my-zsh/custom/plugins).

The plugin integrates with my other plugin Zsh-Select. Install it with e.g. ZI to be able to use -a option for zc command.

⚙️ ❮ Zsh Select ❯

Sall — Sat, 19 Feb 2022 03:29:02 +0000

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

A shell command that will display selection list.

It is similar to selecta, but uses curses library to do display, and when compared to fzf, the main difference is approximate matching instead of fuzzy matching.

It is written in Zshell and has it's capabilities:

patterns, allowing multi-term searching
curses module
approximate matching (Ctrl-F)

The file zsh-select can be copied to any bin directory.

Zsh will serve as say Ruby, and zsh-select will be a regular program available
in system.

Pressing o will make elements uniqe.
To search again after pressing enter, press /. Approximate matching mode is activated by Ctrl-F.

Video: asciinema. You can resize the video by pressing Ctrl-+ or Cmd-+.

Installation

Simply copy file zsh-select to any bin directory such as /usr/local/bin.

The package is also available as plugin. zsh-select will be available in interactive Zsh sessions only when using this method.

Nevertheless, integration with Vim and other uses will simply work when Zsh is your main shell.

Also, plugin managers often allow easy updates.

Integration with Vim

Adding following snippet to vimrc will provide \f keyboard shortcut that will run zsh-select as file-selector.

Multi-term searching and approximate matching
(Ctrl-F) will be available.

The snippet is based on code from selecta github page (MIT license):

" Run a given vim command on the results of fuzzy selecting from a given shell" command. See usage below.

function! ZshSelectCommand(choice_command, zshselect_args, vim_command)
  try
    let selection = system(a:choice_command . " | zsh-select " . a:zshselect_args)
  catch /Vim:Interrupt/
    " Swallow the ^C so that the redraw below happens; otherwise there will be
    " leftovers from zshselect on the screen
    redraw!
    return
  endtry
  redraw!
  exec a:vim_command . " " . selection
endfunction

" Find all files in all non-dot directories starting in the working directory.
" Fuzzy select one of those. Open the selected file with :e.
nnoremap <leader>f :call ZshSelectCommand("find * -type f 2>/dev/null", "", ":e")<cr>

Configuring

There are a few environment variables that can be set to alter Zsh-Select behavior.

Values assigned below are the defaults:

export ZSHSELECT_BOLD="1"                   
# The interface will be drawn in bold font. Use "0" for no bold
export ZSHSELECT_COLOR_PAIR="white/black"   
# Draw in white foreground, black background. Try e.g.: "white/green"
export ZSHSELECT_BORDER="0"                 
# No border around interface, Use "1" for the border
export ZSHSELECT_ACTIVE_TEXT="reverse"      
# Mark current element with reversed text. Use "underline" for marking with underline
export ZSHSELECT_START_IN_SEARCH_MODE="1"   
# Starts Zsh-Select with searching active. "0" will not invoke searching at start.

Use with plugin managers

ZI

Add zi load z-shell/zsh-select to .zshrc.

The plugin will be loaded next time you start Zsh.

To update issue zi update z-shell/zsh-select from command line.

Zgen

Add zgen load z-shell/zsh-select to .zshrc and issue a zgen reset (this assumes that there is a proper zgen save construct in .zshrc).

Antigen

Add antigen bundle z-shell/zsh-select to .zshrc.

There also should be antigen apply.

⚙️ ❮ Zsh-Py3-HTTP ❯ | Auto Spawned service

Sall — Wed, 16 Feb 2022 18:59:11 +0000

❮ ZI ❯ Service - Py3HTTP

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

This Zsh service-plugin will serve given directory (plugin's directory by default) using Python's 3 HTTP server.

Install with ❮ ZI ❯

The service-plugin supports loading single plugin instance per all active Zsh sessions, in background.

zi ice service'py3http'
zi light z-shell/zservice-py3http

Explanation of Zsh-spawned services

First Zsh instance that will gain a lock will spawn the service.
Other Zsh instances will wait.
When you close the initial Zsh session, another Zsh will gain lock and resume the service.

⚙️ ❮ Zsh Unique ID ❯

Sall — Tue, 15 Feb 2022 20:03:25 +0000

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

This plugin provides a unique number that identifies a running Zshell session, in its shell variable $ZUID_ID.

Besides this unique number, also a unique codename is provided, in shell variable $ZUID_CODENAME.

Once you load this plugin, the two parameters will be set, and their values will not be available to other Zshell sessions (being thus unique).

$ZUID_ID is a progressing number starting from 1.

$ZUID_CODENAME is chosen from a list of predefined codenames, see the default list below.

An example use case is to hold logs in files .../mylog-${ZUID_CODENAME}.log,

so that two different Zshells will not write to the same file at the same time.

Default codenames are:

atlantis (for ZUID_ID == 1)
echelon (for ZUID_ID == 2)
quantum (etc.)
ion
proxima
polaris
solar
momentum
hyper
gloom
velocity
future
enigma
andromeda
saturn
jupiter
aslan
commodore
falcon
persepolis
dharma
samsara
prodigy
ethereal
epiphany
aurora
oblivion

Zstyle configuration allows to customize the codenames:

zstyle :plugin:zuid codenames paper metal wood plastic # first 4 shells will have those codenames

Install Zsh Unique ID

The plugin is "standalone", which means that only sourcing it is needed (without using a plugin manager).

So to install, unpack zsh-unique-id somewhere and add:

source {where-zsh-unique-id-is}/zsh-unique-id.plugin.zsh

to zshrc.

Sourcing is recommended, because it can be done early,
at top of zshrc, without a plugin manager – to acquire the unique identification as early as possible.

With ZI

Add zi load z-shell/zsh-unique-id to your .zshrc file. ZI will clone the plugin the next time you start zsh.

To update issue zi update z-shell/zsh-unique-id.

With Antigen

Add antigen bundle z-shell/zsh-unique-id to your .zshrc file.

Antigen will handle cloning the plugin for you automatically the next time you start zsh.

With Oh-My-Zsh

cd ~/.oh-my-zsh/custom/plugins
git clone git@github.com:z-shell/zsh-unique-id.git
Add zsh-unique-id to your plugin list.

With Zgen

Add zgen load z-shell/zsh-unique-id to your .zshrc file in the same place you're doing your other zgen load calls in.

⚙️ ❮ ZI + Diff-so-Fancy ❯ | Git

Sall — Tue, 15 Feb 2022 13:57:24 +0000

❮ ZI + Diff-so-Fancy ❯

https://z.digitalclouds.dev | GitHub | Twitter | Join the team

The project so-fancy/diff-so-fancy integration with ZI.

With this ZI plugin, you simply add two lines to .zshrc:

zi ice as"program" pick"bin/git-dsf"
zi light z-shell/zsh-diff-so-fancy

This will install diff-so-fancy on every account where you use Zshell, and automatically equip git with subcommand dsf. No need to use system package manager and to configure git. Of course, if you have the following standard line in your .gitconfig, it will still work normally:

[core]
pager = diff-so-fancy | less -FXRi

(because this plugin adds diff-so-fancy to $PATH).

Think about Puppet or Chef, i.e. about declarative approach to system configuration.

In this case .zshrc is like a declarative setup guarding you will have diff-so-fancy
on your accounts.

A Few Details

so-fancy/diff-so-fancy is cloned from
Github as submodule. The plugin has bin/git-dsf script which adds subcommand dsf
to git.

That's basically everything needed: convenient way of installing (single Zsh
plugin manager invocation), updating (Zsh plugin managers can easily update) and
integrating with git.

Other plugin managers

Zplug

zplug "z-shell/zsh-diff-so-fancy", as:command, use:"bin/"

Zgen

zgen load z-shell/zsh-diff-so-fancy

Without as"program"-like functionality the .plugin.zsh file picks up setup and simulates adding a command to system, so Zgen and other can work.

@zshell_zi, z.digitalclouds.dev

DEV Community: Sall

✨〰️Feature-rich Syntax Highlighting〰️✨

Fast-Syntax-Highlighting Themes

Recursive fast-syntax-highlighting, highlights code passed to sh -c

Variables

Brackets

Conditions

Strings

here-strings

exec descriptor-variables

for-loops and alternate syntax (brace {/} blocks)

Function definitions

Recursive eval and $( ) highlighting

Chroma functions

Math-mode highlighting

Zcalc highlighting

Performance

Installation

Manual

ZI

✨〰️A Swiss Army Knife for Zsh〰️Unix Shell〰️✨

❮ ZI ❯ 🧙‍‍♀️ A Swiss Army Knife for Zsh.

⚡️ Fast and feature-rich

☑️ Neat and flexible

📈 Familiarize and control

✨〰️ ZI 〰️✨ Vim Syntax

❮ ZI ❯ 🧙‍‍♀️ A Swiss Army Knife for Zsh.

📥 Installation

📕 Manual Installation

✍️ Examples

⚙️ ❮ ZSH Native Scripting Handbook ❯

Information

@ is about keeping array form

extended_glob

Constructs

Reading a file

Reading from stdin

Skipping dirname basename

Resolve Symlinks

Skipping grep

Multi-line matching like with grep

Pattern matching in AND-fashion

Skipping tr

Ternary expressions with +,-,:+,:- substitutions

Ternary expressions with :# substitution

Using built-in regular expressions engine

Skipping uniq

Skipping awk

Searching arrays

Code execution in // substitution

Serializing data

Tip: serializing with Bash

Real-world examples

Testing for Git subcommand

Counting unquoted-only apostrophes

Tips and Tricks

Parsing INI file

⚙️ ❮ ZSH Plugin Standard ❯

What Is A Zsh Plugin?

1. Standardized $0 Handling

Adopted [ zero-handling ]

2. Functions Directory

Adopted [ functions-directory ]

3. Binaries Directory

Adopted [ binaries-directory ]

4. Unload Function

Adopted [ unload-function ]

5. @zsh-plugin-run-on-unload Call

Adopted [ run-on-unload-call ]

6. @zsh-plugin-run-on-update Call

Adopted [ run-on-update-call ]

7. Plugin Manager Activity Indicator

Adopted [ activity-indicator ]

8. Global Parameter With PREFIX For Make, Configure, Etc

Adopted [ global-parameter-with-prefix ]

9. Global Parameter holding the plugin manager’s capabilities

Adopted [ global-parameter-with-capabilities ]

Zsh Plugin-Programming Best practices

Use Of add-zsh-hook To Install Hooks

Use Of add-zle-hook-widget To Install Zle Hooks

`exec` descriptor-variables

for-loops and alternate syntax (brace `{`/`}` blocks)

Recursive `eval` and `$( )` highlighting

Ternary expressions with `+,-,:+,:-` substitutions

Ternary expressions with `:#` substitution

Code execution in `//` substitution

1. Standardized `$0` Handling

5. `@zsh-plugin-run-on-unload` Call

6. `@zsh-plugin-run-on-update` Call

Use Of `add-zsh-hook` To Install Hooks

Use Of `add-zle-hook-widget` To Install Zle Hooks

Standard `Plugins` Hash