In zsh, use zle’s vared built-in to quickly set a variable’s value interactively. vared pastes the variable’s current value in a command line ready for you to edit. When you hit <Return>, the line you’ve edited is set. It even works for arrays, like path.

References:

• zshzle(1)

When you just want to do some quick mental math, there’s actually an even nicer approximation: 5e5, or 500000. “But 500000 is a much farther off than 526000”, you might say, and you’d be right. But 5e5, or five hundred thousand, is less to remember, and when the time comes that you need to compute a closer figure, you already roughly know the error: it’s actually pretty close to 5%. 5e5 times 1.05 is 525000, less than a day under the “true” value.

So remember this: 5e5 minutes is 5% off, add 960.

:grep 'whatever'

Fills the quickfix list with matches.

Be sure and disable anything else which might stomp over the quickfix list, like ALE. Or, use :lgrep which fills the location list, which is scoped to a window.

Acting on the results

Run a command (search and replace, then write) for each file in the quickfix list:

:cfdo %s/whatever/whomstever/g | w

Here’s how you use it to develop a new Python CLI project.

Getting started

We’ll make a CLI called hello-snake, in a package and project called snake. First run poetry new to create the project skeleton.

tom@tomtop 🎪:~/tmp
% poetry new snake
Created package snake in snake

The resulting directory tree:

tom@tomtop 🎪:~/tmp
% tree snake
snake
├── README.rst
├── pyproject.toml
├── snake
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_snake.py

Change to the snake project directory. Poetry will manage a virtualenv for the project, tied to the project path and Python version. Create the virtualenv and open a pre-activated shell with poetry shell.

tom@tomtop 🎪:~/tmp
% cd snake
tom@tomtop 🎪:~/tmp/snake
% poetry shell
Creating virtualenv snake--jYlyyG6-py3.8 in /Users/tom/Library/Caches/pypoetry/virtualenvs
Spawning shell within /Users/tom/Library/Caches/pypoetry/virtualenvs/snake--jYlyyG6-py3.8
tom@tomtop 🎪:~/tmp/snake
% . /Users/tom/Library/Caches/pypoetry/virtualenvs/snake--jYlyyG6-py3.8/bin/activate
(snake--jYlyyG6-py3.8) tom@tomtop 🎪:~/tmp/snake
%

Our CLI entrypoint will be in the snake.console module. Create it in snake/console.py, next to snake/__init__.py, and add a run() function to serve as entrypoint.

def run():
    print("🐍")

Our project will ship a single executable, named hello-snake. Add it to the tool.poetry.scripts section of pyproject.toml.

[tool.poetry.scripts]
hello-snake = 'snake.console:run'`

This specifies that the program hello-snake executes the function run() in the module snake.console.

Install the package and its dependencies to the virtualenv.

(snake--jYlyyG6-py3.8) tom@tomtop 🎪:~/tmp/snake
% poetry install
Updating dependencies
Resolving dependencies... (0.2s)

Writing lock file


Package operations: 9 installs, 0 updates, 0 removals

...
  - Installing snake (0.1.0)

You can now run the new CLI as hello-snake.

(snake--jYlyyG6-py3.8) tom@tomtop 🎪:~/tmp/snake
% hello-snake
🐍

The snake package is installed to the virtualenv as “editable”, so that changes made in the project source directory are reflected immediately whenever you run hello-snake. To try that out, let’s make the snake a little angrier. Update console.py.`

def run():
    print("🐍 tsssssss")

And hello-snake includes the change without having to re-install our package:

(snake--jYlyyG6-py3.8) tom@tomtop 🎪:~/tmp/snake
% hello-snake
🐍 tsssssss

All of this should continue to work the next time you open a poetry shell for this project.

Packaging and distribution

It’s easy to share and distribute your new CLI package. Use poetry build to create tarball and wheel packages under dist/.

tom@tomtop 🎪:~/tmp/snake
% poetry build
Building snake (0.1.0)
 - Building sdist
 - Built snake-0.1.0.tar.gz

 - Building wheel
 - Built snake-0.1.0-py3-none-any.whl

The wheel file can be distributed to users, to be installed to their global Python environment:

tom@tomtop 🎪:~/tmp/snake
% pip install --user dist/snake-0.1.0-py3-none-any.whl
Processing ./dist/snake-0.1.0-py3-none-any.whl
Installing collected packages: snake
Successfully installed snake-0.1.0
WARNING: You are using pip version 19.2.3, however version 20.0.2 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.

Once the wheel is installed, the users can run hello-snake.

tom@tomtop 🎪:~/tmp/snake
% hello-snake
🐍 tsssssss

#!/usr/bin/env ruby --enable=jit

print "Hello, world!"

You test on your Mac and the program greets everybody in record time. Ship it!

Some time later, a user reports a problem. When they run the script, it seems rather slow; in fact, they’ve waited for hours and no one has been greeted.

The script still works (and it’s fast!) on your machine, so you ask the user about their environment. One difference stands out: they’re using Linux. So you spin up a Linux box and try the script. Sure enough, it seems stuck. You reach for strace, and see the same spew looping ad nauseam:

you@yourbox:~$ sudo strace ./hello
execve("./hello", ["./hello"], 0x7ffe721b38b0 /* 52 vars */) = 0
brk(NULL)                               = 0x55b53fddf000
arch_prctl(0x3001 /* ARCH_??? */, 0x7fff6a434040) = -1 EINVAL (Invalid argument)
access("/etc/ld.so.preload", R_OK)      = -1 ENOENT (No such file or directory)
openat(AT_FDCWD, "/etc/ld.so.cache", O_RDONLY|O_CLOEXEC) = 3
fstat(3, {st_mode=S_IFREG|0644, st_size=211342, ...}) = 0
mmap(NULL, 211342, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7f4088423000
close(3)                                = 0
openat(AT_FDCWD, "/usr/lib/libc.so.6", O_RDONLY|O_CLOEXEC) = 3
read(3, "\177ELF\2\1\1\3\0\0\0\0\0\0\0\0\3\0>\0\1\0\0\0`r\2\0\0\0\0\0"..., 832) = 832
lseek(3, 64, SEEK_SET)                  = 64
read(3, "\6\0\0\0\4\0\0\0@\0\0\0\0\0\0\0@\0\0\0\0\0\0\0@\0\0\0\0\0\0\0"..., 784) = 784
lseek(3, 848, SEEK_SET)                 = 848
read(3, "\4\0\0\0\20\0\0\0\5\0\0\0GNU\0\2\0\0\300\4\0\0\0\3\0\0\0\0\0\0\0", 32) = 32
lseek(3, 880, SEEK_SET)                 = 880
read(3, "\4\0\0\0\24\0\0\0\3\0\0\0GNU\0003\321\363P\3617(e\35t\335*V\272\321\344"..., 68) = 68
fstat(3, {st_mode=S_IFREG|0755, st_size=2149496, ...}) = 0
mmap(NULL, 8192, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f4088421000
lseek(3, 64, SEEK_SET)                  = 64
read(3, "\6\0\0\0\4\0\0\0@\0\0\0\0\0\0\0@\0\0\0\0\0\0\0@\0\0\0\0\0\0\0"..., 784) = 784
lseek(3, 848, SEEK_SET)                 = 848
read(3, "\4\0\0\0\20\0\0\0\5\0\0\0GNU\0\2\0\0\300\4\0\0\0\3\0\0\0\0\0\0\0", 32) = 32
lseek(3, 880, SEEK_SET)                 = 880
read(3, "\4\0\0\0\24\0\0\0\3\0\0\0GNU\0003\321\363P\3617(e\35t\335*V\272\321\344"..., 68) = 68
mmap(NULL, 1860536, PROT_READ, MAP_PRIVATE|MAP_DENYWRITE, 3, 0) = 0x7f408825a000
mprotect(0x7f408827f000, 1671168, PROT_NONE) = 0
mmap(0x7f408827f000, 1363968, PROT_READ|PROT_EXEC, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x25000) = 0x7f408827f000
mmap(0x7f40883cc000, 303104, PROT_READ, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x172000) = 0x7f40883cc000
mmap(0x7f4088417000, 24576, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x1bc000) = 0x7f4088417000
mmap(0x7f408841d000, 13240, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_ANONYMOUS, -1, 0) = 0x7f408841d000
close(3)                                = 0
arch_prctl(ARCH_SET_FS, 0x7f4088422580) = 0
mprotect(0x7f4088417000, 12288, PROT_READ) = 0
mprotect(0x55b53f654000, 4096, PROT_READ) = 0
mprotect(0x7f4088481000, 4096, PROT_READ) = 0
munmap(0x7f4088423000, 211342)          = 0
brk(NULL)                               = 0x55b53fddf000
brk(0x55b53fe00000)                     = 0x55b53fe00000
openat(AT_FDCWD, "/usr/lib/locale/locale-archive", O_RDONLY|O_CLOEXEC) = 3
fstat(3, {st_mode=S_IFREG|0644, st_size=3035216, ...}) = 0
mmap(NULL, 3035216, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7f4087f74000
close(3)                                = 0
execve("./hello", ["./hello"], 0x7ffe721b38b0 /* 52 vars */) = 0
brk(NULL)                               = 0x55b53fddf000
arch_prctl(0x3001 /* ARCH_??? */, 0x7fff6a434040) = -1 EINVAL (Invalid argument)
...

What’s going on? The script is just exec-ing itself in a seemingly infinite loop, and not really doing anything else. Why?

It turns out this comes from combining two papercuts, one which applies to shebangs in general, and another which applies to any which invoke /usr/bin/env.

the multiple argument shebang papercut

You can think of the shebang #!/usr/bin/env ruby --enable=jit as having two parts:

• The “interpreter name”, /usr/bin/env, which is a path to the script’s interpreter
• The remainder, ruby --enable=jit

Among other differences in shebangs, Linux and macOS treat the remainder differently. Linux parses the remainder into exactly one argument. In our ./hello example, Linux parses the shebang’s remainder to "ruby --enable=jit", combines it with the user’s arguments {"./hello"}, and executes "/usr/bin/env" with arguments {"/usr/bin/env", "ruby --enable=jit", "./hello"}.

macOS splits the remainder into several arguments if there are spaces. For ./hello, macOS parses the remainder to {"ruby", "--enable=jit"} and executes "/usr/bin/env" with arguments {"env", "ruby", "--enable=jit", "./hello"}.

It seems like the script would fail on Linux with this shebang, because it’s not asking env to find and run ruby. But it’s not saying something like, program not found: ruby --enable=jit, it’s hanging in that loop. Something else is afoot.

the #!/usr/bin/env shebang papercut

The first papercut doesn’t fully explain this loopy behavior. Another paper-sharp shebang, which also tries to pass two arguments to /usr/bin/env, fails differently on Linux:

#!/usr/bin/env ruby --verbose

echo "Goodbye, world"

you@yourbox:~$ ./goodbye
/usr/bin/env: ‘ruby --verbose’: No such file or directory

The difference is in the = character. Besides finding the first interpreter on a user’s PATH, env has another use: to “run a program in a modified environment”. One way it does this is to take arguments of the form VARIABLE=VALUE before the program and its arguments, and set those environment variables in the executed program’s process. For instance:

you@yourbox:~$ env DISPLAY=:0 xeyes -fg dodgerblue

executes {"xeyes", "-fg", "dodgerblue"} with the shell’s environment, plus the environment variable "DISPLAY" set to ":0".

Combining these papercuts, when Linux comes to execute ./hello:

1. An exec-family function reads "./hello"’s contents and parses the shebang into {"/usr/bin/env", "ruby --enable=jit"}.
2. The parsed shebang is combined with the argv passed to exec*() to ultimately execute {"/usr/bin/env", "ruby --enable=jit", "./hello"}.
3. env parses its arguments, sets the environment variable "ruby --enable" to the value "jit" and executes the program "./hello".
4. GOTO 1

./goodbye fails differently because env interprets the argument ruby --verbose as the program to run, since there’s no = character in it.

a solution: -S

Fortunately, modern versions of env have a solution. macOS and FreeBSD support the -S option, which does, quote the macOS manual:

   -S string
           Split apart the given string into multiple strings, and process each of the
           resulting strings as separate arguments to the env utility.  The -S option
           recognizes some special character escape sequences and also supports environment-
           variable substitution, as described below.

On Linux, GNU’s coreutils added the same flag to env in version 8.30, released July 2018.

So you can write a fancy, optionful shebang like:

#!/usr/bin/env -S ruby --enable=jit --verbose

puts "Hello, world!"

And ./hello will execute what you wanted.

references

Andries E. Brouwer posted a good writeup of shebang behavior on many unix-ish platforms.

While stuck in bed reading my phone Friday morning, a Hacker News comment caught my eye. Quoting user stevewodil:

If you’re having trouble getting out of bed, you can try using the 5 second rule to break your brain’s patterns and activate the prefrontal cortex. Basically you count down from 5 out loud (saying the numbers aloud is important) and at 1 you just jump out of that damn bed like NASA launching a rocket.

Not too convincing, but I had to get up, and felt trapped in a very familiar check Twitter-HackerNews-Lobsters-Fangraphs morning cycle of avoidance. It probably couldn’t hurt to try to “break my brain’s patterns” this way.

It turns out that, after a deliberate, five second countdown, out loud, I did indeed simply rocket out of bed. The trick seemed to work on me.

I thought that maybe a similar trick could work to break the brain pattern that’s making me avoid writing: count down from five and make a post. Post anything, just to unblock the process. So here comes a math’s¹ shitpost.

When it comes to skateboarding brand Supreme, with the poor quality of their products, if you ask me, they should call it, .

Thank you.

When the computer’s state is misconfigured, editor plugins may fail. Their failure may be catastrophic or rather subtle. System upgrades and changes irregularly trigger such problems, breaking editor plugins unexpectedly, and forcing the user to troubleshoot.

Neovim’s :checkhealth command is a big help. The editor and its plugins can define certain tests, called “health checks”, which examine the user’s environment for programs, configuration files, and the like. When each test succeeds or fails, its results are logged to a window for the user to read.

A failed health check represents a failed expectation about the development environment. It might also spell out the logic used by the health check to determine that the expectation failed.

For example, suppose you decide to try out Neovim’s python2 integration. So you read the help file and type in one of the examples, but are greeted with an error message.

:py print(sys.version)
E319: No "python" provider found.  Run ":checkhealth provider"

You execute that command, which makes Neovim run health checks for its “provider” components.

Neovim’s Python 2 provider is in a degraded state. Apparently, none of the python2 interpreters that were found could import the neovim module. Like the message suggests, you read :help provider-python.

...
- For Python 2 plugins, make sure Python 2.7 is available in your $PATH, then
  install the package systemwide:
    sudo pip2 install --upgrade pynvim
  or for the current user:
    pip2 install --user --upgrade pynvim
...

You try that pip2 command in another terminal, and then run :checkhealth provider again.

All looks good, so you try the :py command again:

:py print(sys.version)
2.7.16 (default, Apr 12 2019, 15:32:40)
[GCC 4.2.1 Compatible Apple LLVM 10.0.1 (clang-1001.0.46.3)]
Press ENTER or type command to continue

It works! Now you can get your Python on in the editor.

I think what makes this experience so nice is that this health check plainly lists three key sets of facts: the preconditions for the system to work correctly; the system’s current status with respect to those preconditions; and the logic used to determine that status. The plugin is capable of diagnosing its own issues and explaining the problem in words. This is a massive improvement over, say, making sense of a stack trace in what’s likely someone else’s code.

For more on health checks, see Neovim’s documentation, or :help pi_health.