I've noticed the --description option as a part of function declarations in Fish shell syntax.
For example, /usr/share/fish/functions/abbr.fish:
function abbr --description "Manage abbreviations"
…
end
However, I've never seen it used. None of the following commands do what I'm trying to accomplish, which is view the description of any given function (provided that it's defined):
> abbr --description
abbr: Unknown option “--description”
/usr/share/fish/functions/abbr.fish (line 6):
argparse -n abbr $options -- $argv
^
in function 'abbr' with arguments '--description'
> help --description
help: Unknown option “--description”
/usr/share/fish/functions/help.fish (line 3):
argparse -n help --max-args=1 $options -- $argv
^
in function 'help' with arguments '--description'
> help description # opens file:///usr/share/doc/fish/index.html in a browser (same functionality as `help`)
> help abbr # opens file:///usr/share/doc/fish/cmds/abbr.html in a browser (only works for built-in functions)
I haven't seen anything about this option in the documentation. If it's there, please point me to it.
The --description option is to provide a description of the defined function, of course the abbr command doesn't have a description option, because it belongs to function command (and abbr doesn't have such option)
See fish docs:
https://fishshell.com/docs/current/cmds/function.html#description
https://fishshell.com/docs/current/cmds/abbr.html#options
As #puffin answered, the --description option is to add a docstring for your function definition.
But it is much more useful than just something "for the developer", and is in fact designed to be seen by the user, in several places.
In TAB completion menus
In the output of type for a function
In the output of functions -vD funcname ( v erbose D etails)
Examples, using this simple function definition:
mjl#jazz ~> function ... -d 'Go up two directory levels.'
../../
end
Hitting TAB:
This is the most useful purpose of --description|-d. After typing . . TAB, this is how Fish shows the completions (it added the third .):
mjl#jazz ~> ...
.. ... (Go up two directory levels.) ../ (Directory, 160B)
The description appears, so that the user can tell at a glance what the meaning of ... is.
Listing the function:
mjl#jazz ~> type ...
... is a function with definition
function ... --description 'Go up two directory levels.'
../../
end
Showing the function's details:
mjl#jazz ~> functions -vD ...
stdin
n/a
0
scope-shadowing
Go up two directory levels.
You are trying to call the abbr function with the --description option. The option is more of a really simple "docstring" of sorts for the developer, it is not designed to be seen by the end user. Its an option on the function command, it is not adding any help strings or other functionality to the function being defined.
Take the fish function fish_git_prompt defined in /usr/share/fish/functions/fish_git_prompt.fish. Its full definition is function fish_git_prompt --description "Prompt function for Git", and the description provides a very brief explanation of the purpose. The descriptions are pretty repetitive and overly verbose, but would be more useful for short function names which may be ambiguous.
Related
I have fish shell with omf with agnoster theme and git-plugin installed.
I would like to tune my prompt a bit. Does anyone here know where/how I do that. I ran fish_config; but that did not show my current prompt properly. So I am reluctant to go that route. I would rather do it by typing it in; but can't figure out where the final prompt is being stored. I tried 'echo $fish_prompt'. Did not help.
Would appreciate some help. Thanks!
fish_prompt is a function. See https://fishshell.com/docs/current/cmds/fish_prompt.html. To see where it is defined run functions --details fish_prompt. There is no "final prompt [is] being stored" as I understand that phrase. There is a function that creates the prompt. Your echo $fish_prompt would only output something useful if the prompt was a literal string (which isn't supported). You can use functions --all fish_prompt to see where it is defined and the content of the function.
When I used Fish I did not use OMF (I'm now an Elvish user). I had a custom function defined in ~/.config/fish/functions/fish_prompt.fish. So I can't explain how to customize the OMF "agnoster" theme prompt. You'll need to read the documentation for that theme to learn what knobs, if any, it provides for customizing its behavior.
Short answer: edit function fish_prompt in file: .local/share/omf/themes/agnoster/functions/fish_prompt.fish.
Explanation:
This exact file may not work in cases with different plugin's and/or different theme.
The way I figured this was to search for all "*prompt.fish" functions in my home directory. Put a distinct print statement with the prompt in each one of them and check which one got printed and modified the fish_prompt.fish function in that file - which is working for me!
I'd like to be able to simply type herb and then press tab and have fish-shell tab-complete it to herbstclient. I've tried looking it up, but every result I can find has to do with overiding fish's autocomplete with tab rather than ctrl + f.
Do I need to create a fish script for this? If so, what should it look like and where should I put it?
Assuming that is a command you want an abbreviation: abbr herb herbstclient. Although you don't use [tab] to complete an abbreviation; you have to press [space] or [enter]. Note that the expansion can consist of multiple tokens. For example, this is one of my most often used abbreviations: abbr -a -g -- gcm 'git checkout master'. Also, abbreviations only get expanded in the command position; i.e., start of line or after a pipe, |, or semicolon. If you want that expansion elsewhere in a command line there are ways to achieve that but it's a bit more complicated.
Many times I end up writting wrapper function around existing ones, for instance:
function gl {
some_computed_stuff=...
git --no-pager log --reverse $some_computed_stuff "$#"
}
function m {
make "$#" && notify-send success || notify-send failed
}
I know that aliases keep autocompletion but sometimes functions are required and in that case autocompletion is lost.
For instance here I would like to keep git log completion for my function gl or make completion for m.
I tried to add compctl -K _git gl but no suggestions are made. It won't work anyway since I must somehow find how to provide log argument to _git autocompletion script as well, so my question is:
Is there a way to make ZSH (but also bash) understand that typing gl is the exact equivalent of git log? Something like (for ZSH only):
compctl 'git log' gl
compctl 'make' m
For zsh, you can create a new completion with compdef function.
In its basic form it associates a completion function with a word. Provided that zsh comes with lots of completions already built-in, one can just reuse those. For example, for m function from the question:
$ compdef _make m
As per documentation, you can also define a completion for a specific service, if the one is defined in the completion function. Again, as zsh comes with _git completion and it already defines git-log service, a gl function from the question may be autocompleted with:
$ compdef _git gl=git-log
On Linux, you can see existing completion implementations in /usr/share/zsh/functions/Completion/Unix/. You can read the completion implementations to see what services they define.
I wish to create a custom command which has it's first argument as a regex & pressing TAB after typing regex will open a auto-complete menu with all the files matching the pattern.
if I name my command vimf (meaning vim find) and write the auto-complete function like:
#compdef vimf
_arguments "1: :_files -g \"**/*.conf\""\
In the above auto-complete function, typing $vimf , lists all the files ending with .conf in the auto-completion menu. Now, I want this part .conf to be taken from the first argument of the command. So, if I type something like: vimf *.pp, I want it to search only files ending with *.pp.
How do I make that possible? How can I use the arguments of a command while writing auto-complete functions?
To do this you need to use the words array which is set to the content of the command line.
From this, you retrieve the file type by accessing the good index, and troncate the prefix. (this is done by #compdef vimf)
Here is the result:
#compdef vimf
_arguments "1: :_files -g \"**/*.${words[2]##*.}\""\
&& return 0
I tried it on my terminal, it works, but of course can take long time to perform if your do this by the root. Enjoy :)
I know there is a way to list mappings via :map (or :imap, :cmap, etc.), but I can't find a way to list macros I have stored in my vimrc file (as in let #a = 'blahblah').
Is there a way to do this without having to manually looking inside it (via :split [myvimrcfile] or whatever way)?
Also, if it is possible, is there a way to attach some sort of documentation that would display with the macro to explain what it is for? I have a handful that I use quite a bit, but about 6 weeks apart. It would be nice to just quickly list them along with a comment that tells me what the macro does (or even just a name so I make sure I use the right one).
Thanks
In vim, the macros are just stored in registers. You can recall the content of any register and execute it as a macro (which is what the # does). To see a list of what is in your registers, use :reg.
You can see the contents of all the registers using the
:reg
command. Or an argument string like this
:reg ahx
will show you the contents of registers a, h, and x.
That way you can at least see what sequence of commands will be run and hopefully that will be clear enough for you to tell one from another.
The registers simply contain text. You can paste the command sequence in as text or you can copy text into a register and then run it as a command, depending on how you access the register.
I have not found any direct way to edit the contents of a register, but you can paste it into the file, edit it, and then save it back to the same register.
IHTH.
As /u/jheddings wrote the macros are stored as registers and what counts is the assignment of the code to the register (usually done in the vimrc files with let #a=blahblah
To ease the way to display the macros you defined in your vimrc file (in my case it is in the ~/.vimrc path) you can use this vim function:
function! ShowMacros()
10new
exe 'r!' . 'grep -B 1 -E "^\s*let #" ~/.vimrc'
call cursor(1,1)
endfunction
What it does:
10new - open a new vim window with ten lines size
exe ... - execute a command and put in the window
call ... - go to the first line first column
You can execute this function by tipping in the normal mode
:call ShowMacros
You could additionally create a key mapping or a command to fasten the way to call the function:
:cnoremap sm call ShowMacros()<CR>
command! sm call ShowMacros()`
This is the original post where I wrote the function similar to the above.
The OP asked, "is there a way to attach some sort of documentation that would display with the macro to explain what it is for?"
I have found VI / VIM macros extremely obtuse to understand even a week after I've written them, so I heartily support the idea of documentation. I have a suggestion for that, in two parts.
First is the process of documenting the macro in your .vimrc. I've developed the following .vimrc comment format that helps me understand, a week or a year or more later, what a macro is supposed to be doing. E.g.:
"
"= GENERIC CLIPBOARD YANK <F2>y (Y for Yank)
"= Yank the entire contents of the file into the clipboard; quit without saving.
"
"define F2 followed by y to be:
"| Go to line 1.
"| | From there, into the * buffer (system clipboard),
"| | | yank to the end of the file.
"| | | | Go to sleep for 1 second (to allow the clipboard to be updated).
"| | | | | Quit without saving the file.
"| | | | | |
map #2y 1G"*yG1gs:q!<CR>
"-------"-"-"-"--"------
Second, I am imagining that Jakub's ShowMacros() function above could be modified to grep a specific set of Help lines for each macro that would be in the file along with the definition, much the way the above command-line breakdown is attached to the definition, that would provide the needed User Help.
I've flagged two lines above with "= at the beginning of each, so that they can become the User Help. Then Jakub's grep command would search for "^\"= ". Here's the command I used. I'm not sure if the -E for Extended Regular Expressions is needed and the -B 1 is a nice touch to include one line previous to a matching sequence, so here I have an explicitly empty comment line.
In my vimrc, I only needed one backslash, for the initial parsing of the definitions. Here's the line, replacing the one in Jakub's function definition above:
exe 'r!' . 'grep -B 1 -E "^\"= " ~/.vimrc'
Thanks to Jakub's hint, I now can generate help from my .vimrc in pretty much exactly the way the OP is asking for. I've been using vi since 1983, so I'm pretty stoked.
Thanks Jakub!
IHTH,
August