diff --git a/man/abbr.txt b/man/abbr.txt new file mode 100644 index 0000000..cfecc2b --- /dev/null +++ b/man/abbr.txt @@ -0,0 +1,200 @@ +ZSH-ABBR(1) User Commands ZSH-ABBR(1) + + + +NAME + zsh-abbr - manage zsh abbreviations + +SYNOPSIS + abbr (--add | -a) [scope] + + abbr (--clear-session | -c) + + abbr (--erase | -e) [scope] + + abbr (--expand | -x) + + abbr (--export-aliases | -o) [] + + abbr --import-git-aliases [scope] + + abbr --import-aliases [scope] + + abbr --list-abbreviations | -l + + abbr (--list-commands | -L | -s) + + abbr --list-definitions + + abbr (--rename | -R) [scope] + + abbr (--help | -h) + + abbr (--version | -v) + + +DESCRIPTION + abbr manages abbreviations - user-defined words that are replaced with + longer phrases after they are entered. + + For example, a frequently-run command like git checkout can be abbrevi- + ated to gco. After entering gco and pressing [Space], the full text git + checkout will appear in the command line. + + To prevent expansion, press [CTRL-SPACE] in place of [SPACE]. + + +Options + The following options are available: + + + o --add abbreviation expansion or -a abbreviation expansion + + Adds a new abbreviation, causing abbreviation to be expanded as + expansion. + + + o --clear-session or -c + + Erases all session abbreviations. + + + o --erase abbreviation or -e abbreviation + + Erases the abbreviation abbreviation . + + + o --expand abbreviation or -x abbreviation + + Returns the expansion of the abbreviation abbreviation. + + + o --export-aliases [] + + Exports a list of alias command for user abbreviations, suitable + for pasting or piping to whereever you keep aliases. If a is provided, the commands will be appended to it. + + + o --import-git-aliases + + Adds abbreviations for all git aliases. Abbreviations are pre- + fixed with "g", expansions are prefixed with "git ". + + + o --import-aliases + + Adds abbreviations for all aliases. + + + o --list-abbreviations or -l + + Lists all abbreviations. + + + o --list-commands or -L (or -s as in fish) + + Lists all abbreviations as commands suitable for export and + import. + + + o --list-definitions + + Lists all abbreviations and their expansions. + + + o --rename old_abbreviation new_abbreviation or -R old_abbrevia- + tion new_abbreviation + + Renames an abbreviation, from old_abbreviation to new_abbrevia- + tion. + + + o --version or -v + + Show the current version. + + + Some options (see SYNOPSIS) can take a scope: + + o --session or -S + + Abbreviations available in the current session only. + + + o --user or -U + + Abbreviations available to all current and future ses- + sions. + + + and/or a position + + + o --global or -g + + Abbreviation will expand anywhere on a line, rather than + only in command (first word) position. + + + and/or be trialed + + + o --dry-run Show whats the result of the command would be. + + + See INTERNALS for more information. + + +EXAMPLES + abbr gco="git checkout" + + "gco" will be expanded as "git checkout" when it is the first + word in the command, in all open and future sessions. + + + abbr -g gco="git checkout" + + "gco" will be replaced with "git checkout" anywhere on the line, + in all open and future sessions. + + + abbr -g -S gco="git checkout" + + "gco" will be replaced with "git checkout" anywhere on the line, + in the current session. + + + abbr -e -S -g gco; + + Erase the global session abbreviation "gco". Note that because + expansion is triggered by [SPACE] and [ENTER], the semicolon (;) + is necessary to prevent expansion when operating on global + abbreviations. + + + abbr -e -g gco; + + Erase the global user abbreviation "gco". + + + abbr -e gco + + Erase the regular user abbrevation "gco". + + + abbr -R -g gco gch + + Rename an existing global user abbreviation from "gco" to "gch". + + +HISTORY + Inspired by fBfish shell's abbr. + + +AUTHORS + Henry Bley-Vroman + + + +zsh-abbr 3.1.1 March 7 2020 ZSH-ABBR(1) diff --git a/man/man1/abbr.1 b/man/man1/abbr.1 new file mode 100644 index 0000000..c301e6e --- /dev/null +++ b/man/man1/abbr.1 @@ -0,0 +1,182 @@ +.TH "ZSH-ABBR" 1 "March 7 2020" "zsh\-abbr 3.1.1" "User Commands" +.SH NAME +zsh\-abbr \- manage zsh abbreviations +.SH SYNOPSIS + +\fBabbr\fR (\fB\-\-add\fR | \fB\-a\fR) [\fIscope\fR] <\fIabbreviation\fR> <\fIexpansion\fR> + +\fBabbr\fR (\fB\-\-clear\-session\fR | \fB\-c\fR) + +\fBabbr\fR (\fB\-\-erase\fR | \fB\-e\fR) [\fIscope\fR] <\fIabbreviation\fR> + +\fBabbr\fR (\fB\-\-expand\fR | \fB\-x\fR) <\fIabbreviation\fR> + +\fBabbr\fR (\fB\-\-export\-aliases\fR | \fB\-o\fR) <\fIscope\fI> [<\fIdestination\fR>] + +\fBabbr \-\-import\-git\-aliases\fR [\fIscope\fR] + +\fBabbr \-\-import\-aliases\fR [\fIscope\fR] + +\fBabbr \-\-list\-abbreviations\fR | \fB\-l\fR + +\fBabbr\fR (\fB\-\-list\-commands\fR | \fB\-L\fR | \fB\-s\fR) + +\fBabbr \-\-list\-definitions\fR + +\fBabbr\fR (\fB\-\-rename\fR | \fB\-R\fR) [\fIscope\fR] <\fIold_abbreviation\fR> <\fInew_abbreviation\fR> + +\fBabbr\fR (\fB\-\-help\fR | \fB\-h\fR) + +\fBabbr\fR (\fB\-\-version\fR | \fB\-v) + +.SH DESCRIPTION +\fBabbr\fR manages abbreviations \- user\-defined words that are replaced with longer phrases after they are entered. + +For example, a frequently\-run command like git checkout can be abbreviated to gco. After entering gco and pressing [\fBSpace\fR], the full text git checkout will appear in the command line. + +To prevent expansion, press [\fBCTRL\-SPACE\fR] in place of [\fBSPACE\fR]. + +.SH Options +The following options are available: + +.IP \(bu +\fB\-\-add \fIabbreviation\fR \fIexpansion\fR or \fB\-a\fR \fIabbreviation\fR \fIexpansion\fR + +Adds a new abbreviation, causing \fIabbreviation\fR to be expanded as \fIexpansion\fR. + +.IP \(bu +\fB\-\-clear\-session\fR or \fB\-c\fR + +Erases all session abbreviations. + +.IP \(bu +\fB\-\-erase \fIabbreviation\fR or \fB\-e\fR \fIabbreviation\fR + +Erases the abbreviation \fIabbreviation\fR . + +.IP \(bu +\fB\-\-expand \fIabbreviation\fR or \fB\-x \fIabbreviation\fR + +Returns the \fIexpansion\fR of the abbreviation \fIabbreviation\fR. + +.IP \(bu +\fB\-\-export\-aliases\fR [<\fIdestination\fR>] + +Exports a list of alias command for user abbreviations, suitable for pasting or piping to whereever you keep aliases. If a <\fIdestination\fR> is provided, the commands will be appended to it. + +.IP \(bu +\fB\-\-import\-git\-aliases\fR + +Adds abbreviations for all git aliases. Abbreviations are prefixed with "g", expansions are prefixed with "git ". + +.IP \(bu +\fB\-\-import\-aliases\fR + +Adds abbreviations for all aliases. + +.IP \(bu +\fB\-\-list\-abbreviations\fR or \fB\-l\fR + +Lists all abbreviations. + +.IP \(bu +\fB\-\-list\-commands\fR or \fB\-L\fR (or \fB\-s\fR as in fish) + +Lists all abbreviations as commands suitable for export and import. + +.IP \(bu +\fB\-\-list\-definitions\fR + +Lists all abbreviations and their expansions. + +.IP \(bu +\fB\-\-rename\fR \fIold_abbreviation\fR \fInew_abbreviation\fR or \fB\-R\fR \fIold_abbreviation\fR \fInew_abbreviation\fR + +Renames an abbreviation, from \fIold_abbreviation\fR to \fInew_abbreviation\fR. + +.IP \(bu +\fB\-\-version\fR or \fB\-v\fR + +Show the current version. + +.PP +Some options (see \fBSYNOPSIS\fR) can take a \fIscope\fR: +.RS +.IP \(bu +\fB\-\-session\fR +or +\fB\-S\fR + +Abbreviations available in the current session only. + +.IP \(bu +\fB\-\-user\fR or \fB\-U\fR + +Abbreviations available to all current and future sessions. + +.RE + +and/or a position +.RS + +.IP \(bu +\fB\-\-global\fR or \fB\-g\fR + +Abbreviation will expand anywhere on a line, rather than only in command (first word) position. + +.RE + +and/or be trialed +.RS + +.IP \(bu +\fB\-\-dry\-run\fR +Show whats the result of the command would be. + +.RE + +See \fBINTERNALS\fR for more information. + +.SH EXAMPLES + +.TP +\fBabbr\fR gco="git checkout" + +"gco" will be expanded as "git checkout" when it is the first word in the command, in all open and future sessions. + +.TP +\fBabbr \-g\fR gco="git checkout" + +"gco" will be replaced with "git checkout" anywhere on the line, in all open and future sessions. + +.TP +\fBabbr \-g \-S\fR gco="git checkout" + +"gco" will be replaced with "git checkout" anywhere on the line, in the current session. + +.TP +\fBabbr \-e \-S \-g\fR gco; + +Erase the global session abbreviation "gco". Note that because expansion is triggered by [\fBSPACE\fR] and [\fBENTER\fR], the semicolon (;) is necessary to prevent expansion when operating on global abbreviations. + +.TP +\fBabbr \-e \-g\fR gco; + +Erase the global user abbreviation "gco". + +.TP +\fBabbr \-e\fR gco + +Erase the regular user abbrevation "gco". + +.TP +\fBabbr \-R \-g\fR gco gch + +Rename an existing global user abbreviation from "gco" to "gch". + +.SH HISTORY +Inspired by \fBfish\fR shell's \fBabbr\fR. + +.SH AUTHORS + +Henry Bley\-Vroman diff --git a/zsh-abbr.zsh b/zsh-abbr.zsh index 16e61ed..b2e1901 100755 --- a/zsh-abbr.zsh +++ b/zsh-abbr.zsh @@ -25,7 +25,7 @@ _zsh_abbr() { opt_import_aliases opt_import_fish opt_list opt_list_commands \ opt_print_version opt_rename opt_scope_session opt_scope_user \ opt_type_global opt_type_regular type_set release_date scope_set \ - should_exit text_bold text_reset util_usage version + should_exit text_bold text_reset version action_set=false number_opts=0 opt_add=false @@ -51,171 +51,6 @@ _zsh_abbr() { should_exit=false text_bold="\\033[1m" text_reset="\\033[0m" - util_usage=" - ${text_bold}abbr${text_reset}: fish shell-like abbreviations for zsh - - ${text_bold}Synopsis${text_reset} - ${text_bold}abbr${text_reset} --add|-a [SCOPE] ABBREVIATION EXPANSION - ${text_bold}abbr${text_reset} --clear-session|-c [SCOPE] ABBREVIATION - ${text_bold}abbr${text_reset} --erase|-e [SCOPE] ABBREVIATION - ${text_bold}abbr${text_reset} --expand|-x ABBREVIATION - ${text_bold}abbr${text_reset} --export-aliases|-o [SCOPE] [DESTINATION] - ${text_bold}abbr${text_reset} --import-git-aliases [SCOPE] - ${text_bold}abbr${text_reset} --import-aliases [SCOPE] - ${text_bold}abbr${text_reset} --list-abbreviations|-l - ${text_bold}abbr${text_reset} --list-commands|-L|-s - ${text_bold}abbr${text_reset} --list-definitions - ${text_bold}abbr${text_reset} --rename|-R [SCOPE] OLD_ABBREVIATION NEW - - ${text_bold}abbr${text_reset} --help|-h - ${text_bold}abbr${text_reset} --version|-v - - ${text_bold}Description${text_reset} - ${text_bold}abbr${text_reset} manages abbreviations - user-defined words - that are replaced with longer phrases after they are entered. - - For example, a frequently-run command like git checkout can be - abbreviated to gco. After entering gco and pressing [${text_bold}Space${text_reset}], - the full text git checkout will appear in the command line. - - To prevent expansion, press [${text_bold}CTRL-SPACE${text_reset}] in place of [${text_bold}SPACE${text_reset}]. - - ${text_bold}Options${text_reset} - The following options are available: - - o --add ABBREVIATION=EXPANSION or -a ABBREVIATION=EXPANSION Adds a new - abbreviation, causing ABBREVIATION to be expanded to EXPANSION. - - o --clear-session or -E Erases all session abbreviations. - - o --erase ABBREVIATION or -e ABBREVIATION Erases the - abbreviation ABBREVIATION. - - o --expand ABBREVIATION or -x ABBREVIATION Returns the abbreviation - ABBREVIATION's EXPANSION. - - o --export-aliases [-g] [DESTINATION_FILE] or -o [-g] [DESTINATION_FILE] - Exports a list of alias command for user abbreviations, suitable - for pasting or piping to whereever you keep aliases. Add -g to export - alias commands for session abbreviations. If a DESTINATION_FILE is - provided, the commands will be appended to it. - - o --help or -h Show this documentation. - - o --import-aliases Adds abbreviations for all aliases. - - o --import-fish FILE Import from fish shell or zsh-abbr < 3. - - o --import-git-aliases Adds abbreviations for all git aliases. - ABBREVIATIONs are prefixed with g, EXPANSIONs are prefixed - with git[Space]. - - o --list-abbreviations or -l Lists all ABBREVIATIONs. - - o --list-commands or -L (or fishy -s) Lists all abbreviations as - commands suitable for export and import. - - o --list-definitions Lists all ABBREVIATIONs and their EXPANSIONs. - - o --rename OLD_ABBREVIATION NEW_ABBREVIATION - or -R OLD_ABBREVIATION NEW_ABBREVIATION Renames an abbreviation, - from OLD_ABBREVIATION to NEW_ABBREVIATION. - - o --version or -v Show the current version. - - In addition, when adding abbreviations, erasing, exporting aliases, - [git] importing, or renaming use - - o --session or -S to create a session abbreviation, available only in - the current session. - - o --user or -U to create a user abbreviation (default), - immediately available to all sessions. - - and - - o --global or -g to create a global abbreviation, which expand anywhere - on a line. - - and - - o --dry-run with add, import, or rename to see what the result would be. - - See the 'Internals' section for more on them. - - ${text_bold}Examples${text_reset} - ${text_bold}abbr${text_reset} -a -g gco=\"git checkout\" - ${text_bold}abbr${text_reset} --add --session gco=\"git checkout\" - - Add a new abbreviation where gco will be replaced with git checkout - session to the current shell. This abbreviation will not be - automatically visible to other shells unless the same command is run - in those shells. - - ${text_bold}abbr${text_reset} -- g-=\"git checkout -\" - - If the EXPANSION includes a hyphen (-), the --add command\'s - entire EXPANSION must be quoted. - - ${text_bold}abbr${text_reset} -a l=less - ${text_bold}abbr${text_reset} --add l=less - - Add a new abbreviation where l will be replaced with less user so - all shells. Note that you omit the -U since it is the default. - - ${text_bold}abbr${text_reset} -x gco - \$(${text_bold}abbr${text_reset} -expand gco) - - Output the expansion for gco (in the above --add example, - git checkout). Useful in scripting. - - ${text_bold}abbr${text_reset} --export-aliases -session - - Export alias declaration commands for each *session* abbreviation. - Export lines look like alias -g ='' - - ${text_bold}abbr${text_reset} --export-aliases - - Export alias declaration commands for each *user* abbreviation. - Export lines look like alias -g ='' - - ${text_bold}abbr${text_reset} --export-aliases ~/aliases - - Add alias definitions to ~/aliases - - ${text_bold}abbr${text_reset} -e -g gco - ${text_bold}abbr${text_reset} --erase --session gco - - Erase the session gco abbreviation. - - ${text_bold}abbr${text_reset} -R -g gco gch - ${text_bold}abbr${text_reset} --rename --session gco gch - - Rename the existing session abbreviation from gco to gch. - - ${text_bold}abbr${text_reset} -R l le - ${text_bold}abbr${text_reset} --rename l le - - Rename the existing user abbreviation from l to le. Note that you - can omit the -U since it is the default. - - ${text_bold}Internals${text_reset} - The ABBREVIATION cannot contain IFS whitespace, comma (,), semicolon (;), - pipe (|), or ampersand (&). - - Defining an abbreviation with session scope is slightly faster than - user scope (which is the default). - - You can create abbreviations interactively and they will be visible to - other zsh sessions if you use the -U flag or don't explicitly specify - the scope. If you want it to be visible only to the current shell - use the -g flag. - - The options add, export-aliases, erase, expand, import, list, - list-commands, and rename are mutually exclusive, as are the session - and user scopes. - - $version $release_date" version="zsh-abbr version 3.1.1" function add() { @@ -703,7 +538,7 @@ _zsh_abbr() { } function util_usage() { - print "$util_usage\\n" + man abbr 2>/dev/null || cat ${ZSH_ABBR_SOURCE_PATH}/man/abbr.txt | less -F } for opt in "$@"; do @@ -1070,6 +905,7 @@ abbr() { # -------------- _zsh_abbr_init +ZSH_ABBR_SOURCE_PATH=${0:A:h} if [ "$ZSH_ABBR_DEFAULT_BINDINGS" = true ]; then _zsh_abbr_bind_widgets