feat: re-format zi help & ice --help messages

- lists available ices via `zi ice [-h/-help]` - remove verbiage in `zi help` to improve readability - fix broken formatting of `times` in `zi help` - sort commands alphabetically in `zi help` message Signed-off-by: Doster, Vladislav <[email protected]>
zdharma-continuum · Jun 16, 2023 · d0d5a81 · d0d5a81
1 parent 1cb1df6
commit d0d5a81
Show file tree

Hide file tree

Showing 11 changed files with 378 additions and 400 deletions.
diff --git a/_zinit b/_zinit
@@ -36,6 +36,7 @@ __zinit_commands(){
     'env-whitelist:Specify names (also patterns) of parameters to be left unchanged during an unload'
     'glance:Look at plugins source'
     'help:Usage information'
+    'ice:Set ice'
     'load:Load plugin'
     'man:Display Zinit'\''s manpage'
     'module:Manage binary Zsh module shipped with Zinit'
@@ -236,6 +237,11 @@ _zinit_env_whitelist(){
 _zinit_glance(){
   _arguments - installed '1:installed:__zinit_installed' && ret=0
 } # ]]]
+# FUNCTION: _zinit_ice [[[
+_zinit_ice(){
+  _arguments -A \
+    '(-h --help)'{-h,--help}'[Print usage]' && ret=0
+} # ]]]
 # FUNCTION: _zinit_list [[[
 _zinit_list(){
   _message 'Hit enter to list the defined key bindings replay' && ret=0
@@ -279,7 +285,7 @@ _zinit_snippet(){
   _arguments -A \
     '(-c --command)'{-c,--command}'[Load the snippet as a command (i.e., make executable and apend to $PATH])' \
     '(-f --force)'{-f,--force}'[Force new download of the snippet file]' \
-    '(-h --help)'{-h,--help}'[Show this help message]'
+    '(-h --help)'{-h,--help}'[Print usage]'
   _arguments - snippet '*::snippet:__zinit_installed_snippets' && ret=0
 } # ]]]
 # FUNCTION: _zinit_status [[[

diff --git a/doc/zsdoc/_zinit.adoc b/doc/zsdoc/_zinit.adoc
diff --git a/doc/zsdoc/zinit-autoload.zsh.adoc b/doc/zsdoc/zinit-autoload.zsh.adoc
@@ -796,7 +796,7 @@ ____
 
 ____
 
-Has 64 line(s). Doesn't call other functions.
+Has 66 line(s). Doesn't call other functions.
 
 Called by:
 

diff --git a/doc/zsdoc/zinit-install.zsh.adoc b/doc/zsdoc/zinit-install.zsh.adoc
@@ -302,10 +302,10 @@ Has 195 line(s). Calls functions:
  |-- .zinit-download-file-stdout
  |   `-- zinit.zsh/+zinit-message
  |-- .zinit-jq-check
- |   `-- zinit.zsh/+zinit-message
+ |   `-- zinit.zsh/+zi-log
  |-- .zinit-json-to-array
  |   `-- .zinit-jq-check
- |       `-- zinit.zsh/+zinit-message
+ |       `-- zinit.zsh/+zi-log
  |-- ziextract
  |   `-- zinit.zsh/+zinit-message
  |-- zinit.zsh/+zinit-message
@@ -379,10 +379,10 @@ ____
 
 ____
 
-Has 8 line(s). Calls functions:
+Has 3 line(s). Calls functions:
 
  .zinit-jq-check
- `-- zinit.zsh/+zinit-message
+ `-- zinit.zsh/+zi-log
 
 Called by:
 
@@ -405,7 +405,7 @@ Has 4 line(s). Calls functions:
 
  .zinit-json-get-value
  `-- .zinit-jq-check
-     `-- zinit.zsh/+zinit-message
+     `-- zinit.zsh/+zi-log
 
 Not called by script or any function (may be e.g. a hook, a Zle widget, etc.).
 
@@ -426,7 +426,7 @@ Has 13 line(s). Calls functions:
 
  .zinit-json-to-array
  `-- .zinit-jq-check
-     `-- zinit.zsh/+zinit-message
+     `-- zinit.zsh/+zi-log
 
 Uses feature(s): _eval_, _setopt_
 

diff --git a/doc/zsdoc/zinit.zsh.adoc b/doc/zsdoc/zinit.zsh.adoc
@@ -110,6 +110,8 @@ Has 244 line(s). Calls functions:
  |   |-- .zinit-get-object-path
  |   |   `-- .zinit-any-to-user-plugin
  |   |-- .zinit-ice
+ |   |   `-- +zi-log
+ |   |       `-- +zinit-message
  |   |-- .zinit-load-ices
  |   |   `-- .zinit-get-object-path
  |   |       `-- .zinit-any-to-user-plugin
@@ -225,6 +227,7 @@ Has 1 line(s). Calls functions:
 
 Called by:
 
+ .zinit-ice
  zinit-additional.zsh/.zinit-debug-clear
  zinit-additional.zsh/.zinit-debug-report
  zinit-additional.zsh/.zinit-debug-revert
@@ -233,6 +236,7 @@ Called by:
  zinit-additional.zsh/.zinit-debug-stop
  zinit-additional.zsh/:zinit-tmp-subst-source
  zinit-autoload.zsh/.zinit-unload
+ zinit-install.zsh/.zinit-jq-check
 
 ==== +zinit-deploy-message
 
@@ -300,7 +304,6 @@ Called by:
  zinit-install.zsh/.zinit-get-latest-gh-r-url-part
  zinit-install.zsh/.zinit-get-package
  zinit-install.zsh/.zinit-install-completions
- zinit-install.zsh/.zinit-jq-check
  zinit-install.zsh/.zinit-setup-plugin-dir
  zinit-install.zsh/.zinit-update-snippet
  zinit-install.zsh/ziextract
@@ -690,9 +693,13 @@ ____
 
 ____
 
-Has 13 line(s). Doesn't call other functions.
+Has 32 line(s). Calls functions:
 
-Uses feature(s): _setopt_
+ .zinit-ice
+ `-- +zi-log
+     `-- +zinit-message
+
+Uses feature(s): _setopt_, _zmodload_, _zparseopts_
 
 Called by:
 
@@ -1600,10 +1607,11 @@ ____
  
  Entrypoint function directly exposed to user, consumes subcommands with respective arguments,
  and completion.
+ 
 
 ____
 
-Has 553 line(s). Calls functions:
+Has 527 line(s). Calls functions:
 
  zinit
  |-- +zinit-message
@@ -1618,6 +1626,8 @@ Has 553 line(s). Calls functions:
  |-- .zinit-get-object-path
  |   `-- .zinit-any-to-user-plugin
  |-- .zinit-ice
+ |   `-- +zi-log
+ |       `-- +zinit-message
  |-- .zinit-load-ices
  |   `-- .zinit-get-object-path
  |       `-- .zinit-any-to-user-plugin
@@ -1776,6 +1786,8 @@ Has 1 line(s). Calls functions:
      |-- .zinit-get-object-path
      |   `-- .zinit-any-to-user-plugin
      |-- .zinit-ice
+     |   `-- +zi-log
+     |       `-- +zinit-message
      |-- .zinit-load-ices
      |   `-- .zinit-get-object-path
      |       `-- .zinit-any-to-user-plugin

diff --git a/tests/commands.zunit b/tests/commands.zunit
@@ -15,6 +15,19 @@
   assert $output contains 'zinit delete [options] [plugins...]'
   assert $state equals 0
 }
+@test 'zinit help' {
+  for cmd in '-h' '--help' 'help'; do
+    run zinit $cmd
+    assert $output contains 'Usage: zinit [OPTIONS] COMMAND'
+    assert $state equals 0
+  done
+}
+@test 'ice --help' {
+  run zinit ice --help
+  assert $output contains 'Usage: zinit ice [-h|--help] [args ...]'
+  assert $output contains 'Available ice-modifiers:'
+  assert $state equals 0
+}
 @test 'delete --all' {
   run zinit as'completion' is-snippet for @'https://github.com/docker/cli/blob/master/contrib/completion/zsh/_docker'
   assert $state equals 0

diff --git a/tests/gh-r.zunit b/tests/gh-r.zunit
@@ -282,7 +282,7 @@
   $gh_cli --version; assert $state equals 0
 }
 @test 'gh-hub' { # A command-line tool that makes git easier to use with GitHub
-  run zinit cp"hub-*/etc/hub.zsh_completion -> _hub" for @mislav/hub; assert $state equals 0
+  run zinit cp"hub-*/etc/hub.zsh_completion -> _hub" for @github/hub; assert $state equals 0
   local hub="$ZBIN/hub"; assert "$hub" is_executable
   $hub --version; assert $state equals 0
 }

diff --git a/tests/ices.zunit b/tests/ices.zunit
@@ -51,15 +51,5 @@
   assert "$ZPLUGINS/test---completions-overwrite/_whatever2" is_file
   assert "$ZINIT[COMPLETIONS_DIR]/_whatever2" is_file
 }
-@test 'completions-ignored' {
-  # only the _valid file should be installed as a completion
-  run zinit as"null" id-as"test/ignored_completions" atclone"touch __init__.py _valid" completions for zdharma-continuum/null
-  assert $state equals 0
-  assert "$ZPLUGINS/test---ignored_completions/_valid" is_file
-  assert "$ZPLUGINS/test---ignored_completions/__init__.py" is_file
-  assert "$ZINIT[COMPLETIONS_DIR]/_valid" is_file
-  COMPS=( "$ZINIT[COMPLETIONS_DIR]"/_* )
-  assert __init__.py is_not_value_in $COMPS
-}
 
 # vim:ft=zsh:sw=2:sts=2:et:foldmarker=\ {,}:foldmethod=marker
diff --git a/zinit-autoload.zsh b/zinit-autoload.zsh
@@ -1413,53 +1413,55 @@ EOF
 #
 # User-action entry point.
 .zinit-help() {
-           builtin print -r -- "${ZINIT[col-p]}Usage${ZINIT[col-rst]}:
-—— help                          – usage information
-—— bindkeys                      – lists bindkeys set up by each plugin
-—— cd ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}                   – cd into plugin's directory; also support snippets, if feed with URL
-—— cdclear [-q]                  – clear compdef replay list, -q – quiet
-—— cdisable ${ZINIT[col-info]}cname${ZINIT[col-rst]}                – disable completion \`cname'
-—— cdlist                        – show compdef replay list
-—— cdreplay [-q]                 – replay compdefs (to be done after compinit), -q – quiet
-—— cenable ${ZINIT[col-info]}cname${ZINIT[col-rst]}                 – enable completion \`cname'
-—— changes ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}              – view plugin's git log
-—— clist|completions             – list completions in use
-—— compile ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}              – compile plugin (or all plugins if ——all passed)
-—— compiled                      – list plugins that are compiled
-—— compinit                      – refresh installed completions
-—— create ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}               – create plugin (also together with Github repository)
-—— creinstall ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}           – install completions for plugin, can also receive absolute local path; -q – quiet
-—— csearch                       – search for available completions from any plugin
-—— cuninstall ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}           – uninstall completions for plugin
-—— debug                         – manage debug mode
-—— delete                        – delete a plugin or snippet
-—— edit ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}                 – edit plugin's file with \$EDITOR
-—— env-whitelist [-v|-h] {env..} – allows to specify names (also patterns) of variables left unchanged during an unload. -v – verbose
-—— glance ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}               – look at plugin's source (pygmentize, {,source-}highlight)
-—— ice <ice specification>       – add ICE to next command, argument is e.g. from\"gitlab\"
-—— light [-b] ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}           – light plugin load, without reporting/tracking (-b – do track but bindkey-calls only)
-—— load ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}                 – load plugin, can also receive absolute local path
-—— loaded|list {keyword}         – show what plugins are loaded (filter with \'keyword')
-—— ls                            – list snippets in formatted and colorized manner
-—— man                           – manual
-—— module                        – manage binary Zsh module shipped with Zinit, see \`zinit module help'
-—— recall ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}|URL           – fetch saved ice modifiers and construct \`zinit ice ...' command
-—— recently ${ZINIT[col-info]}[time-spec]${ZINIT[col-rst]}          – show plugins that changed recently, argument is e.g. 1 month 2 days
-—— report ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}               – show plugin's report (or all plugins' if ——all passed)
-—— self-update                   – updates and compiles Zinit
-—— snippet [-f] ${ZINIT[col-pname]}{url}${ZINIT[col-rst]}            – source local or remote file (by direct URL), -f: force – don't use cache
-—— srv {service-id} [cmd]        – control a service, command can be: stop,start,restart,next,quit; \`next' moves the service to another Zshell
-—— status ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}|URL           – Git status for plugin or svn status for snippet (or for all those if ——all passed)
-—— stress ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}               – test plugin for compatibility with set of options
-—— times [-s] [-m] [-a] – statistics on plugin load times, sorted in order of loading; -s – use seconds instead of milliseconds, -m – show plugin loading moments, -a – show both load times and loading moments
-—— uncompile ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}            – remove compiled version of plugin (or of all plugins if ——all passed)
-—— unload ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}               – unload plugin loaded with \`zinit load ...', -q – quiet
-—— update [-q] ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]}|URL      – Git update plugin or snippet (or all plugins and snippets if ——all passed); besides -q accepts also ——quiet, and also -r/--reset – this option causes to run git reset --hard / svn revert before pulling changes
-—— version                       – display zinit version
-—— zstatus                       – overall Zinit statu
-—— add-fpath|fpath ${ZINIT[col-info]}[-f|--front]${ZINIT[col-rst]} \\
-    ${ZINIT[col-pname]}plg-spec ${ZINIT[col-info]}[subdirectory]${ZINIT[col-rst]}      – adds given plugin directory to \$fpath; if the second argument is given, it is appended to the directory path; if the option -f/--front is given, the directory path is prepended instead of appended to \$fpath. The ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]} can be absolute path
-—— run [-l] [plugin] {command}   – runs the given command in the given plugin's directory; if the option -l will be given then the plugin should be skipped – the option will cause the previous plugin to be reused"
+    local -a usage_message=(
+        "Usage: zinit [OPTIONS] COMMAND"
+        ""
+        "Zinit is a plugin management system for zsh."
+        ""
+        "Commands:"
+        "  bindkeys         Lists bindkeys set up by each plugin"
+        "  cd               Change directory to a plugin or snippet"
+        "  cdclear          Clear compdef replay list"
+        "  cdisable         Disable completion"
+        "  cdlist           Show compdef replay list"
+        "  cdreplay         Replay compdefs"
+        "  cenable          Enable completion"
+        "  changes          View plugin's git log"
+        "  compile          Compile plugin"
+        "  compiled         List plugins that are compiled"
+        "  compinit         Refresh installed completions"
+        "  completions      List completions in use"
+        "  create           Create plugin (also together with Github repository)"
+        "  creinstall       Install a plugin or local completion"
+        "  csearch          Search for available completions from any plugin"
+        "  cuninstall       Uninstall completions for plugin"
+        "  debug            Manage debug mode"
+        "  delete           Delete a plugin or snippet"
+        "  edit             Edit plugin's file with \$EDITOR"
+        "  glance           Look at plugin's source"
+        "  help             Usage information"
+        "  ice              Add ICE to next command"
+        "  light            Light plugin load, without reporting/tracking"
+        "  load             Load plugin, can also receive absolute local path"
+        "  man              Manual"
+        "  module           Manage binary zsh module shipped with zinit"
+        "  plugins          List currently installed plugins"
+        "  recall           Fetch saved ice modifiers and construct 'zinit ice ...' command"
+        "  recently         Show plugins that changed recently"
+        "  report           Show plugin's report"
+        "  self-update      Update zinit"
+        "  snippet          Source local or remote file (by direct URL)"
+        "  snippets         List currently installed snippets"
+        "  status           Git status for plugin or svn status for snippet"
+        "  stress           Test plugin for compatibility with set of options"
+        "  times            Statistics on plugin load times, sorted in order of loading"
+        "  uncompile        Remove compiled version of plugin"
+        "  unload           Unload plugin"
+        "  update           Update a plugin or snippet"
+        "  version          Display zinit version"
+        "  zstatus          Overall zinit status"
+    )
+    builtin print -l -- $usage_message
 
     integer idx
     local type key
@@ -1474,9 +1476,9 @@ EOF
         done
     done
 
-local -a ice_order
-ice_order=( ${${(s.|.)ZINIT[ice-list]}:#teleid} ${(@)${(@)${(@Akons:|:u)${ZINIT_EXTS[ice-mods]//\'\'/}}/(#s)<->-/}:#(.*|dynamic-unscope)} )
-print -- "\nAvailable ice-modifiers:\n\n${ice_order[*]}"
+    print -- "Run 'zinit COMMAND --help' for more information on a command."
+    print -- ''
+    print -- "For more help on how to use Zinit, head to https://github.com/zdharma_continuum/zinit'."
 } # ]]]
 
 # FUNCTION: .zinit-list-bindkeys [[[

diff --git a/zinit-install.zsh b/zinit-install.zsh
@@ -12,12 +12,7 @@ builtin source "${ZINIT[BIN_DIR]}/zinit-side.zsh" || {
 # that's not the case
 .zinit-jq-check() {
     command -v jq >/dev/null && return 0
-
-    +zinit-message "{error}❌ ERROR: jq binary not found" \
-        "{nl}{u-warn}Please install jq:{rst}" \
-        "https://github.com/jqlang/jq" \
-        "{nl}{u-warn}To do so with zinit, please refer to:{rst}" \
-        "https://github.com/zdharma-continuum/zinit/wiki/%F0%9F%A7%8A-Recommended-ices#jq"
+		+zi-log '{e} Missing required dependency {cmd}jq{rst}. Please install it.'
     return 1
 } # ]]]
 # FUNCTION: .zinit-json-get-value [[[
@@ -554,8 +549,8 @@ builtin source "${ZINIT[BIN_DIR]}/zinit-side.zsh" || {
     local c cfile bkpfile
     # The plugin == . is a semi-hack/trick to handle 'creinstall .' properly
     [[ $user == % || ( -z $user && $plugin == . ) ]] && \
-        completions=( "${plugin}"/**/_[^_.]*~*(*.zwc|*.html|*.txt|*.png|*.jpg|*.jpeg|*.js|*.md|*.yml|*.yaml|*.py|*.ri|_zsh_highlight*|/zsdoc/*|*.ps1)(DN^/) ) || \
-        completions=( "${ZINIT[PLUGINS_DIR]}/${id_as//\//---}"/**/_[^_.]*~*(*.zwc|*.html|*.txt|*.png|*.jpg|*.jpeg|*.js|*.md|*.yml|*.yaml|*.py|*.ri|_zsh_highlight*|/zsdoc/*|*.ps1)(DN^/) )
+        completions=( "${plugin}"/**/_[^_.]*~*(*.zwc|*.html|*.txt|*.png|*.jpg|*.jpeg|*.js|*.md|*.yml|*.ri|_zsh_highlight*|/zsdoc/*|*.ps1)(DN^/) ) || \
+        completions=( "${ZINIT[PLUGINS_DIR]}/${id_as//\//---}"/**/_[^_.]*~*(*.zwc|*.html|*.txt|*.png|*.jpg|*.jpeg|*.js|*.md|*.yml|*.ri|_zsh_highlight*|/zsdoc/*|*.ps1)(DN^/) )
     already_symlinked=( "${ZINIT[COMPLETIONS_DIR]}"/_[^_.]*~*.zwc(DN) )
     backup_comps=( "${ZINIT[COMPLETIONS_DIR]}"/[^_.]*~*.zwc(DN) )
-Original file line number
+Diff line change
@@ Expand Up / @@ -796,7 +796,7 @@ ____ @@
     ____
-    Has 64 line(s). Doesn't call other functions.
+    Has 66 line(s). Doesn't call other functions.
     Called by:
@@ Expand Down @@