Skip to content

Latest commit

 

History

History
230 lines (184 loc) · 10.6 KB

README.md

File metadata and controls

230 lines (184 loc) · 10.6 KB
Raw

cz

About

Cz is a bash script that provides a common interface to interactive line selection tools.

What is an "interactive line selection tool"? It's a kind of program that reads text input then presents an interactive menu for the user to select one line. Some line selection tools run only in the terminal and others are graphical - cz uses a tool appropriate for the situation.

Cz implements a plugin system. Each plugin defines lines from which to select, an output template, and a command template. Creating new plugins is quick and painless in any programming language.

Included are almost 300 plugins covering a variety of use cases. For example with some of the included plugins you can select from:

Tools

The following line selection tools are supported:

Tool Mode
choose GUI
dmenu GUI
fzf TTY
fzy TTY
gum TTY
iselect TTY
pick TTY
pipedial TTY
rofi GUI
selecta TTY
sentaku TTY
skim TTY
slmenu TTY
vis-menu TTY
zenity GUI

Many thanks to the authors of the above tools!

Aware of any other line selection tools? Let me know.

Installation

# just download the script to a directory on your path
curl -sS https://raw.githubusercontent.com/apathor/cz/master/bin/cz -o ~/bin/cz

# and make it executable
chmod -v +x ~/bin/cz

Cz requires at least bash version 4. Mac OS users should `brew install bash`.

Usage

cz [OPTIONS] [PLUGIN...] [ARGS ...] [< LINES]
Select a line using an interactive line selection tool.

OPTIONS
 These options print some information then exit:
  -h : help     : Show this help text or help text for plugin.
  -H : example  : List example commands.
  -k : tools    : List supported line selection tools.
  -l : plugins  : List detected plugins.
  -v : version  : Show version string.

 These options set the program mode. Select a line then... :
  -p : print    : Print the line. This is the default mode.
  -q : quote    : Print fields from the line in shell quotes.
  -r : run      : Run a templated command.
  -s : simulate : Print a templated command.
  -t : template : Print a templated string.
  -u : unquote  : Print fields from the line literally.
  -o : output   : Only print input lines instead of selecting a line.

 These options set a template:
  -e TEMPLATE   : Set the command template. This option implies mode '-r'.
  -f FIELDS     : Set the field template. This option implies mode '-q'.

 These options control input and line splitting:
  -c            : Do not use cached input lines.
  -d DELIMITER  : Set the field splitting characters.
  -g            : Buffer stdin and pass it to command set with '-e'.
  -0            : Read null terminated lines from input.
  -i IN-FILE    : Set file from which to read selections instead of stdin.

 These options control how lines are selected:
  -n NUMBER     : Select a line the given number of times.
  -w            : Pick a line at random.
  -x            : Use a graphical line selection tool.
  -y            : Use a terminal line selection tool.
  -z TOOL       : Use the given line selection tool.

 These options control debugging features:
  -m            : Print some debugging information.

TOOLS
 The following interactive line selection tools are supported:
  choose, dmenu, fzf, fzy, gum, iselect, pick, pipedial, rofi, selecta,
  sentaku, slmenu, vis-menu, and zenity.

PLUGINS
 Plugins use cz for an application specific task. Each plugin defines input
  lines, delimiter, and template options.
 Run 'cz -l' to list plugins and 'cz -h PLUGIN' or 'cz help' for help text.
 All commands starting with 'cz_' are considered plugins.

TEMPLATES
 Sub-strings of TEMPLATE in the following formats are replaced with
  one or more fields from a selected line split by DELIMITER.
     {X}     - field X
     {X:}    - fields X through end of fields
     {X:Y}   - fields X through X + Y
     {X,Y,Z} - fields X, Y, and Z

 Append @C, @E, @P, or @Q to transform selected fields:
  {X@C} - Insert argument directly. This is risky for command strings!
  {X@E} - Replace backslash escape sequences in arguments with bash $'...' quotes.
  {X@P} - Expand arguments for use in prompt strings.
  {X@Q} - Quote arguments for use in command input. This is the default.

ENVIRONMENT
 CZ_GUI         : The preferred interface (1=graphical 0=terminal).
 CZ_BINS        : A list of line selection tools in order of preference.
 CZ_DMENU_COLOR : Colon separated colors for dmenu (NF:NB:SF:SB).
 CZ_DMENU_FONT  : The font to use for dmenu.
 CZ_ROFI_THEME  : The theme to use for rofi.

Configuration

To get the most out of cz users should consider binding shell and window manager keys.

Bash

Download this example bash config then copy it into your bashrc file.

The example config defines key bindings that run cz to provide interactive functionality.

Some of the key bindings use the included function `rleval` to do one of the following:

  • Insert output from cz into the bash command buffer at cursor point.
  • Replace the word at cursor point in the bash command buffer with output from cz.
  • Run cz to launch an interactive program (like $EDITOR) using some part of the selection.

The example key bindings are as follows:

Keys Function
C-x x Select a cz plugin, run it in quote mode, and insert one or more fields from the selection.
C-x X Select a cz plugin, run it print mode, and insert the selection.
C-x z Select a cz plugin, run it in run mode, and insert the output of the command.
C-x Z Select a cz plguin, run it in simulate mode and insert the command templated with the selection.
C-x r Select a command from bash history and insert it.
C-x u Select a unicode character and insert it.
C-x g Select an uncomitted file in current git repository and insert its path.
C-x G Select a comitted file in current git repository and insert its path.
C-x d Using the current word as a directory, replace it with a selected descendant directory.
C-x D Using the current word as a pattern, replace it with a selected matching descendant directory under $PWD.
C-x f Using the current word as a directory, replace it with a selected descendant file.
C-x F Using the current word as a pattern, replace it with a selected matching descendant file under $PWD.
C-x l Using the current word as a pattern, replace it with a selected matching file from the locate database.
C-x e Using the current word as a pattern, replace it with the path of a file matching it under $PWD.
C-x E Using the current word as a pattern, run $EDITOR to open selected file matching it under $PWD.

Zsh

Download the example zsh config then copy it into your zshrc file.

The example config defines the same key bindings described in the bash section above.

i3 Window Manager

Download the example i3 config then copy it into your i3 config.

The example config defines the following key bindings:

Keys Function
Mod x Select a cz plugin, run it, and put fields from selected line into a clipboard.
Mod X Select a cz plugin, run it, and put selected line into a clipboard.
Mod z Select a cz plugin, run it, and put the command output into a clipboard.
Mod Z Select a cz plguin, run it in simulate mode, and put the output into a clipboard.
Mod c Select a command and run it.
Mod C Select a clipboard and pipe its contents through the selected command.
Mod o Select a clipboard then select a URL extracted from its contents to open in a browser.
Mod Shift Space Select an i3 a tag and jump to the selected window.
Mod Tab Select an i3 window and jump to it.
Mod Shift Tab Select an i3 workspace and switch to it.

Name

seize
To fall or rush upon suddenly and lay hold of; to gripe or grasp suddenly;
*to reach and grasp*.