zsh: Other Functions

Previous: User Configuration Functions, Up: User Contributions [Contents][Index]

### 26.12 Other Functions

There are a large number of helpful functions in the `Functions/Misc` directory of the zsh distribution. Most are very simple and do not require documentation here, but a few are worthy of special mention.

#### 26.12.1 Descriptions

`colors`

  This function initializes several associative arrays to map color names to (and from) the ANSI standard eight-color terminal codes. These are used by the prompt theme system (Prompt Themes). You seldom should need to run `colors` more than once.

  The eight base colors are: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, and `white`. Each of these has codes for foreground and background. In addition there are seven intensity attributes: `bold`, `faint`, `standout`, `underline`, `blink`, `reverse`, and `conceal`. Finally, there are seven codes used to negate attributes: `none` (reset all attributes to the defaults), `normal` (neither bold nor faint), `no-standout`, `no-underline`, `no-blink`, `no-reverse`, and `no-conceal`.

  Some terminals do not support all combinations of colors and intensities.

  The associative arrays are:

  `color`
  `colour`

    Map all the color names to their integer codes, and integer codes to the color names. The eight base names map to the foreground color codes, as do names prefixed with ‘`fg-`’, such as ‘`fg-red`’. Names prefixed with ‘`bg-`’, such as ‘`bg-blue`’, refer to the background codes. The reverse mapping from code to color yields base name for foreground codes and the `bg-` form for backgrounds.

    Although it is a misnomer to call them ‘colors’, these arrays also map the other fourteen attributes from names to codes and codes to names.

  `fg`
  `fg_bold`
  `fg_no_bold`

    Map the eight basic color names to ANSI terminal escape sequences that set the corresponding foreground text properties. The `fg` sequences change the color without changing the eight intensity attributes.

  `bg`
  `bg_bold`
  `bg_no_bold`

    Map the eight basic color names to ANSI terminal escape sequences that set the corresponding background properties. The `bg` sequences change the color without changing the eight intensity attributes.

  In addition, the scalar parameters `reset_color` and `bold_color` are set to the ANSI terminal escapes that turn off all attributes and turn on bold intensity, respectively.

`fned` [ `-x` num ] name

  Same as `zed -f`. This function does not appear in the zsh distribution, but can be created by linking `zed` to the name `fned` in some directory in your `fpath`.

`is-at-least` needed [ present ]

  Perform a greater-than-or-equal-to comparison of two strings having the format of a zsh version number; that is, a string of numbers and text with segments separated by dots or dashes. If the present string is not provided, `$ZSH_VERSION` is used. Segments are paired left-to-right in the two strings with leading non-number parts ignored. If one string has fewer segments than the other, the missing segments are considered zero.

  This is useful in startup files to set options and other state that are not available in all versions of zsh.

      is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
      is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
      is-at-least 2.6-17 || print "You can't use is-at-least here."

`nslookup` [ arg ... ]

  This wrapper function for the `nslookup` command requires the `zsh/zpty` module (see The zsh/zpty Module). It behaves exactly like the standard `nslookup` except that it provides customizable prompts (including a right-side prompt) and completion of nslookup commands, host names, etc. (if you use the function-based completion system). Completion styles may be set with the context prefix ‘`:completion:nslookup`’.

  See also the `pager`, `prompt` and `rprompt` styles below.

`regexp-replace` var regexp replace

  Use regular expressions to perform a global search and replace operation on a variable. If the option `RE_MATCH_PCRE` is not set, POSIX extended regular expressions are used, else Perl-compatible regular expressions (this requires the shell to be linked against the `pcre` library).

  var is the name of the variable containing the string to be matched. The variable will be modified directly by the function. The variables `MATCH`, `MBEGIN`, `MEND`, `match`, `mbegin`, `mend` should be avoided as these are used by the regular expression code.

  regexp is the regular expression to match against the string.

  replace is the replacement text. This can contain parameter, command and arithmetic expressions which will be replaced: in particular, a reference to `$MATCH` will be replaced by the text matched by the pattern.

  The return status is 0 if at least one match was performed, else 1.

`run-help` cmd

  This function is designed to be invoked by the `run-help` ZLE widget, in place of the default alias. See ‘Accessing On-Line Help’ (Utilities) for setup instructions.

  In the discussion which follows, if cmd is a file system path, it is first reduced to its rightmost component (the file name).

  Help is first sought by looking for a file named cmd in the directory named by the `HELPDIR` parameter. If no file is found, an assistant function, alias, or command named `run-help-cmd` is sought. If found, the assistant is executed with the rest of the current command line (everything after the command name cmd) as its arguments. When neither file nor assistant is found, the external command ‘`man` cmd’ is run.

  An example assistant for the "ssh" command:

      run-help-ssh() {
          emulate -LR zsh
          local -a args
          # Delete the "-l username" option
          zparseopts -D -E -a args l:
          # Delete other options, leaving: host command
          args=(${@:#-*})
          if [[ ${#args} -lt 2 ]]; then
              man ssh
          else
              run-help $args[2]
          fi
      }

  Several of these assistants are provided in the `Functions/Misc` directory. These must be autoloaded, or placed as executable scripts in your search path, in order to be found and used by `run-help`.

  `run-help-git`
  `run-help-svk`
  `run-help-svn`

    Assistant functions for the `git`, `svk`, and `svn` commands.

`tetris`

  Zsh was once accused of not being as complete as Emacs, because it lacked a Tetris game. This function was written to refute this vicious slander.

  This function must be used as a ZLE widget:

      autoload -U tetris
      zle -N tetris
      bindkey keys tetris

  To start a game, execute the widget by typing the keys. Whatever command line you were editing disappears temporarily, and your keymap is also temporarily replaced by the Tetris control keys. The previous editor state is restored when you quit the game (by pressing ‘`q`’) or when you lose.

  If you quit in the middle of a game, the next invocation of the `tetris` widget will continue where you left off. If you lost, it will start a new game.

`tetriscurses`

  This is a port of the above to zcurses. The input handling is improved a bit so that moving a block sideways doesn’t automatically advance a timestep, and the graphics use unicode block graphics.

  This version does not save the game state between invocations, and is not invoked as a widget, but rather as:

      autoload -U tetriscurses
      tetriscurses

`zargs` [ option ... `-``-` ] [ input ... ] [ `-``-` command [ arg ... ] ]

  This function has a similar purpose to GNU xargs. Instead of reading lines of arguments from the standard input, it takes them from the command line. This is useful because zsh, especially with recursive glob operators, often can construct a command line for a shell function that is longer than can be accepted by an external command.

  The option list represents options of the `zargs` command itself, which are the same as those of `xargs`. The input list is the collection of strings (often file names) that become the arguments of the `command`, analogous to the standard input of `xargs`. Finally, the arg list consists of those arguments (usually options) that are passed to the command each time it runs. The arg list precedes the elements from the `input` list in each run. If no command is provided, then no arg list may be provided, and in that event the default command is ‘`print`’ with arguments ‘`-r -``-`’.

  For example, to get a long `ls` listing of all plain files in the current directory or its subdirectories:

      autoload -U zargs
      zargs -- **/*(.) -- ls -l

  Note that ‘`-``-`’ is used both to mark the end of the option list and to mark the end of the input list, so it must appear twice whenever the input list may be empty. If there is guaranteed to be at least one input and the first input does not begin with a ‘`-`’, then the first ‘`-``-`’ may be omitted.

  In the event that the string ‘`-``-`’ is or may be an input, the `-e` option may be used to change the end-of-inputs marker. Note that this does not change the end-of-options marker. For example, to use ‘`..`’ as the marker:

      zargs -e.. -- **/*(.) .. ls -l

  This is a good choice in that example because no plain file can be named ‘`..`’, but the best end-marker depends on the circumstances.

  The options `-i`, `-I`, `-l`, `-L`, and `-n` differ slightly from their usage in `xargs`. There are no input lines for `zargs` to count, so `-l` and `-L` count through the input list, and `-n` counts the number of arguments passed to each execution of command, including any arg list. Also, any time `-i` or `-I` is used, each input is processed separately as if by ‘`-L` `1`’.

  For details of the other `zargs` options, see man page xargs(1) (but note the difference in function between `zargs` and `xargs`) or run `zargs` with the `-``-help` option.

`zed` [ `-f` [ `-x` num ] ] name
`zed -b`

  This function uses the ZLE editor to edit a file or function.

  Only one name argument is allowed. If the `-f` option is given, the name is taken to be that of a function; if the function is marked for autoloading, `zed` searches for it in the `fpath` and loads it. Note that functions edited this way are installed into the current shell, but not written back to the autoload file. In this case the `-x` option specifies that leading tabs indenting the function according to syntax should be converted into the given number of spaces; ‘`-x 2`’ is consistent with the layout of functions distributed with the shell.

  Without `-f`, name is the path name of the file to edit, which need not exist; it is created on write, if necessary.

  While editing, the function sets the main keymap to `zed` and the vi command keymap to `zed-vicmd`. These will be copied from the existing `main` and `vicmd` keymaps if they do not exist the first time `zed` is run. They can be used to provide special key bindings used only in zed.

  If it creates the keymap, `zed` rebinds the return key to insert a line break and ‘`^X^W`’ to accept the edit in the `zed` keymap, and binds ‘`ZZ`’ to accept the edit in the `zed-vicmd` keymap.

  The bindings alone can be installed by running ‘`zed -b`’. This is suitable for putting into a startup file. Note that, if rerun, this will overwrite the existing `zed` and `zed-vicmd` keymaps.

  Completion is available, and styles may be set with the context prefix ‘`:completion:zed`’.

  A zle widget `zed-set-file-name` is available. This can be called by name from within zed using ‘`\ex zed-set-file-name`’ (note, however, that because of zed’s rebindings you will have to type `^j` at the end instead of the return key), or can be bound to a key in either of the `zed` or `zed-vicmd` keymaps after ‘`zed -b`’ has been run. When the widget is called, it prompts for a new name for the file being edited. When zed exits the file will be written under that name and the original file will be left alone. The widget has no effect with ‘`zed -f`’.

  While `zed-set-file-name` is running, zed uses the keymap `zed-normal-keymap`, which is linked from the main keymap in effect at the time zed initialised its bindings. (This is to make the return key operate normally.) The result is that if the main keymap has been changed, the widget won’t notice. This is not a concern for most users.

`zcp` [ `-finqQvwW` ] srcpat dest
`zln` [ `-finqQsvwW` ] srcpat dest

  Same as `zmv -C` and `zmv -L`, respectively. These functions do not appear in the zsh distribution, but can be created by linking `zmv` to the names `zcp` and `zln` in some directory in your `fpath`.

`zkbd`

  See ‘Keyboard Definition’ (Utilities).

`zmv` [ `-finqQsvwW` ] [ `-C` | `-L` | `-M` | -{`p`|`P`} program ] [ `-o` optstring ]
`` srcpat dest

  Move (usually, rename) files matching the pattern srcpat to corresponding files having names of the form given by dest, where srcpat contains parentheses surrounding patterns which will be replaced in turn by `$1`, `$2`, ... in dest. For example,

      zmv '(*).lis' '$1.txt'

  renames ‘`foo.lis`’ to ‘`foo.txt`’, ‘`my.old.stuff.lis`’ to ‘`my.old.stuff.txt`’, and so on.

  The pattern is always treated as an `EXTENDED_GLOB` pattern. Any file whose name is not changed by the substitution is simply ignored. Any error (a substitution resulted in an empty string, two substitutions gave the same result, the destination was an existing regular file and `-f` was not given) causes the entire function to abort without doing anything.

  In addition to pattern replacement, the variable `$f` can be referrred to in the second (replacement) argument. This makes it possible to use variable substitution to alter the argument; see examples below.

  Options:

  `-f`

    Force overwriting of destination files. Not currently passed down to the `mv`/`cp`/`ln` command due to vagaries of implementations (but you can use `-o-f` to do that).

  `-i`

    Interactive: show each line to be executed and ask the user whether to execute it. ‘`Y`’ or ‘`y`’ will execute it, anything else will skip it. Note that you just need to type one character.

  `-n`

    No execution: print what would happen, but don’t do it.

  `-q`

    Turn bare glob qualifiers off: now assumed by default, so this has no effect.

  `-Q`

    Force bare glob qualifiers on. Don’t turn this on unless you are actually using glob qualifiers in a pattern.

  `-s`

    Symbolic, passed down to `ln`; only works with `-L`.

  `-v`

    Verbose: print each command as it’s being executed.

  `-w`

    Pick out wildcard parts of the pattern, as described above, and implicitly add parentheses for referring to them.

  `-W`

    Just like `-w`, with the addition of turning wildcards in the replacement pattern into sequential `${1}` .. `${N}` references.

  `-C`
  `-L`
  `-M`

    Force `cp`, `ln` or `mv`, respectively, regardless of the name of the function.

  `-p` program

    Call program instead of `cp`, `ln` or `mv`. Whatever it does, it should at least understand the form

        program -- oldname newname

    where oldname and newname are filenames generated by `zmv`. program will be split into words, so might be e.g. the name of an archive tool plus a copy or rename subcommand.

  `-P` program

    As `-p` program, except that program does not accept a following `-``-` to indicate the end of options. In this case filenames must already be in a sane form for the program in question.

  `-o` optstring

    The optstring is split into words and passed down verbatim to the `cp`, `ln` or `mv` command called to perform the work. It should probably begin with a ‘`-`’.

  Further examples:

      zmv -v '(* *)' '${1// /_}'

  For any file in the current directory with at least one space in the name, replace every space by an underscore and display the commands executed.

      zmv -v '* *' '${f// /_}'

  This does exactly the same by referring to the file name stored in `$f`.

  For more complete examples and other implementation details, see the `zmv` source file, usually located in one of the directories named in your `fpath`, or in `Functions/Misc/zmv` in the zsh distribution.

`zrecompile`

  See ‘Recompiling Functions’ (Utilities).

`zstyle+` context style value [ `+` subcontext style value ... ]

  This makes defining styles a bit simpler by using a single ‘`+`’ as a special token that allows you to append a context name to the previously used context name. Like this:

      zstyle+ ':foo:bar' style1 value1 \
             +':baz'     style2 value2 \
             +':frob'    style3 value3

  This defines style1 with value1 for the context `:foo:bar` as usual, but it also defines style2 with value2 for the context `:foo:bar:baz` and style3 with value3 for `:foo:bar:frob`. Any subcontext may be the empty string to re-use the first context unchanged.

#### 26.12.2 Styles

`insert-tab`

  The `zed` function sets this style in context ‘`:completion:zed:*`’ to turn off completion when `TAB` is typed at the beginning of a line. You may override this by setting your own value for this context and style.

`pager`

  The `nslookup` function looks up this style in the context ‘`:nslookup`’ to determine the program used to display output that does not fit on a single screen.

`prompt`
`rprompt`

  The `nslookup` function looks up this style in the context ‘`:nslookup`’ to set the prompt and the right-side prompt, respectively. The usual expansions for the `PS1` and `RPS1` parameters may be used (see Prompt Expansion).

Previous: User Configuration Functions, Up: User Contributions [Contents][Index]