sglavoie.com – Tag: Vim

Black: A Python Formatter to Brighten Your Workflow

Sébastien Lavoie — Sat, 13 Jul 2019 13:10:00 -0500

What is Black?

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

Black will take less than ideal code and will automatically reformat it according to the PEP-8 style guide. It will take care of many things, including the following (taken in that order from README.md in Black’s repo):

Wrapping lines properly by shortening as much as possible single statements;
Break long lines;
Remove superfluous empty lines;
Take care of adding trailing commas where necessary;
Convert single quotes (') to double quotes (");
Convert numeric literals to lowercase (0XAB to 0xAB);
Superfluous parentheses are removed;
Split call chains on different lines;
Works from the terminal and support many code editor integrations (Emacs, Vim, VS Code, Sublime, etc.).

Now that it’s clear why it can be a good idea to use it, let’s see how it works with Vim and the terminal.

How to use it?

First, we need to install it using Python 3.6.0+:

bash

$ pip install black

That’s it!

Use it from the terminal

In its simplest invocation, we can use Black by specifying a file or a directory by typing:

bash

$ black path_to_file_or_directory

It doesn’t come with many options as its goal is to automatically format code consistently, but you can find out more about this tool in the following way:

bash

$ black --help

Use it with Vim

Using Black as part of your workflow in a code editor is where I believe it really shines, because you can see almost in real-time when you make a formatting mistake, which will help down the road in committing less sins.

Integrating Black with Vim or Neovim is quick and painless, adding a simple line in your .vimrc or init.vim file. You can also proceed to do a manual installation without a plugin manager as explained in the GitHub repository.

With vim-plug:

 vim
 
Plug 'python/black'

With Vundle:

 vim
 
Plugin 'python/black'

Once the plugin is installed, it may well be convenient to automatically format Python files when saving the buffer, which can be accomplished by adding the following line to the configuration file:

 vim
 
autocmd BufWritePre *.py execute ':Black'

By default, Black works surprisingly well on its own. I only went ahead and changed the default line length from 88 to 79 characters by also adding this line:

 vim
 
let g:black_linelength = 79 " default is 88

Finally, it’s worth noting you can update Black at any point from the terminal with pip and you can also do it directly from within Vim/Neovim with this command:

 vim
 
:BlackUpgrade

Vim will then output something along those lines:

Upgrading Black with pip…

DONE! You are all set, thanks for waiting

Any example?

Taking a random Python 3.6+ code sample, we could originally have something like this (hopefully not):

 python
 
 
 
 for source in data_sources :


 # Retrieve a list of all matching log files in `source`
 log_files=glob.glob( f'{source}/{LOG_NAME}*' )
 if log_files == [ ]:
 print(f'\nThere is no log file to delete in {source}.')
 continue
 else :
 print(f'Log files in {source}:')
 for log_file in log_files:
 if (ARGUMENTS.remind): REMINDER_IS_SET = True
 print(
 log_file
 )
 message = (
 '\nDo you want to delete log files ' 'for this source? (y/n) '
 )
 if (user_says_yes( message = message )) :
 for log_file in log_files: os.remove(log_file)
 print(
 'Log files deleted.'
 )
 continue
 else : continue
 print( 'Exiting script...' )
 sys. exit(0)

Running Black, we will get something that’s quite a bit more palatable:

 python
 
 
 
 for source in data_sources:

 # Retrieve a list of all matching log files in `source`
 log_files = glob.glob(f"{source}/{LOG_NAME}*")
 if log_files == []:
 print(f"\nThere is no log file to delete in {source}.")
 continue
 else:
 print(f"Log files in {source}:")
 for log_file in log_files:
 if ARGUMENTS.remind:
 REMINDER_IS_SET = True
 print(log_file)
 message = (
 "\nDo you want to delete log files " "for this source? (y/n) "
 )
 if user_says_yes(message=message):
 for log_file in log_files:
 os.remove(log_file)
 print("Log files deleted.")
 continue
 else:
 continue
 print("Exiting script...")
 sys.exit(0)

Conclusion

I think the results speak for themselves: enforcing a style with a tool like Black is definitely useful to avoid arguments about conflicting coding styles. It lets you focus on what matters instead: being productive while providing value to the world.

Tag Navigation in Vim

Sébastien Lavoie — Fri, 19 Apr 2019 17:52:00 -0500

Navigate inside the current buffer

There is a command gd that stands for Goto local Declaration. It is quite useful when looking for a variable inside the current buffer as it allows to jump to where it is declared when the variable is under the cursor. Using that command, you can also find where a function is declared and it will find the first occurrence in the current function. If looking for the first occurrence in the buffer, gD (Goto global Declaration) will do the trick. You can jump back and forth to where you were with the commands Ctrl + O (older position) and Ctrl + I (newer position) in normal mode.

Navigate inside all buffers within the current project

To be able to jump between buffers and go back to the origin of a declaration when it is imported in the current module, generating tags comes in very handy as it allows you to use the command Ctrl + ] to jump to a tag, just like when using the help pages in Vim.

To make this work, we can conveniently use ctags. First, we need to make sure it’s installed on the system as follow:

Debian/Ubuntu

bash

sudo apt-get install ctags

bash

sudo apt-get install exuberant-ctags

OS X

bash

brew install ctags

You can put the following command in your configuration file to be able to generate the necessary tags inside Vim by typing MakeTags in command mode:

 vim
 
command! MakeTags !ctags -R .

This will make it easy to remember how to do it. After that, open an existing project in its root directory and use this newly created MakeTags command to generate the tags. This will create a file named tags in the current working directory*. Now, you will be able to open any file inside your project and jump to all the available declarations with Ctrl + ].

* _{Note: This will create tags recursively from the current working directory, not from the path matching the current buffer.}

If you go to a tag that leads you a few declarations away in one file or another, you can come back with Ctrl + T. Here is a clear explanation from Vim’s help:

The most obvious way to use this is while browsing through the call graph of
a program. Consider the following call graph:

	main ---> FuncA ---> FuncC
	 ---> FuncB

(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
you can CTRL-] to get to FuncC. If you now want to go back to main you can
use CTRL-T twice. Then you can CTRL-] to FuncB.

To keep those tags useful when you update your project, you can map a sequence that saves the buffer you are working on and then regenerates the tags automatically. Here is an example:

 vim
 
nnoremap <leader>W :w<CR>:MakeTags<CR>:echo 'ctags have been updated.'<CR>

And on this note, we’re ready to conquer the world.

Using Vimwiki for Note-Taking

Sébastien Lavoie — Mon, 03 Dec 2018 13:26:00 -0600

What is Vimwiki?

From the official website:

Vimwiki is a personal wiki for Vim – interlinked, plain text files written in a markup language.

As this relies upon Vim’s power to write content in a simple format, this quickly became a viable option to organize more and more notes!

What were the other options considered?

I have used various approaches in the past for different purposes and reasons, including Evernote, Simplenote, Microsoft OneNote, Google Docs, Boostnote, Freeplane/FreeMind (mind-mapping), Workflowy and even plain .txt files. Each has its pros and cons, but I then decided to limit my options based on the following self-imposed requirements:

It has to be available on Linux. Right from the start, this would disqualify many applications such as Notational Velocity, Bear, Quiver, Paper, Ulysses and Squid.
It has to be open source as this is a philosophy that I strongly embrace. Plus, having the ability to freely modify it and contribute to the project is an important additional bonus. Adiós Evernote, Google Docs, Dropbox Paper, Microsoft OneNote, Workflowy and Quip.
It has to be fast to use and it has to make it possible to express oneself in more than one way. Say goodbye to Freeplane (otherwise great for general brainstorming!) and FreeMind (which has been abandoned by its own developers): both are relatively slow on an old machine because they use Java and it is quite a stretch to use them for something other than mind maps. In that same category would disappear draw.io, which is fantastic for making flowcharts and diagrams!
It has to be versatile enough to handle features such as including images, links and attached files and have a way to perform search and replace. Ciao Simplenote which is, well, simple. Even though it doesn’t fit the bill in this case, it remains a great option as it can synchronize your notes with many different devices (iOS, macOS, Android, Windows and Linux). It has a feature that allows you to move a slider which acts as a timeline and shows you a different version of your note since its creation with the actual date and time down to the minute for each restore point. You can also use tags and Markdown and it has options to share and collaborate with others. Highly recommended!
It should have a hefty user base to back it up. This would exclude text editor plugins such as atom-notes for Atom or VSNotes for VS Code, which also lack features for accomplishing all of the above.
On top of everything else, it has to be available offline, in a portable and readable format. Now, after discarding most options, we are left with Boostnote which uses CoffeeScript-Object-Notation and Vimwiki which has its own Wiki syntax that’s similar in many ways to Markdown*. Those are the strongest contenders that I could think of but of course, if you would like to share your recommendations, please do so in the comments below!

* _{I somehow discredited
Emacs simply because I started
to learn Vim first and since I’m still far from understanding all of
its features, I had to postpone the discovery of Emacs.}

One feature-rich alternative to Vimwiki

After settling down on Vimwiki, I later found out about Joplin, which comes with many great features and characteristics such as:

Free & Open Source
Manages notes and todo lists
Search across all notes/todos
Import/Export from/to various formats, including Markdown and even imports from Evernote
Support for attachments
Tags
Synchronization with multiple providers such as Dropbox, Nextcloud, OneDrive and even your own private cloud
Available for Windows, Linux, macOS, Android and iOS
Web Clipper integration

This application left me a great first impression to say the least and I will make sure to stay up to date on its active development, which you can follow on GitHub.

Why did Vimwiki win in the end?

In short

The modal nature of Vim makes it very hard to enjoy any other text editor once you get used to it. The learning curve is quite considerable and nearly infinite, but this is also why I think it is worth investing more time to master it as it has proven to be an everlasting piece of trusty software.

There is a feature in Boostnote to set the Editor Keymap to vim so that you can edit text in a very similar way, but then you miss out on Vim’s Command mode which adds tremendous extensibility and the ability to create any mappings you wish on the fly.

Expanded edition

Boostnote comes with nice features such as Tags, the ability to set multiple storage locations for notes, a Preferences panel to adjust many options, a feature to add code snippets, real-time preview of Markdown being edited, etc. Make no mistake: this is a great program. But there are many Vim features that are hard or impossible to replicate and everything that you can do in Boostnote can be done in Vim also (ctags, emmet syntax, plugins for Markdown, etc.).

For starters, the terminal integration is obviously unmatched. In Vim, CTRL+Z will stop Vim and gives you access to the terminal to do whatever you want to do. From that point, you can simply switch back to Vim by issuing the command fg. The terminal integration goes even further: you can have full access to the terminal inside Vim buffers since Vim 8.1 and that is a feature that has been available in Neovim for even longer.
Even though vim mode can be enabled to edit text, you have to use the mouse to get many tasks done and the editing window can loose the focus. On the other hand, Vim is just one single window by default that you can split however you want, including adding tabs if your heart tells you to.
You have to open your notes with Boostnote if you want them to be fully readable out of the box. Vimwiki does almost no processing with the content of the files so that it is very easy to open them with any other text editor. On a related note, it is much easier to export many notes at the same time with Vimwiki. Boostnote does have a few options to export individual notes (.md, .txt, .html and print), but it is not as user-friendly with many notes.
Vimwiki makes it easy to link notes together and navigate between them, even within subfolders: highlight text, press Enter to create a link and open a new note, write your note and press Backspace to go back to where you created the link. That’s quick and easy!

Conclusion

In the end, it is a matter of taste as those programs are indeed very distinct. Boostnote has a polished interface, is much easier to use and has many settings easily changed. Vim/Neovim, on the contrary, requires a lot of initial effort both to understand and to set up according to your needs, but it does deliver a good dose of productivity… Eventually!

An honorable mention goes to Simplenote, which is a joy to use with mobile devices and allows for quick synchronization between different devices across all the supported platforms.

Where things really get in favor of Vim, you could mention the extensive help system (command :help), the use of macros, words and lines completion, the dot (.) command, the many registers at your disposal for different tasks, the impressive amount of plugins available, the ways in which you can configure mappings, functions… But that’s for a whole new story!

Tmux Integration with Vim/Neovim — First Steps

Sébastien Lavoie — Mon, 19 Nov 2018 20:31:00 -0600

tmux integration

tmux offers many advantages in the context of remote access to another machine, but it also shines on a local setup! Here is how I currently like to set it up.

Configuration file

 ~/.tmux.conf
 bash
 
 
 
# split panes using | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

# switch panes using Alt-arrow without prefix
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D


# Enable mouse mode (tmux 2.1 and above)
set -g mouse on

source-file "${HOME}/.tmux-themepack/blue.tmuxtheme"

This is all very self-explanatory. Many themes can be found here.

Automating the launch of a default session

This is a small Bash script that I like to have for automatic set up of a development environment with tmux and Vim/Neovim. As my current workflow, I enjoy the following:

 ~/.tmux_default_session.sh
 bash
 
 
 
#!bash
# var for session name (to avoid repeated occurences)
sn=dev

tmux new-session -s "$sn" -d

# Create 3 windows
tmux new-window -t "$sn:0" -n "nvim"
tmux new-window -t "$sn:9" -n "python"
tmux new-window -t "$sn:8" -n "terminal"

# Split terminal window vertically, then split the right pane
# horizontally, then switch to the left pane (identified by `FOCUS IS
# HERE`).
# _________________
# |>_ |>_ |
# | | |
# | FOCUS |-------|
# | IS |>_ |
# | HERE | |
# -----------------
tmux split-window -h
tmux split-window -v
tmux select-pane -L

# Set up Neovim ready to open files
tmux send-keys -t "$sn:0" C-z 'nvim .' Enter

# Set up alias for IPython and clear the screen when entering IPython
tmux send-keys -t "$sn:9" C-z 'ipython' Enter
tmux send-keys -t "$sn:9" 'clear' Enter

# Select window #0 and attach to the session
tmux select-window -t "$sn:0"
tmux -2 attach-session -t "$sn"

Aliases to make use of

I add the following aliases in ~/.bash_aliases to automate a chunk of the workflow:

 ~/.bash_aliases
 bash
 
 
 
# This will launch tmux with the desired configuration
alias dev='bash ~/.tmux_default_session.sh'

# This will kill the tmux server if the need arises. By detaching from
# the tmux session, you simply run this command and can reattach easily
# to the default session configuration on another project.
alias kdev='pkill tmux'

# If the session has been detached but the tmux server is still running,
# I use the following alias to quickly reattach to the default session
# named `dev` in that example.
alias adev='tmux attach-session -t dev'

tmux demo

(click to open image)

The content of this post can be found on GitHub.