sglavoie.com – Tag: Neovim

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.

Using Embedded Terminals Inside Neovim

Sébastien Lavoie — Wed, 16 Jan 2019 17:32:00 -0600

Terminals & Neovim

Terminal buffers are a built-in feature of Neovim. This means that terminals can be launched inside Neovim just like any other buffer, may it be a split window, a new tab or an independent buffer. Why is this so useful? Be prepared to be amazed.

(click to open)

Seamless integration with Vim commands

For a start, terminals are not just opened inside Neovim: they are truly integrated. When you type the letter i in a terminal buffer, it switches to a new mode, Terminal, where you have access to all underlying features of a regular Bash terminal, such as CTRL + r to search, tab completion of commands, CTRL + w to delete a word backwards or CTRL + u to delete the whole line backwards.

When you escape the Terminal mode, you switch back to Normal mode, where all Vim commands are available as usual, such as navigation, search, etc. Where this gets interesting is when you consider that the terminal is just like any other buffer (except it’s not modifiable) and so you can for instance copy its content or paste into it from different registers. You can split them, view the line number, get automatic scrolling when output appears in Insert mode, you can switch back to Normal mode at any time even if a command hasn’t completed… and of course all commands like gt to go to another tab work as always.

Terminals get supercharged with the power of Vim

This is getting exciting (at least for me). Now, having a terminal with more power is useful in many cases:

A whole terminal session can be saved to another file easily by copying the desired range (:%y to copy everything, for example).
Instead of having to scroll with the mouse, all Vim commands are available to search and navigate through the buffer: gg to go to the beginning of the session, G to go to the end, 12G to go to line number 12, / or ? to search forward and backward respectively. You can even set local or global marks to jump back and forth to precise lines consistently!
It’s even possible to send commands directly to a specific terminal or set up a REPL to execute any code, either a selection, a line or a range of lines. I don’t personally use that feature yet, but I see how useful that can be and you can too if you watch this [screencast presented by Drew Neil](https://thoughtbot.com/upcase/videos/neovim-sending-commands-to-a- terminal-buffer) on thoughtbot.com.
If the terminal is opened in Normal mode, the cursor and the current position are kept intact even though new output could appear, such as would be the case if you are running a server in the background or waiting for a system update to finish. This is especially nice for instance if you are trying to debug a web application: you can leave the cursor exactly where you would like to keep reading the output and never get lost… Plus you have the ability to easily move around, search and copy like a ninja!

The workflow is more compact and centralized

Because the terminals are running with one Neovim instance, you get everything in the same place, which is usually how you need to access your work anyway. If for some reasons you need to have multiple instances of Neovim running, this is possible too and in that situation you could simply split them into different workspaces.

Because everything is launched with Neovim, every terminal left open will also be exited when you close Neovim, shutting down any server or quitting any background interaction going on in the terminals. I have found that this behaviour is what I expect pretty much all the time because the idea of having a terminal inside a working session of Neovim is to work on something related, so it makes sense to close everything that’s to do with a single project or task when you exit the text editor. No need for CTRL + d or exit anymore!

Terminal settings to consider

I don’t use many settings or mappings related to terminals, but I guess the nicest one is to remap the Escape key because by default, this is a weird mapping that leads to twisted fingers (<C-\><C-n>). Here is what I currently have in my init.vim file (the equivalent of .vimrc for Neovim):

 vim
 
 
 
set termguicolors " Make colors look better in terminal

" Exit from terminal buffer (Neovim) more easily (remaps Esc key in
" terminal)
tnoremap <C-[> <C-\><C-n>

" Open terminal buffer (M stands for the Alt key)
nnoremap <M-t> :te<CR>

" Switch to terminal buffer automatically (when only one terminal is
" open)
nnoremap <M-0> :b term://<CR>

" Move between windows exactly the same way as usual
tnoremap <C-j><C-k> <C-\><C-N>
tnoremap <C-h> <C-\><C-N><C-w>h
tnoremap <C-j> <C-\><C-N><C-w>j
tnoremap <C-k> <C-\><C-N><C-w>k
tnoremap <C-l> <C-\><C-N><C-w>l

Conclusion

This was a quick overview of a feature that I have neglected for some time but recently realized how well it integrates with my workflow. You can find some more information by typing :h terminal. If you already use Neovim, it’s worth giving it a try! Otherwise, it’s worth giving Neovim a try.

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.