TT: Console navigation the easy way with Apparix

Today I will start a new series where I present small tools which I use on a daily basis and considered very useful. These tools haven’t to be killer applications, but doing the task they are written for, very well. Therefor also the name of this series: TT, which stands for ToolTips. Most of this applications are open source, so I will take the opportunity to say “Thank you” to all the people out there, which create such cool stuff in there free time.

We start with a tool called Apparix.

Console?

As you may know, I’m a keyboard addict. My preferred OS is Linux, I use Ion3 as the window manager, rxvt-unicode as terminal application and (g)Vim as the preferred editor. On the other side I have a MacBook Pro as laptop and love the possibilities of Mac OS X. How does this come together? Well, all these tools are available on Mac OS X as well. The X11 port of Mac OS X is getting better with each release and using it in fullscreen is good enough. Mac OS X is based on BSD and together with MacPorts, there is nothing I missed until today. As I have to work really platform independent, there is Windows. Vim is available, but working console based (read: command.com) isn’t really much fun. There is of course mingw, but I never managed it to create a work environment like on Linux/UNIX. Anyway, I work not that much on Windows, so I can live with other tools there as well (a really good free editor is Notepad++ and if you hate Explorer have a look at Altap Salamander). So the question remains: Console? I have the feeling using the keyboard within a console application is much faster than clicking around with the mouse. This doesn’t mean I like to type every single character when starting an application or changing the current working directory. Many modern command interpreters, like the Bash, have built in word expansion. This allows you to use the tabulator key for fast expansion of typed characters for a given set of commands. Of course this makes the console life much more easier. But there is more!

Bookmarking important directories

Usually, I’m working on projects. One project is VirtualBox. Other might be some private stuff, like personal letters or other development I do. As the regular user organize his projects in directory trees it make sense to bookmark them. Most people believe bookmarking is something Internet specific, but this isn’t true. Bookmarking means getting access to an important information very fast, without remembering the exact location of this information. This is exactly what Apparix does. It bookmarks directories and make these bookmarks easy accessible on the console. So I have bookmarks for sub-projects within VirtualBox, like the GUI or Main. Getting there is as easy as writing to vgui. It’s the same as writing cd /bin and it even provide word expansion of the available bookmarks. In this case the bookmark is vgui and it expand to the GUI directory within the VirtualBox source tree.

How does this work?

Installing Apparix is pretty simple. You will find all the information on the website. The important part is the integration within your shell. You need to extent your .bashrc. One way is to add the functions you need into .bashrc. Alternatively you can download the file .bash_apparix and source it in your .bashrc. When you have done this and start a new shell, you should navigate to a directory you like to bookmark. There you type bm to create your first bookmark. Afterwards, regardless what your current working directory is, you could execute to DIR_NAME to get there. Of course you can name the bookmark other than the current directory name, by using bm MY_NAME. By executing als all bookmarks are shown. There is much more possible of course. See the documentation for more information. Anyway, this is the main use case for Apparix, so there is not much more to say. Really?

Using the Apparix database for other applications

The cool thing on many Linux applications is, they are saving their data in simple text files. Also Apparix. The bookmark “database” is saved in a file called .apparixrc. It’s a simple text file, which is easy to parse. It looks like this:

j,vbox,/Users/poetzsch/projects/vbox
j,VirtualBox,/Users/poetzsch/projects/vbox/src/VBox/Frontends/VirtualBox
j,Main,/Users/poetzsch/projects/vbox/src/VBox/Main
j,Runtime,/Users/poetzsch/projects/vbox/src/VBox/Runtime
j,Installer,/Users/poetzsch/projects/vbox/src/VBox/Installer/darwin
j,cv,/Users/poetzsch/projects/private/office/latex/cv
j,dow,/Users/poetzsch/Downloads

This allows the usage of this information in other contexts as well. One example is Vim. As I mentioned earlier, this is my main editor. So it would be cool to use the bookmarks, I already have, there as well. To easy change the current directory in Vim, add the following to your .vimrc:

command! -complete=custom,BmCe -nargs=1 To :call BmTo('<args>')
fun BmCe(A,L,P)
 return system("awk 'BEGIN{FS=","}/j,/{print $2}' ~/.apparixrc")
endfun
fun BmLs(dir)
 return system('apparix '.a:dir.' | tr -d "n"')
endfun
fun BmTo(dir)
 execute ':cd '.BmLs(a:dir)
endfun

After restarting Vim, it is possible to navigate with :To MY_BOOKMARK to any directory known by Apparix.

Conclusion

One simple task, getting to a directory where you are often have to be, with one simple solution. Thats all to say about Apparix. It does this in a very simple way, which is fully integrated into the Bash and the saved information could be used by other applications as well.

8 thoughts on “TT: Console navigation the easy way with Apparix

  1. Hi, apparix author here. Nice article, and I’m quite thrilled about VIM integration. It gives an error for me upon attempting ‘To m’, giving:

    Error detected while processing function BmTo:
    line 1:
    E172: Only one file name allowed: :cd — portalse /homes/stijn/topaz/micans/m
    cl/mcl/src— expansionsj CVS /homes/stijn/topaz/micans/

    My vim-fu is very, very, very weak. Can it be a version issue? Mine is 7.0.

    Finally, a feature not mentioned I believe, but one that I use a *lot* is the ability to type ‘to m src’ to go to the subdirectory src of bookmark m. It completes as well, so you could do ‘to pr data/long-version-name/images’, completing on all the components of that subdirectory.
    Thanks, Stijn

    1. Hi Stijn,

      cool that you found your way on my blog. Thanks again for this useful application. On a quick look I don’t understand the error message you got on Vim, but I have to say that I don’t use the more advanced features of Apparix like portals and such. So maybe the parsing isn’t done right in this situation.

      Using the expansion of sub folders of the bookmark is indeed another useful feature of Apparix. Thanks for pointing this out for the readers of my blog (I know this of course ;)).

      Chris

    2. Hi, I found the issue. In your vim code the first line should read
      command! -complete=custom,BmCe -nargs=1 To :call BmTo(”)
      The was presumably eaten away by HTML parsing. Also, I would recommend adding -favour rOl (thats arr, OH, ell) to the apparix invocation, that way it will also work if you identical bookmarks to multiple recommendations (that’s something I do; I have a ‘now’ bookmark that gets updated every now and again, I like to keep the old ones). Finally, it might be nice to execute cd only if apparix returned succesfully. I am going to try .. . Will definitely mention this page and this code on the apparix web site.

      1. Amusingly and rather silly, it was eaten again. I’ll try to escape the HTML in there and add a tiny bit of formatting. Fingers crossed, here goes:

        command! -complete=custom,BmCe -nargs=1 To :call BmTo('<args&gt')
        
        1. It would be great if some kind of editing were possible. Anyway,

          command! -complete=custom,BmCe -nargs=1 To :call BmTo('<args>')
          

Leave a Reply

Your email address will not be published. Required fields are marked *