{"id":282,"date":"2016-10-13T02:25:46","date_gmt":"2016-10-13T01:25:46","guid":{"rendered":"http:\/\/www.benningtons.net\/?p=282"},"modified":"2017-02-09T00:37:24","modified_gmt":"2017-02-09T00:37:24","slug":"bash-completion","status":"publish","type":"post","link":"https:\/\/www.benningtons.net\/index.php\/bash-completion\/","title":{"rendered":"Bash Completion"},"content":{"rendered":"

Command-line completion is a wonderful thing. If you get bored of typing a long filename (for example) you can just hit tab and it will complete the name for you. If the shell can’t be certain of which filename you wanted then you can hit tab again and either (depending on the shell) get a list of matching names or toggle through a list of possibilities.
\nSome may say that’s just being lazy but I prefer to see it as being efficient and surely the less typing you do then the fewer mistakes you’ll make?
\nThe only downsides of command-line completion are a) that it lulls you into thinking really long filenames are ok and b) that you’ll find yourself hitting tab out of habit whenever you find yourself having to type a long name, which can be annoying when you’re not even at a command-line.
\n
\nWhilst working on a small project to create some shell commands of my own I realised that completion didn’t work for them. So I investigated further and was impressed by how easy completion was to configure and how you can use it to do more than just complete the current word.
\nHere is a summary of my findings whilst using the Bash shell on Debian 8 (Jessie).
\n<\/p>\n

Setup:<\/b>
\n<\/p>\n

Wherever you’re using Bash you’ll probably find basic completion already configured. But for more advanced programmable completion you’ll need to install the bash-completion<\/b> package.
\n
\nWhen starting a terminal session, one of the Bash startup scripts (either \/etc\/bash.bashrc<\/b> for all users or your own ~\/.bashrc<\/b>) will configure completion by running \/usr\/share\/bash-completion\/bash-completion<\/b>.
\nCompletion rules for individual commands can be found within the files in \/usr\/share\/bash-completion\/completions\/<\/b> and in \/etc\/bash-completion.d\/<\/b>. The former appears to be for commands that came with your distro and the latter for subsequent additions.
\n
\nSo having looked at the examples already in these directories I decided to try and create one for my project. As I’m not changing any existing files then I don’t appear to be at risk of breaking anything. My new addition is called ce_complete.sh<\/b> and I’m placing it in \/etc\/bash-completion.d\/<\/b>. To do so I need to use sudo so that system changes are made by the root user.
\n
\nNote that after making any changes to these files you need to reload your Bash completion settings. This can be done by closing your terminal session and opening a new one (to cause the startup scripts to run) or you could simply re-run the completion config script with . \/etc\/bash-completion<\/b> (which just runs the \/usr\/share\/bash-completion\/bash-completion<\/b> script). Note the space in . \/<\/b> at the start of that command. That ensures the script is run by your current process and not in a spawned process that would reload its own completion rules instead of your own.
\n
\nNow let’s look at the contents of my completion script as I add more features.
\n<\/p>\n

For commands:<\/b>
\n<\/p>\n

I can’t say I’m comfortable with the use of completion on commands. Commands generally have very short names so completion shouldn’t be necessary and if you’ve forgotten the full command name then typing a few letters and then hoping for completion to fill-in the rest is dangerous.
\nHowever, Bash provides command completion by checking all the directories listed in the PATH<\/b> variable to find a matching file. Use echo $PATH<\/b> to see what those directories are and to test it try typing c<\/b> followed by two tabs to get a list of all commands starting with ‘c’.
\nOne of my own commands is called clice<\/b> and I’ve placed the executable file in \/usr\/local\/bin\/<\/b> so it’s now listed amongst all those commands that start with ‘c’.
\nI can also type cli<\/b> followed by tab to complete the command name but I don’t recommend it.
\n
\nLong name command options however can be a pain to type and they should be descriptive enough to make completion safe. So cp --str<\/code> followed by a tab will expand to cp --strip-trailing-slashes<\/code> which is a useful time saver.
\nI realise that cp doesn’t need the full name and that cp --str<\/code> is unambiguous enough for it to complete the task but it’s reassuring to complete the full name and confirm that I’ve picked the right option.
\n
\nAs every command appears to complete their long name options then I feel I should do the same for my clice<\/b> command. Even though those options are currently just the standard --version<\/code> and --help<\/code>.
\nTo achieve this my \/etc\/bash-completion.d\/ce_complete.sh<\/b> file now looks like this:
\n<\/p>\n

\r\n_ce_clice()\r\n{\r\n\tlocal cur prev words cword\r\n\t_init_completion || return\r\n\r\n\tlocal opts="--help --version"\r\n\tCOMPREPLY=( $( compgen -W "$opts" "$cur" ) )\r\n\r\n\treturn 0\r\n}\r\ncomplete -F _ce_clice clice\r\n<\/pre>\n
<\/p>\n
[Remember that any such changes will only take effect once you have restarted your terminal session or reloaded completion settings (see above).]
\nStarting at the bottom of this code snippet is the complete<\/b> command that links my command clice<\/b> with the function _ce_clice<\/b>. So whenever I now type clice and press tab, bash will call the function that makes up the rest of this code snippet.
\nThe _ce_clice<\/b> function starts in the same way as all other completion functions by declaring some local variables and then initialising them. Returning to the command line should that initialisation fail.
\nThose variables are:
\ncur<\/b>=what’s been typed of the current word,
\nprev<\/b>=the previous word in the command-line,
\nwords<\/b>=the command name and
\ncwords<\/b>=a count of previous words on the command-line
\n
\nThe boilerplate for Bash completion functions then has a gap where I declare a local variable opts<\/b> and load it with a space separated list of my command options before the boilerplate continues.
\nThe function provides a response back to the command-line by loading the COMPREPLY<\/b> variable with a list of valid completion results. If there is only one result then that will be inserted into the command-line.
\nTo generate that list of results the compgen<\/b> function is used to list all my command options in variable opts<\/b> that match the partially typed word in variable cur<\/b>.<\/p>\n
<\/p>\n
For filenames:<\/b>
\n<\/p>\n
In addition to the clice<\/b> command my project includes a shell script for managing how I edit programs. The script is called ce_edit.sh<\/b> which I place in \/usr\/local\/bin\/<\/b> but to make it easier to use I have aliased it to the command name edc<\/b> by adding alias edc=’. ce_edit.sh’<\/b> to my bash startup script ~.bashrc<\/b>. Note the space again in =’. ce<\/b> to ensure this command runs in my current process and not a spawned process.
\n
\nce_edit.sh<\/b> takes the filename that I wish to edit as an argument, so command-line completion would be very helpful. To set this up I added the following code to the same ce_completion.sh<\/b> script that my previous clice<\/b> command uses. I could use separate completion scripts but I prefer to keep everything related to my project together. As my completion commands call different completion functions then there is no confusion
\n<\/p>\n
\r\n_ce_edit()\r\n{\r\n\tlocal cur prev words cword\r\n\t_init_completion || return\r\n\r\n\tCOMPREPLY=( $( compgen -f ${cur} ) )\r\n\r\n\treturn 0\r\n}\r\ncomplete -F _ce_edit edc\r\n<\/pre>\n
<\/p>\n
As you can see, this contains the same boilerplate code with a couple of changes. Firstly compgen<\/b> is using a -f<\/b> option to generate a list of files in the current directory that match the partially typed filename in the cur<\/b> variable.
\nSecondly note that the complete<\/b> command at the bottom is linking my aliased edc<\/b> command to this new function and that it does not use the full script name of ce_edit.sh<\/b>.
\n
\nI can now type edc ce_c<\/b> followed by a tab to get edc completion.sh<\/b> which is really useful.
\n<\/p>\n
Beyond word completion:<\/b>
\n<\/p>\n
I could have stopped there but, having noticed that these completion functions are just Bash scripts, I wondered if I could do more than just complete the current word on the command-line?
\n
\nCompletion for the edc<\/b> command works well but I need to be in the right directory in the first place.
\n
\nAs a naming convention I give each project a two letter prefix (ce<\/b> for my “command-line coding ecosystem” project), I keep all the code for each project in a seperate directory (~\/Code\/CE\/<\/b> for this project) and I start each filename with the same project prefix (e.g. ce_completion.sh<\/b> and ce_edit.sh<\/b> for this project). So the source code for clice<\/b> can be found in ~\/Code\/CE\/ce_clice.c<\/b>
\n
\nSo in theory I could be in any directory and type edc ce_c<\/b> followed by a tab and my completion function should have enough detail to know where I need to go and which file I want to edit.
\nI’ve implemented this with the following additions to the _ce_edit<\/b> completion function.
\n<\/p>\n
\r\n_ce_edit()\r\n{\r\n\tlocal cur prev words cword\r\n\t_init_completion || return\r\n\r\n# Do we have at least two letters to determine the project directory?\r\n\tif [[  ${#cur} > 1 ]]\r\n\t then\r\n\t\tSOURCEDIR="\/home\/ben\/Code\/$(echo ${cur:0:2}|tr [a-z] [A-Z])"\r\n\t\tif [ -d "$SOURCEDIR" ]                          # does the project directory exist?\r\n\t\t then\r\n\t\t\tcd ${SOURCEDIR}\/\r\n\t\t\tCOMPREPLY=( $( compgen -f ${cur} ) )\r\n\t\tfi\r\n\tfi\r\n\r\n\treturn 0\r\n}\r\n<\/pre>\n
<\/p>\n
Some may shudder at the thought of a completion function changing your working directory but this works a treat and saves a lot of time when editing code at the command-line.
\nYou may have noticed that I haven’t managed to get the function to resolve ~<\/b> to my home directory so I’ve had to type that in full for now.
\n
\nThe echo<\/b> and tr<\/b> commands convert the first two letters at the start of a filename to uppercase for the directory name.
\nThis can’t resolve the project directory unless two letters are typed. For completeness I should look to enable a single letter, say ‘c’, to resolve to CE or to a list of all projects starting with ‘c’.
\nThat’s on my #TODO list but in the meantime I’m impressed by how easy Bash completion was to setup for my project.
\n
\nAll code for this and my other projects can now be found on my GitHub account: https:\/\/github.com\/agben<\/a><\/p>\n\n","protected":false},"excerpt":{"rendered":"
Command-line completion is a wonderful thing. If you get bored of typing a long filename (for example) you can just hit tab and it will complete the name for you. If the shell can’t be certain of which filename you wanted then you can hit tab again and either (depending on the shell) get a […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[9],"tags":[28,10],"_links":{"self":[{"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/posts\/282"}],"collection":[{"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/comments?post=282"}],"version-history":[{"count":11,"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/posts\/282\/revisions"}],"predecessor-version":[{"id":293,"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/posts\/282\/revisions\/293"}],"wp:attachment":[{"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/media?parent=282"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/categories?post=282"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.benningtons.net\/index.php\/wp-json\/wp\/v2\/tags?post=282"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}