From: Daniel Shahaf <d.s@daniel.shahaf.name>
To: Pier Paolo Grassi <pierpaolog@gmail.com>
Cc: Zsh-Users List <zsh-users@zsh.org>
Subject: [PATCH] docs: Add an example of setting and querying zstyles (was: Re: problem with context specification)
Date: Mon, 13 Jan 2020 17:41:21 +0000 [thread overview]
Message-ID: <20200113174121.GA8678@tarpaulin.shahaf.local2> (raw)
In-Reply-To: <20200113170630.GA8134@tarpaulin.shahaf.local2>
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 1e35d2245..e556e2b37 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -17,18 +17,37 @@ item(tt(zstyle -m) var(context) var(style) var(pattern))(
This builtin command is used to define and lookup styles. Styles are
pairs of names and values, where the values consist of any number of
strings. They are stored together with patterns and lookup is done by
-giving a string, called the `context', which is compared to the
-patterns. The definition stored for the first matching pattern will be
-returned.
+giving a string, called the `em(context)', which is matched against the
+patterns. The definition stored for the most specific pattern that matches
+will be returned.
-For ordering of comparisons, patterns are searched from most specific to
-least specific, and patterns that are equally specific keep the order in
-which they were defined. A pattern is considered to be more specific
+A pattern is considered to be more specific
than another if it contains more components (substrings separated by
colons) or if the patterns for the components are more specific, where
simple strings are considered to be more specific than patterns and
complex patterns are considered to be more specific than the pattern
-`tt(*)'.
+`tt(*)'. A `tt(*)' in the pattern will match zero or more characters
+in the context; colons are not treated specially in this regard.
+If two patterns are equally specific, the tie is broken in favour of
+the pattern that was defined first.
+
+em(Example)
+
+For example, to define your preferred form of precipitation depending on which
+city you're in, you might set the following in your tt(zshrc):
+
+example(zstyle ':weather:europe:*' preferred-precipitation rain
+zstyle ':weather:europe:germany:* preferred-precipitation none
+zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow)
+
+Then, the fictional `tt(weather)' plugin might run under the hood a command
+such as
+
+example(zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY)
+
+in order to retrieve your preference into the scalar variable tt($REPLY).
+
+em(Usage)
The first form (without arguments) lists the definitions. Styles
are shown in alphabetic order and patterns are shown in the order
@@ -39,7 +58,7 @@ tt(zstyle). The optional first argument is a pattern which will be matched
against the string supplied as the pattern for the context; note that
this means, for example, `tt(zstyle -L ":completion:*")' will
match any supplied pattern beginning `tt(:completion:)', not
-just tt(":completion:*"): use tt(":completion:\*") to match that.
+just tt(":completion:*"): use tt(':completion:\*') to match that.
The optional second argument limits the output to a specific var(style) (not a
pattern). tt(-L) is not compatible with any other options.
next prev parent reply other threads:[~2020-01-13 17:42 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <CGME20200113164758eucas1p17ea364450eec705f49edaa8fb69fa65b@eucas1p1.samsung.com>
2020-01-13 16:46 ` problem with context specification Pier Paolo Grassi
2020-01-13 16:56 ` Peter Stephenson
2020-01-13 17:46 ` Mikael Magnusson
2020-01-14 11:52 ` Peter Stephenson
2020-01-13 17:53 ` Bart Schaefer
2020-01-13 17:06 ` Daniel Shahaf
2020-01-13 17:41 ` Daniel Shahaf [this message]
2020-01-14 15:59 ` Pier Paolo Grassi
2020-01-14 16:45 ` Daniel Shahaf
2020-01-14 17:55 ` Pier Paolo Grassi
2020-01-14 18:05 ` Peter Stephenson
2020-01-14 18:34 ` Bart Schaefer
2020-01-14 18:50 ` Daniel Shahaf
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200113174121.GA8678@tarpaulin.shahaf.local2 \
--to=d.s@daniel.shahaf.name \
--cc=pierpaolog@gmail.com \
--cc=zsh-users@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).