tl;dr

My mini note-taking CLI tool jot can now back-up jottings to a GitHub gist, thanks to GitHub’s gh CLI.

Always Be Jotting

Last time I told you I’ve been using jot for months. It’s my opinionated CLI tool to record stuff that I can reflect on later. I just type something like jot "promoted synergy" in the terminal and move on.

And now there’s 1200 jottings.

But there’s only one text file.

A backup might be handy, eh.

Copy-waste

I had been copy-pasting the jot file into a private GitHub gist¹ at the end of each week. Gists are used mostly for throwaway scratch files, code snippets and text files.

Given that jot is a personal project and I want to make things easier for myself², I think this is fine as a backup host. It’s what I’m doing already, after all.

But oof, copy-paste? We can do better. So I built in a new option into jot to support upload to a gist.

This is now available in the dev version (v0.3.0.dev1) available from GitHub like uv tool install git+https://github.com/matt-dray/jot³. I’ll be testing it for a while before it goes in the stable release⁴.

With this dev version I can now run jot -u (short for --upload) every so often. No more filthy copy-pasting.

jot -u
✅ Success

Gistjacking

Well, there’s a bit more to it than that.

There are some obvious checks and inputs required when jot -u is run. The upload_jottings() function has a series of hoops:

1. Is the GitHub CLI gh installed? If not, prompt installation.
2. Is there an internet connection? You can’t upload if not, obv.
3. Is the user logged into a GitHub account? If not, prompt gh auth login.
4. Is there a GIST_ID value in the config file? If not, prompt for it (it’s the 32-character string in the gist’s URL, or found via gh gist list).
5. Does the GIST_ID match an actual gist ID in your account? The gist must already exist.
6. Is there a jot file path recorded in the config? If not, prompt the user to create one.

If that’s all cleared, it runs subprocess.run(["gh", "gist", "edit", gist_id, jot_path]) to upload the contents of the jot file. This is equivalent to running the equivalent gh command directly from the terminal, but with extra defensive steps.

In other words, I’ve hijacked gh to do all the hard work, lol. This is great, because I want jot to be minimal and require little maintenance. Thanks Michaelsoft.

I jot u

It’s a clear limitation that --upload only uploads to a GitHub gist. I’m a simple chap, this is fine for me for now.

But the interface could be tweaked in future to allow for other hosts. Maybe in the form jot --upload <host>. The CLI logic could react to <host> to decide what credentials and values are needed for the upload.

Oh no, what if someone contributed to my poor little project with their favoured host? 🥺

tl;dr

I’ve now used my CLI tool jot nearly 1200 times. It’s been a useful low-friction way to remember what I’ve been up to for later reflection.

One-shot jot

I’ve written about jot before: my very simple and opinionated Python command-line tool for jotting down little timestamped notes to myself.

In an open terminal I can just:

jot "put one of the new coversheets on the TPS reports"

And it gets automatically prepended to a text file with the date and time.

Rinse and repeat throughout the day.

A jot of bother

Regular readers know that I make stuff and… move on.

Sike! I’ve actually been using this one a whole bunch.

In fact, I’ve been jotting things down every work day since August 2025 and have banked well over 1000 jottings.

But has it actually been useful?

Forget me jot

I have a leaky brain.

This causes a problem when I try to write weeknotes and timesheets. It also means I struggle to reflect on my achievements, which is pertinent given my upcoming annual appraisal.

So, for these past months, I’ve been taking a couple of seconds to jot down what I’m doing as I’m doing it.

I’ve been writing things in the style of git commit messages: they start with a verb and are short and sweet. For consistency, I’ve been referring to the name of a repository where possible and writing down colleagues’ names. For example: jot "released version 1.0 of the package" and jot "called morag to discuss app development"¹.

Typically they’re about what I did, rather than the outcome. I also record little human interactions and feedback, which can otherwise fall through the cracks.

At the most basic level, the simple act of writing things down has helped me recognise the volume and variety of my tasks. Meanwhile, jot’s options like --list and --search (with --from-date and --to-date) have helped me filter down that large volume of information when I want to get more analytical².

This is not a comprehensive business tool for reminders, to-do lists, minutes and actions. It’s just a brain outside my brain.

Switch to the terminal; write a sentence; go back to work. And now I have 1194 reminders of what I’ve been up to. Little effort to help plug a big gap.

In the PyPIline

I started developing jot to learn ‘how to Python’ and write CLIs. I think that’s a success, but where next?

Well, I’ve formalised its existence by uploading it to the Python Package Index (PyPI) to make it’s more readily available.

You can now find it as jot-cli on PyPI, as of version 0.3.0. Yes, you have to install ‘jot-cli’ rather than ‘jot’, because the name is already taken on PyPI. But the command still remains jot in the terminal³.

You could install⁴ with uv⁵:

uv tool install jot-cli

Then, to upgrade:

uv tool upgrade jot-cli

The development version is available from GitHub like:

uv tool install git+https://github.com/matt-dray/jot

Note that the GitHub repo is still called ‘jot’ despite it having to be called ‘jot-cli’ on PyPI⁶.

Thnks fr th Mmrs

Right now it works for me, which is the bottom line.

I know some others have had a go and found it useful too. Thanks in particular to:

• Olivier for submitting code to let the list of jottings to be filtered by date
• my work colleagues (especially Fran who have provided feedback in our ‘sidequests and suport’ sessions.
• Adriana for blue-sky thinking (but mostly for listening to me ramble on about it)

I want functionality to remain simple, so future updates will mostly be about improving the underlying code and user interface rather than adding entirely new features.

I have, however, been developing an option to upload the file to a GitHub gist as backup. But maybe that’s too radical.

That’s yer jot

So, is jot a world-beating bit of software? No, there’s plenty of similar and more powerful tools out there⁷.

And has the dogfood been delicious? Aye, gourmet, and I’ll continue to chow down.

jot "wrote a blog post about jot's release to PyPI"

tl;dr

I messed around again with tyle, my Python-CLI roguelike-like. Now it has godlike destruction and creation.

The beast at Tanagra

Before now, you could install tyle¹ and type tyle into your terminal to generate a tile-grid with a player, surrounded by floor (.) and wall (#) tiles, as well as ‘fog of war’ (?) beyond a certain distance.

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . # . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . @ . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
Move (WASD+Enter): 

What next? I wanted to start thinking about enemies, but I did this with r.oguelike already and wanted to try something different first.

I’m old enough to remember when Minecraft was first cool. What is Minecraft? Break block make block.

We can mimic this in two dimensions pretty easily.

Jinza, when the truth was uncovered

In tyle, the underlying map is a TileGrid-class object, which is just a list of lists of Tile-class objects. These tiles currently take one of two values: they’re traversable floor (.) or untraversable wall (#).

What if you could just… remove the obstruction?

Well now you can. For example:

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . @ # . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
Facing: right
Move [wasd], [b]reak, [p]lace, [q]uit: 

We’re facing right and the adjacent tile is a wall. Inputting b will break the wall.

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . @ . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
Facing: right
Move [wasd], [b]reak, [p]lace, [q]uit: 

What’s actually happening is that the tile adjacent to the player’s direction is being replaced with a floor tile in the TileGrid.

To help the player, I’ve added to the UI a reminder of which way the player is facing, decided by the last direction of travel.

In tile.py, we can interpret an input of b to mean ‘update the Tile in the specified location’:

if move == "b":
    row_change, col_change = direction_changes[self.direction]
    target_row = self.player.row + row_change
    target_col = self.player.col + col_change
    
    if not (
        0 <= target_row < self.n_rows and 0 <= target_col < self.n_cols
    ):
        return True

    target_tile = self.tiles[target_row][target_col]
    
    if target_tile.symbol == self.tileset["wall"]:
        self.tiles[target_row][target_col] = Tile(
            self.tileset["floor"], True
        )
    
    return True

In short: if the player submits b, then replace the tile in the direction they’re facing with a floor tile. This gives the illusion that the wall has been destroyed.

Sokath, his eyes uncovered

Naturally, we can do this in reverse. Instead of breaking a wall block, we can build one.

Pressing p will place a wall tile in the direction we’re facing (right in this example).

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . @ # . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
Facing: right
Move [wasd], [b]reak, [p]lace, [q]uit: 

This requires a small change to the code, allowing for a wall Tile to be added to the TileGrid rather than removed:

if move in ["b", "p"]:
    row_change, col_change = direction_changes[self.direction]
    target_row = self.player.row + row_change
    target_col = self.player.col + col_change
    
    if not (
        0 <= target_row < self.n_rows and 0 <= target_col < self.n_cols
    ):
        return True

    target_tile = self.tiles[target_row][target_col]
    
    if move == "b":
        if target_tile.symbol == self.tileset["wall"]:
            self.tiles[target_row][target_col] = Tile(
                self.tileset["floor"], True
            )
    
    if move == "p":
        if target_tile.symbol == self.tileset["floor"]:
            self.tiles[target_row][target_col] = Tile(
                self.tileset["wall"], False
            )
    
    return True

Jerna, before the dawn

At the moment, destruction and creation are infinite (within the confines of the tilegrid). You can break and build as many wall blocks as you like. Such omnipotence.

In future I want to add this to an inventory system. Break one wall? Now you can make one wall. No more, no less.

Perfectly balanced.

tl;dr

tyle, my Python-CLI roguelike-like, now has ‘fog of war’.

Grid and bare it

You may remember my tyle concept: the beginnings of an in-terminal tile-based roguelike to help me improve my Python CLI skills.

You could install the development version like uv tool install git+https://github.com/matt-dray/tyle.git and initiate by typing tyle in a terminal.

Before now, you’d get something like this:

. . . # # . # . . . . . . . # . . . . . 
. . . . . . . . . . . . . # . . . . . . 
# . . . . . . . . . . . . # . . . . . . 
. . # # . # . . . . . . . . . . . . . . 
. . . . . . . . . . @ . . . . . . . . . 
. . . . . . . . . . # . . # . . . . . . 
. . . . . . . . . # # # . . . # . . . # 
. . . . . . # . . . . . . # . . . . . # 
. # . . # . . . . . . . . . . . . . . . 
Move (WASD+Enter): 

There’s a player (@), floor tiles (.), and randomly-placed non-traversable wall tiles (#). You move the player by typing at the prompt.

It’ll be in colour if your terminal supports ANSI escape codes.

The big reveal

Obviously tyle could improve in many ways. For example, the development of enemies and pathfinding, procedural dungeons, or an inventory system.

A quick win is ‘fog of war’¹.

This phrase refers to uncertainty when drawing up battle plans, but is also a mechanic in many videogames, including roguelikes.

A classic example is in the Civilization series of games. When you start, you cannot see the content of tiles you haven’t visited. The tiles are literally shrouded in fog. That keeps things interesting: will the next tile contain a barbarian hoarde or a potential city-founding location?

Fog lights

We can introduce fog into tyle with little effort.

For lore reasons, imagine the player character is carrying a lamp that illuminates a certain number of tiles in any direction².

How can we achieve this practically?

You may remember that tyle has a TileGrid class. It has a draw() method to generate and print the current state of the tile map.

Previously, we drew the underlying terrain in the map by default, which is composed of the floor (symbol .) and wall (#) symbols. The only exception was to draw the player in the location given by the Player-class row and column properties.

We can intercept this logic to draw fog-of-war symbols by default, unless within a certain tile-range of the player, in which case we draw the terrain.

For maximum portability—and as a hat-tip to the original roguelikes—we’ve been using ASCII symbols as ‘graphics’. We may as well continue for the fog.

I couldn’t think of anything cleverer than simply putting a ?, geddit. Also it’s coloured grey becuase that seems right.

Sound the foghorn

And so the relevant for-loop in the TileGrid class takes this shape:

for row in range(self.n_rows):
    row_symbols = []
    for col in range(self.n_cols):
        if self.player.row == row and self.player.col == col:
            symbol = self.player.symbol
        elif max(
            abs(self.player.row - row), abs(self.player.col - col)
        ) in range(1, self.fog):
            symbol = self.tiles[row][col].symbol
        else:
            symbol = "?"

So, for each row and column, print the symbol for the:

• player (@) if matching Player-class properties row and column
• terrain tile (. or #) if within fog number of tiles from the player
• fog (?) if no other conditions are met (i.e. all the remaining tiles)

In main() I’ve set fog = args.fog with default=2, so we’ll see fog beyond two tiles of the player. You can adjust the vision range in the CLI with the --fog (-f) option, like tyle -f 3.

The default gives us something like:

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . # . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . @ . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? . . . # . ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
Move (WASD+Enter): 

And moving left two steps gives us:

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? # . . . # ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? . . @ . . ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? # . . . . ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? . . . . . ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 
Move (WASD+Enter): 

Ooh, mysterious.

Mist opportunity?

Your ability to see n tiles around the player-character is pretty rudimentary. It implies that you, the player, have an omniscient top-down view of the playing area³… which you do, but that’s not very immersive⁴.

More advanced approaches might include a ‘cone of vision’. The player can only see what’s in their line of sight. In other words, they can’t see through walls.

Woah, woah. We’re not coding a full game engine from scratch.

Or are we, haha?

tl;dr

The {weva} R package contains a titchy command-line interface (CLI) to present an opinionated micro-weather report.

Building some {Rapp}ort

I’m spending more time in the terminal.

So I’ve been making little CLI concepts:

• jot for recording notes
• pet for a persistent cyberpet
• tyle for a roguelike-like

These are all written in Python, which seems a more natural choice for this purpose than R¹.

But I was pleased to see a recent blog post about a new release of {Rapp}, an R package to help create CLIs.

So obviously I needed to try it out.

CLImate

But a CLI for what?

My colleagues and I have enjoyed twee weather CLIs of late, like weathr and wttr.in.

So, because I have no imagination: introducing the concept {weva} (‘wevvah’²) R package.

It does way less than those other examples and doesn’t have fun ASCII graphics. It’s just a simple toy project to see how {Rapp} works, with no guarantees. Is that enough disclaimers?

Along with {Rapp}, this was made possible by the:

• free APIs Open-Meteo and postcodes.io³, which do not require a login
• the tidyverse packages {httr2} and {lubridate}

pak::pak("matt-dray/weva")

weva::install_cli()

weva tr197aa

now 10.9°C ☁️ | +1h 11.3°C ☁️ 

weva kw14yr

now 6.1°C ☁️ | +1h 6.3°C 🌧️🪶 

weva tr197aa -h 24

now 10.9°C ☁️ | +24h 7.7°C 🌧️🪶 

weva tr197aa -h 24 -e

now 10.9°C ☁️ | +24h 7.7°C 🌧️🪶 | today 9.3°C to 12°C 

weva tr197aa -h 24 -e -d

2026-03-01 10:00 10.9°C 🌧️🪶 | 2026-03-02 10:00 7.7°C 🌧️🪶 | 2026-03-01 9.3°C to 12°C 

Inside the crystal ball

What’s actually happening in the code?

{weva} is just a normal R package with some exported functions to get_latlon(), get_weather() and write_report().

But there’s one difference: a script under exec/ that contains R code that {Rapp} will reinterpret (magically?) into a CLI.

At time of writing it looks like this:

#!/usr/bin/env Rapp
#| name: weva
#| description: A micro weather report with 'Open-Meteo' and 'postcodes.io' APIs

#| description: A UK postcode
postcode <- NULL

#| description: Hours from now for the 'later' segment (up to three days)
#| short: h
hours <- 1L

#| description: Show API and calculated datetimes in 'now' and 'later' segments?
#| short: d
datetimes <- FALSE

#| description: Show a segment for today's min and max temperatures?
#| short: e
extremes <- FALSE

get_latlon(postcode) |>
  get_weather() |>
  write_report(
    hours_to_forecast = hours,
    show_datetimes = datetimes,
    show_extremes = extremes
  ) |>
  cat()

Note in this file:

• the shebang (#!)⁸, which gives the path to where {Rapp} is installed
• the hashpipes (#|) for documenting the CLI and its options
• that everything else is normal R code

{Rapp} interprets postcode <- NULL as a required positional argument for weva. You can just type the postcode without a flag.

Conversely, the remaining options must be named, though short names can be used to save typing. --hours (-h) is interpreted as an integer with a default of 1 --datetimes and --extremes (-d, -e) are off (FALSE) by default, but the user can just use the flag without an argument to turn it on.

What’s also nice is that {Rapp} gives us --help (and --help-yaml) for free, based on our variable documentation.

weva --help

Usage: weva [OPTIONS] <POSTCODE>

A micro weather report with 'Open-Meteo' and 'postcodes.io' APIs

Options:
  -h, --hours <HOURS>             Hours from now for the 'later' segment (up to
                                  three days)
                                  [default: 1] [type: integer]
  -d, --datetimes / --no-datetimes  Show API and calculated datetimes in 'now'
                                  and 'later' segments?
                                  [default: false]
                                  Enable with `--datetimes`.
  -e, --extremes / --no-extremes  Show a segment for today's min and max
                                  temperatures?
                                  [default: false]
                                  Enable with `--extremes`.

Arguments:
  <POSTCODE>  A UK postcode

In short, {Rapp} lets you write ‘normal’ looking R code that gets interpreted into a CLI with various types of options.

That’s quite a neat, low-effort way to create a CLI.

{Rapp}ing up

{weva} is [repeated disclaimers]. It would be easy to get carried away and build something even more complex. I’ve achieved the content and learning I wanted, so I stop here.

In fact, I already used this tool yesterday before a trip⁹. I discovered the day was going to be overcast with some showers. Who could have guessed?

But on more variable days, I’m reminded of Fran’s observation when faced with differing forecasts:

I had better go outside and see who’s right

Very wise.

tl;dr

The {hext} R package helps you make text-based hex logos.

A simple mind

Call me a normie, but I am an R-hex-logo enjoyer.

I took a step further last year to create my own (limited) hex-making package, {gex}, which I’ve written about before¹.

The goal of {gex} was to keep things simple: minimal dependencies, only grid graphics².

But I was too short-sighted, too small-brained. I went simple, but not simple enough.

Do the simple things well

Yihui recently said ‘bye, hex stickers’.

In his post he discussed an entirely text-based hex logo for {litedown}. Charlie Gao’s {secretbase}³ has also joined the text revolution.

The spirit of these packages is minimalism. Their logos match this aesthetic.

Simplicity is a probably a good goal in general.

So, naturally, I have overengineered a simple thing to make it simple for you to not think about the complication behind such a simple thing.

Next: text hext

{hext} lets you write text-based logos.

You could install like:

pak::pak("matt-dray/hext")  # GitHub-only

There is only one function: hext(). Very simple, very demure.

Hex outputs have four lines⁴. You can add text and specify alignment for each of these.

hext::hext(
  "keep", "it", "simple,", "silly",
  "left", "centre", "right", "left"
)

  ________
 /keep    \
/    it    \
\   simple,/
 \silly___/

hext() handles character padding and line-length limits on your behalf. It tries its best with Unicode (like emoji)⁵, but rendering is hard⁶.

That’s it, really.

Hexagone

Think less, say less.

tl;dr

I’m writing tyle to help in my quest to slay Python.

Very early access

I’ve started ‘tyle’, a concept Python CLI that contains the foundations for a little in-terminal tile- and turn-based game.

The rudimentary tool is available to install from GitHub (v0.1.0 at time of writing). I like uv for this job¹:

uv tool install git+https://github.com/matt-dray/tyle.git

Then you can start a ‘game’ (heavy emphasis on those quote marks) from your terminal by typing:

tyle

.......#..
..........
.##..#....
....#....#
......#...
.....@....
..#.......
........#.
..........
....#.....
Move (WASD+Enter): 

The gameboard is just a tile grid printed to the terminal. You (the @ symbol) can travel around the floor tiles (.), but not through obstacles (randomly-placed #) or off the map.

At the prompt you can type W and Enter to move up, for example. Q and Enter will quit.

Aaand that’s it for now.

Gone rogue

This game style and ASCII-text ‘graphics’ may be familiar as the blueprint for the classic dungeoncrawling videogame Rogue (1980).

Other key features are turn-based interaction, procedurally-generated environments and player permadeath. Later games aped and adapted these features, giving rise to the ‘roguelike’ and ‘roguelite’ genres.

The scope for tyle is far tighter: I promise nothing. So let’s call this a ‘roguelike-like’ for now.

A sidequest

To explain the lore, I’ve been making some twee CLI projects to help me learn Python. First jot for recording little timestamped notes², then pet for a mini cyberpet experience.

tyle is also a Python-backed CLI, but is helping me learn more about object-oriented programming and building my own classes, specifically. It’s nice to organise code into object ‘types’ that contain their own variables (properties) and functions (methods).

As someone with a background in R, I tend to think every nail can be hammered with a function. R supports classes, of course, most recently with the {S7} package³. But the approach feels far more at home in Python with its greater focus on ‘programming’ than ‘doing statistics’⁴.

A class act

First, a high-level overview of what tyle’s three main classes represent:

• Tile represents each square on the grid
• TileGrid represents the whole grid of tiles
• Entity represents the player character

Each of these have properties and methods that allow them to store data and be queried in certain ways:

• Tile objects store their representative symbol (e.g. #) and if they can be traversed
• TileGrid objects store and print the tile grid, while also assessing player movement
• Entity objects store tile coordinates and hit points for the player

A tile-grid object is composed of many tile objects. Some tiles are designated as floor tiles (.) and others as walls (#). Think of the tile-grid as the ‘terrain’ layer of the game.

The player is not part of the terrain layer, but exists independently and carries its own coordinate properties. When printing the tilegrid with a drawing method, the player’s symbol (@) is printed preferentially. There’s logic to prevent the player from moving to non-traversable places (walls or off the map).

class Tile:
    def __init__(self, symbol: str, traversable: bool) -> None:
        self.symbol = symbol
        self.traversable = traversable

tile = Tile(".", True)

tile.symbol

'.'

grid = [
    [Tile("#", True) for _ in range(n_cols)]
    for _ in range(n_rows)
]

[[<__main__.Tile at 0x107a22120>, <__main__.Tile at 0x107a23170>],
 [<__main__.Tile at 0x107a236e0>, <__main__.Tile at 0x107a23020>]]

Hack

But I’ve read about the {r.oguelike} R package on this blog before. Have you run out of ideas?

Uh-oh, I’ve been rumbled.

Listen, agitator: an R-function spaghetti was never the ‘right’ choice. Not least because that particular ‘game’ had to be played in the R console, rather than the terminal directly.

Python is probably more suited to this type of activity. In fact, Python can be used as a full-blown game engine, aided by tools like PyGame. In fact, there are several roguelike-specific packages to help you build roguelikes specifically, like libtcod⁷.

I’m ignoring these because I want to use this little project to help me learn Python skills, not roguelike-making skills, specifically. Classes, yes, but also stuff like type hints, docstrings, writing modules, creating CLIs, etc.

Do it with tyle

As ever, I may stop there⁸. But there are some obvious improvements that could also strengthen my Python skills.

For example, a bunch of stuff from {r.oguelike} could be interesting to translate here, like procedural dungeons, enemy battling and pathfinding, and an inventory.

We should also ‘listen’ for keyboard input with something like pynput. A much more natural approach compared to smashing the Enter key.

Of course, learning new stuff can feel like navigating through a dungeon full of goblins. But to avoid permadeath of coding skills you’ve just got to keep going tile-by-tile, amirite?

tl;dr

jot now has --where, --version, --from and --to options.

Whoops

Me, lying, the last time I posted about jot:

It’s basically feature-complete from my perspective.

Reminder: jot is my simple little Python CLI for recording timestamped notes to a text file.

In fact, now you can:

• combine options
• search between specific dates
• quickly get tool meta-information

And?

Options --search and --list (-s and -l) can now be used in combination.

This was achieved by adding an argument to the search_jottings() function that takes the value given by --list.

So, assuming this little jot file:

jot.txt

[2025-08-28 11:15] ate an apple
[2025-08-27 10:58] ate a kiwi
[2025-08-26 11:09] ate a pineapple
[2025-08-25 10:40] ate an apple and a pear

A casual --search will return anything matching your search term.

jot -s "apple"

[2025-08-28 11:15] ate an apple
[2025-08-26 11:09] ate a pineapple
[2025-08-25 10:40] ate an apple and a pear

But that could overwhelm the console if you have a lot of jottings.

So now you can add the --list flag to limit to the most recent n jottings that match the search term.

jot -s "apple" -l 1

[2025-08-28 11:15] ate an apple

Where? What?

I added helpers --where and --version (-w and -v) as quality-of-life improvements.

--where is useful if you forget the file paths handled by jot, which are:

• the config file, which contains a key-value path to the jot file
• the jot file, which is where the text of the jottings is saved

jot -w

📍 Default path to config file: /Users/mattdray/.jot-config.json
📍 Path to jot file: /Users/mattdray/Documents/jot.txt

The tool has gone through a bunch of changes, so you can check what version you’re running with --version.

jot -v

0.2.11

The version number is also provided now when you run jot --help (-h) to print the help documentation.

Assuming you’re using uv, run uv tool upgrade jot to get the latest version.

When?

I mentioned using a regular expression to filter for jottings between dates. That’s awful¹.

Helpfully, Olivier Iffrig-Petit contributed a couple of new options to handle this.

--from and --to (-f and -t) take values in the form YYYYMMDD to filter from (inclusive) and to (exclusive) given dates. They can be used alone or together, along with --search and --list.

So, to return jottings from 26 August 2025 up to (but not including) 28 August 2025:

jot -f 20250826 -t 20250828

[2025-08-27 10:58] ate a kiwi
[2025-08-26 11:09] ate a pineapple

Isolating time periods like this has helped me find information to write weeknotes and complete my timesheets.

Many thanks Olivier.

Sure?

Along with these features, I’ve added basic tests for the Python functions using pytest. A couple of things that were new to me were:

• the @pytest.mark.parametrize() decorator, which helps set up inputs that can be iterated over in a test
• that capsys captures system outputs, as the name implies, which you can compare to expected values

And naturally my patience was tested trying to get the pytest GitHub Action to run correctly.

Next?

Next thing might be to prepare jot for PyPi. There’s probably two breaking changes to be made before then:

1. Save the config file somewhere more suitable than the user’s home directory.
2. Rename the package because there’s already a macOS tool named ‘jot’, lol².

So, perhaps, finally, maybe, for now:

It’s basically feature-complete from my perspective.

tl;dr

{a11ytables} is dead, long live {aftables}.

Regret?

A while back I presented ‘Panic! In The Toolshed’ about how public-sector data scientists should share code to prevent wheel reinvention¹.

I gave the example of my {a11ytables} R package, which has helped to publish spreadsheets of official statistics that follow best practices.

It got harder to find time to maintain the package. I hemmed-and-hawed about its existence and procrastinated two concept packages to make up for its weaknesses².

But then the weight³ was lifted!

Rehome

The Analysis Function at the Office for National Statistics (ONS) now host and maintain the package. I can’t think of a better home.

Transferring the package GitHub repository was a bit of a dance, passing from the co-analysis org to my personal account and finally the best-practice-and-impact org. I fretted about archiving and forking instead, but a transfer appears not to have caused issues.

As part of this move, the package has been renamed {aftables}. The ‘af’ stands for ‘Analysis Function’ and echoes the related {afcharts} package that helps produce best-practice visualisations.

As a parting gift, I used my {gex} package to make a quick hex logo that echoes the {afcharts} logo:

This renaming hasn’t had a major impact as far as I can tell. The team published a launch blog; I updated colleagues via the cross-government Slack; and GitHub auto-rereoutes from co-analysis/a11ytables to best-practice-and-impact/aftables.

The team has already made updates and submitted successfully to CRAN in these past few months, which I definitely didn’t have the energy to tackle.

So now you can just install.packages("aftables") to try it out. Simply lovely.

Relief

So thank you to the Analysis Function team, particularly Olivia and Zach; to Matt and Tim for their early contributions; and to everyone who has used the package and provided feedback.

Panic? What panic?

tl;dr

I’ve made pet: a (very simple) Python tool to look after a persistent cyberpet on your command line.

Adopt

I made this for learning purposes, but if you did want to try it:

0. Install uv if you somehow haven’t already.
1. From your terminal run uv tool install git+https://github.com/matt-dray/pet.git.
2. Run pet.
3. Take responsibility.

Pet the kitty

Running pet takes control of the terminal and asks you to select an option with ↓, ↑ and Enter:

• 📊 Stats to show your pet’s name (supplied by the user when they first run pet), birth (creation datetime), age (days since birth) and health (out of 10)
• 👀 See to print a little picture of your pet (always the same handsome cat)
• 🍣 Feed to simulate your pet eating and gaining one unit of health
• ❌ Quit to exit the program back to the terminal
• 👋 Release to discard your pet (cry) and delete its data

Here’s what a playthrough looks like:

Lines starting with a question mark require input from the user. Once selected, the options disappear and the chosen one is displayed in blue. When the user can choose from several options, a blue chevron is moved between the options.

Crucially, if you quit and come back later, your pet will be recalled and its stats will have changed given the amount of time that’s passed. Pay attention! Your pet’s health will diminish over time¹.

That’s it.

The soft underbelly

You can see the ‘game loop’ in the cli.py module. Basically:

1. If it doesn’t exist, create a json file of pet stats on the user’s computer, having prompted for the pet’s name.
2. Update the stats given the time elapsed since birth and since your last interaction.
3. Deplete the pet’s health as a function of elapsed time (1 health unit lost per hour).
4. Ask the user to select an action from the menu and act accordingly, ad infinitum.
5. Break the loop on exit, and delete the stats json file if the pet was released.

Not too complicated. Behind this, the Python functions in utils.py are for wrangling and overwriting the stats file, calculating time and health loss, and for initiating the graphics engine (i.e. print(), lol).

Gaining XP

As well as getting more general experience in Python packaging, I learnt more about:

• InquirerPy, which does the heavy lifting on user interaction, like inquirer.select() for presenting keyboard-navigable options²
• user_data_dir() from platformdirs, which can create a platform-independent path to a location on the user’s machine where game data can be stored

As in several recent posts, uv has also been great here for the development loop, including to support use of ruff and ty³ for code quality, like uvx ruff format.

A good egg

This pet tool has been designed for my own learning. There’s loads of missing features, but my goals have been met.

For more of a triple-A⁴ virtual pet experience, you can read earlier blogs about my {tamRgo} package, which does a much better job of this in the R console. It has lots more features, like ‘happy’, ‘hungry’ and ‘dirty’ meters; different pet species; experience points and levelling up; and ‘graphics’ dependent on the pet’s species and level. Ah, and the concept of death.

tl;dr

You can use Python’s rich library to make super minimal presentations at the command line.

Sliding scale

Recently, conference organisers forced a colleague to convert their Quarto presentation to P*werPoint. Unconscionable.

Proprietary software shouldn’t get in the way of good ideas, maaan.

Actually, if your message is good enough¹ then why waste time rendering anything? Why not just print directly to the terminal, lol?

That’s rich

The rich library is for prettifying output and making user interfaces².

There’s nothing to stop you using rich to show faux ‘slides’ at the command line. So, as a thought experiment, I’ve given this a go.

Basic approach:

1. Clear the screen.
2. Accept keyboard input.
3. Draw the next slide.

I’ve prepared a single Python demo script to do exactly this. Dependencies are declared at the top, so you can run it with uv like uv run slides.py³.

Crucially, you’ll have to zoom in to you terminal so the words end up nice and big. I don’t know a simple way to do this automatically (or if it’s even possible).

Then you can use arrow keys to move through the slides and press Q to quit.

slides.py

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "pynput",
#     "rich",
# ]
# ///

from pynput import keyboard
from rich.align import Align
from rich.console import Console
from rich.panel import Panel
import os

console = Console()

def panelise(
    *args,
    sep="\n",
    panel_title,
    panel_subtitle="#ShareholderValue",
    panel_width=console.size.width,
    panel_height=console.size.height - 2,
):
    panel_text = sep.join(args)
    panel_body = Align.center(panel_text, vertical="middle")
    panel = Panel(
        panel_body,
        title=panel_title,
        subtitle=panel_subtitle,
        width=panel_width,
        height=panel_height,
    )
    return panel

slides = [
    panelise(
        " ___ _   _ _ __   ___ _ __ __ _ _   _ ",
        "/ __| | | | '_ \ / _ \ '__/ _` | | | |",
        "\__ \ |_| | | | |  __/ | | (_| | |_| |",
        "|___/\__, |_| |_|\___|_|  \__, |\__, |",
        "      __/ |                __/ | __/ |",
        "     |___/                |___/ |___/ ",
        "                            promote it",
        panel_title="",
        panel_subtitle="",
    ),
    panelise(
        "• Push the envelope",
        "• Double down",
        "• Think outside the box",
        panel_title="Paradigm shift",
    ),
    panelise(
        "• Move the needle",
        "• Circle back",
        "• Take this offline",
        panel_title="Key deliverables",
    ),
    panelise(
        "You must clap",
        panel_title="You're welcome",
    ),
]

index = 0
running = True

def render_slide():
    os.system("clear")

    width = console.size.width
    filled = int((index) / (len(slides) - 1) * width)
    bar = "▬" * filled + " " * (width - filled)
    console.print(bar, style="green")

    console.print(slides[index], style="green")

def on_press(key):
    global index, running

    if hasattr(key, "char") and key.char == "q":
        running = False
        listener.stop()
        return

    if key == keyboard.Key.right:
        index = (index + 1) % len(slides)

    elif key == keyboard.Key.left:
        index = (index - 1) % len(slides)

    render_slide()

listener = keyboard.Listener(on_press=on_press)

render_slide()
listener.start()
listener.join() 

The slides in the demo are spat out like this⁴:

Some may call this content ‘jargon rich’ but they are losers who have simply never grinded as hard as me, bro.

Slidecraft

I’ll step through the code.

First, we initiate a console object: console = Console(). The print() method against this lets us style the output.

Next, I made a panelise() function, which wraps rich’s Panel(). This simplifies ‘slide’ setup with some defaults.

Incidentally, a ‘panel’ is just an area surrounded by a border, which I’ve ‘hacked’ to use as a bordered slide.

Then we create a dict of slides, passing lines of text and the slide title. In my example I created a title slide with some cool ASCII art and then a few slides with simple bullets.

Next are two important functions:

• render_slide(), which clears the console, adds a progress bar at the top (oh yeah, did I mention there’s a progress bar?⁵) and then prints the slide content
• on_press(), which uses the pynput library to accept keypresses (left- and right-arrows to move slides and Q to quit)

Then there are steps to run the presentation itself:

1. Start ‘listening’ to keyboard presses with keyboard.Listener().
2. Render the first slide (index = 0) with render_slide().
3. Move to the next slide with an arrow press (wrapping back to the start).
4. Exit the slides when a q happens (set running = FALSE and stop listening for keypresses).

The slideshow’s over

So, this thing I threw together does what I wanted it to do. Improvements are absolutely possible.

Of course, I haven’t made full use of rich’s rich colour and style control. rich also has a module that interprets Markdown input, which may be preferable to Panel() in some cases.

I know the script works on macOS but I haven’t tested it anywhere else. I suspect there may be better, platform independent approaches.

It’s also true that pressing the arrow keys will advance slides… even if the focus is away from the terminal. Ah well!

Anyway, if you want an actual fully-featured terminal-based tool, you could try something like Maas Lalani’s slides.

Next slide please!

tl;dr

I’ve added a small set of options to jot, my minimal opinionated Python command-line tool that helps me remember stuff.

Forget me jot

You may recall I made a Python CLI tool called jot to help me record work tasks. I go to my terminal and type jot "corrected a typo" and it gets added to a simple text file with a timestamp.

To give it a go, I recommend installing uv and then install from GitHub like uv tool install git+https://github.com/matt-dray/jot.

Opt in

I’ve been using jot for the past couple of weeks and it’s helping me record things I would typically forget about. As a result, I’ve found it easier to unobscure ‘invisible work’ and reflect on what I’ve achieved.

But my list of jottings is getting harder to manage as it gets longer. There’s a couple of things that would make it easier for me: to be able to peek at the past few jottings and to search them for specific terms.

So, I’ve added two options and will demonstrate them against some imaginary data:

[2025-08-30 09:27] granola and yoghurt
[2025-08-29 07:47] pancakes, blueberries and maple syrup
[2025-08-28 08:00] fried egg on sourdough toast
[2025-08-27 08:06] yoghurt and strawberries
[2025-08-26 08:19] strawberry jam on toast
[2025-08-25 08:52] wholemeal toast and poached eggs
[2025-08-24 09:15] muesli and milk
[2025-08-23 09:23] muesli with berries and milk
[2025-08-22 08:13] hash browns and scrambled eggs
[2025-08-21 07:48] granola and yoghurt
[2025-08-20 07:54] cereal and milk

Everything below is correct as of jot v0.2.3, but I may work to improve some features. Feel free to make suggestions too.

$ jot -l 3

[2025-08-30 09:27] granola and yoghurt
[2025-08-29 07:47] pancakes, blueberries and maple syrup
[2025-08-28 08:00] fried egg on sourdough toast

jot -s egg

[2025-08-28 08:00] fried egg on sourdough toast
[2025-08-25 08:52] wholemeal toast and poached eggs
[2025-08-22 08:13] hash browns and scrambled eggs

$ jot -s "2025-08-2([5-9]).*egg"

[2025-08-28 08:00] fried egg on sourdough toast
[2025-08-25 08:52] wholemeal toast and poached eggs

Pain in the argparse?

A new learning for me has been argparse package, which allows your Python function to accept inputs at the command line.

That’s been crucial for this update to jot (v0.2.3). At the start of the main() function I’ve set up some argparse steps.

To initiate the parser:

import argparse

parser = argparse.ArgumentParser(
    prog="jot",
    description="Minimal opinionated Python CLI to jot timestamped thoughts.",
    epilog="Source: https://github.com/matt-dray/jot",
)

Then we can add arguments to the parser. Here’s how we do that for the search argument, for which I’ve written a corresponding search_jottings() Python function:

parser.add_argument(
    "-s",
    "--search",
    nargs="?",
    type=str,
    help="search jottings (regex supported)",
)

After these declarations, we can collect the parsed arguments:

args = parser.parse_args()

Later in the body of the main() function we can use the named elements of args to pass into our Python functions. For our search option, that looks like this:

search_jottings(jot_path, args.search)

As a result of this set up, we also get a nice help file for free with --help or -h, which should be helpful for users:

jot -h

usage: jot [-h] [-l [LIST]] [-s [SEARCH]] [text]

Minimal opinionated Python CLI to jot timestamped thoughts.

positional arguments:
  text                  text to write to file

options:
  -h, --help            show this help message and exit
  -l [LIST], --list [LIST]
                        show last n jottings
  -s [SEARCH], --search [SEARCH]
                        search jottings (regex supported)

Source: https://github.com/matt-dray/jot

Jot on

As I’ve mentioned before, jot was built by me for me. It’s basically feature-complete from my perspective. The plan is to extend it minimally and only as a way to learn more Python. But I welcome suggestions!

tl;dr

I’ve started a minimal opinionated Python command-line tool to help me remember stuff. It’s called jot.

Jot or not

This tool is for me¹, but if you want to install it, I recommend you install uv first. Then run uv tool install git+https://github.com/matt-dray/jot from a terminal to install jot (currently v0.2.1) from GitHub.

Open a terminal and write your first jotting like jot "sharpened my pencils". When prompted, enter a text file path where your jottings will be saved. This path will be stored in a .jot-config.json file in your home folder. Each jot call will prepend your your text file with the jotting and a timestamp.

Keep that terminal window open and write new jottings throughout the day, week, month, year.

That’s it.

Forget me jot

The development of jot is a story in three neurologically-themed parts:

1. Goldfish brain.
2. Robot brain.
3. Human brain.

Human heart

There’s not much of a lesson here, apart from the fact I like tinkering and would prefer to do things that way.

I’ll develop jot a bit more with the aid of ‘traditional’ techniques. The interface will remain minimal, but I’d like to add some really basic options to fetch jottings from the past day/week/month or that match a keyword. Add some ideas if you like.

And actually, I think LLMs do have a place in this story, just not in the development stage. Before team standups I can consult an LLM to summarise the past week from my jottings. Before appraisals I can summarise the past year.

One particular LLM asked if I’d like some Python code to generate a P*werPoint slide to summarise my week. Wow!

Very cool. Judgement day is inevitable.

tl;dr

You can use uv to help turn a Python¹ script into a self-contained executable. Useful for really important stuff, like… discovering the next public holiday from your terminal?

This is my own attempt at something I saw Rodrigo do².

Worth a bunt

The UK government maintains an API catalogue. A very (very) simple API example is the bank-holidays API run by the Government Digital Service (GDS). It’s perhaps most well-known for the associated page on the GOV.UK website.

All the API does is serve a JSON file with upcoming public holidays. I wrote a ramshackle little Python script that grabs the file, works out what the next holiday is, and prints it out.

Crucially, it also prints bunting if, according to the JSON, the occasion calls for it.

Banking crisis

So, here’s the quite-ordinary code for this demonstration³:

bank.py

import httpx
from datetime import date

# Fetch bank holidays

resp = httpx.get("https://www.gov.uk/bank-holidays.json")
events = resp.json()["england-and-wales"]["events"]

for event in events:
    event["date"] = date.fromisoformat(event["date"])

# Find next holiday
today = date.today()
future = [event for event in events if event["date"] >= today]
next = future[0]

# Print message

is_today = next["date"] == today
needs_bunting = next["bunting"]

if is_today:
    when = "today!"
else: 
    when = f"on {next['date'].strftime('%d %B %Y')}"

str_out = f"{next['title']} is {when}"

if needs_bunting:
    str_out = str_out + " ▼▽▼▽▼▽"

print(str_out)

Christmas Day is on 25 December 2025 ▼▽▼▽▼▽

Very simple. Does the job⁴. But if we want to use the script, maybe we’ll have to clone a repo containing the script, change directory, activate the virtual environment and only then run the script. Every time we want to use it.

Wouldn’t it be better if I could just call it quickly from my macOS Terminal when I need it? To just type bank.py and get a quick response?

uv protection

This is where uv can help out⁵. You can install via Homebrew with brew install uv, for example.

You can start by adding a block at the top of your file to declare dependencies. Kind of like bundling a pyproject.toml inside your script⁶. No need to worry about a separate dependencies file, lockfile or virtual environment.

To add your dependencies, use uv add with the --script option in the form:

uv add httpx datetime --script bank.py

Which will add the following section at the top of our bank.py script, including the Python requirement:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "datetime",
#     "httpx",
# ]
# ///

And there you have it: all the information needed to run this file in an isolated manner. You’ll be able to run uv run bank.py from your terminal without any additional files required.

But wait! There’s more. How boring, how painful to have to write the uv run bit. That’s six characters⁷. And you’ll have to provide the full path to the script, yikes.

Instead, you can add a shebang⁸ at the top of the file to make it executable:

#!/usr/bin/env -S uv run

Note the unusual bit on the end… aha! uv again! The -S uv run bit asks the interpreter to let good ol’ uv handle the whole operation.

Finally, you can change the mode (chmod) of the file by adding (+) executable (x) status. Then put the file where you terminal will look if you type the name of the file.

chmod +x bank.py
mv bank.py ~/.local/bin

Then you can merely call bank.py from the terminal to know when the next bank holiday is.

One man’s trash

You can find a GitHub Gist of my code⁹, or:

bank.py

#!/usr/bin/env -S uv run

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "datetime",
#     "httpx",
# ]
# ///

import httpx
from datetime import date

# Fetch bank holidays

resp = httpx.get("https://www.gov.uk/bank-holidays.json")
events = resp.json()["england-and-wales"]["events"]

for event in events:
    event["date"] = date.fromisoformat(event["date"])

# Find next holiday
today = date.today()
future = [event for event in events if event["date"] >= today]
next = future[0]

# Print message

is_today = next["date"] == today
needs_bunting = next["bunting"]

if is_today:
    when = "today!"
else: 
    when = f"on {next['date'].strftime('%d %B %Y')}"

str_out = f"{next['title']} is {when}"

if needs_bunting:
    str_out = str_out + " ▼▽▼▽▼▽"

print(str_out)

Next, more important goal: write something similar to help me know what bin day it is (we alternate fortnightly between refuse and recycling). I saved a neighbour from getting erroneously binfluenced recently, so this is dear to my heart.

tl;dr

The package {hexbase} has been improved and renamed {gex}. It’s no longer ‘dependency free’, but has a goal of being ‘gridverse’ only. Sellout!

Enter the gecko

In my last post I wrote about {hexbase}: a dependency-free hex-logo builder, which was helping me learn the basics of R’s grid-graphics system.

Now the package goal is to stay ‘lightweight’ and import only Prof Murrell and co’s family of small ‘gridverse’ packages (I think I’ve invented this term?).¹

Hence the name change: ‘gex’ is an allusion to grid + hex. I liked ‘grex’ more, but it’s already taken on CRAN. Also, a certain flavour of 90s gamer might appreciate the new name.

A great example of the benefit is for the hex border. In {hexbase}, the ‘border’ was just the gap between a smaller hexagon inside a bigger one. Now, {gex} uses {gridGeometry}‘s polyclipGrob() with op = "minus" to ’cut out’ a smaller from a bigger hexagon to create a polygon that can be applied with add_border().

Cast a gex hex

Building a hex with {gex} differs little from {hexbase}. The steps are:

1. Open a PNG graphics device with open_hex().
2. Add the hexagon with add_hex().
3. Add and arrange as many text and image elements as you like with add_text() and add_image().
4. Choose to overlay a border with add_border() (or not).
5. Close the device and write the file with close_device().

Below is the code used to create the logo for the package itself (how meta), which is shown at the top of this post.²

First, install the package from GitHub.

install.packages("remotes")  # if not yet installed
remotes::install_github("matt-dray/gex")

Image manipulation is at the the user’s discretion before being added to the hex. Here I’ll use {magick} to wrangle a line-drawing of a lizard that I want to use (which is bundled in the package), turning it from black to green. I’ll save it as a new PNG and re-read it.

img_tmp <- tempfile(fileext = ".png")  # temp storage for image
system.file("images", "lizard.png", package = "gex") |> 
  magick::image_read() |>
  magick::image_fill("olivedrab1", fuzz = 100, refcolor = "black") |>
  magick::image_write(img_tmp)  # write
img <- png::readPNG(img_tmp)  # read the edited image

Now I’ll start building the hex. Here I’m using loops to write multiple images and to add the text twice with an offset and different colours for a drop-shadow effect.

# Set up write location and graphics device
temp_path <- tempfile(fileext = ".png")
gex::open_device(temp_path)

# Add same image multiple times in a loop
gex::add_hex(col = "olivedrab4")
for (x in seq(-0.04, 1, 0.2)) {  # add many images in a loop
  for (y in seq(0, 1, 0.16)) {
    gex::add_image(img, x, y, width = 0.3, angle = -30)
  }
}

# Add text with 'drop shadow'
font <- "IBM Plex Serif"  # installed on my system
x <- 0.52; y <- 0.56  # starting positions
styles <- list(  # to loop over
  list(coords = c(x = x + 0.01, y = y - 0.01), col = "olivedrab4"),
  list(coords = c(x = x, y = y), col = "olivedrab1")
)
for (style in styles) {
  gex::add_text(
    string = "gex",
    x = style[["coords"]][["x"]],
    y = style[["coords"]][["y"]],
    size = 60,
    col = style[["col"]],
    family = font,
    face = "italic"
  )
}

# Add border and write file
gex::add_border(col = "olivedrab1")
gex::close_device()

As mentioned previously, you build the hex by opening a device and adding elements to it, before closing it to save the file. That may make some people uncomfortable since there’s no ‘object’ as such; you can’t pipe between functions in {gex}. But this comes as no surprise to base and grid-graphics enjoyers, which is kind of the target market. There are dozens of us!

Having said this, I did enjoy Kieran’s recent sermon on this style of interaction:

We have to remember to turn the device off once we’re done with it, like it’s 1997. If you forget, you won’t notice for a while but eventually it’s like your Dad is gonna yell at you because you forgot to turn the lights off downstairs before you went to bed or you left the fridge door open after you went to get a drink of milk or you opened the window while the air conditioning is running in the house what the hell kind of child have I raised.

I’m (probably) not your dad and you (probably) weren’t raised in a barn; I trust you to close_device() when using {gex}. Also, the package is partly named after a videogame from pre-1997, so it’d be anachronistic to do it any other way, amirite?

Going on grid

Since {gex} uses the grid graphics system, other ‘gridverse’ packages can be used to help make your hex. Two others are {gridBase} to put a base R plot in a viewport and {gridGraphics} to convert that plot to a grob. Handily, Guangchuang Yu (of {hexSticker} fame!) wrapped this up in ggplotify::base2grob(), which does what it says on the tin.

Here’s a plot of multicoloured points applied to a hex. Note all the {grid} calls, which are the type of thing that {gex} hides in its functions so you don’t have to think about it (more on that later in the post).

# Start with {gex}
temp_path <- tempfile(fileext = ".png")
gex::open_device(temp_path)
gex::add_hex()

# Add a base plot without {gex}
grid::pushViewport(grid::viewport())
base_plot <- ggplotify::base2grob(
  \() {
    par(mar = rep(0, 4))  # no plot margin
    n <- 1000
    plot(
      runif(n), runif(n),  # 'random' points
      xaxs = "i", yaxs = "i",  # 'edge-to-edge' plot
      axes = FALSE, ann = FALSE,  # no chart stuff
      pch = 16, col = palette.colors(n, , , TRUE)  # style points
    )
  }
)
grid::grid.draw(base_plot)  # it's a grob now, we can draw it
grid::popViewport()

# Finish up with {gex}
gex::close_device()

Other grid-adjacent packages could be used as well. Trevor has put together {gridpattern} to allow for pattern and gradient fills. For example, you could call grid.pattern_gradient() to add a splendid background to your hex.

temp_path <- tempfile(fileext = ".png")
gex::open_device(temp_path)
gex::add_hex()
gridpattern::grid.pattern_gradient()
gex::close_device()

Lovely.

The sticky back-end

In case you’re wondering what’s going on under the hood, here’s a simplified description. This is more for the nerds. Which is what you are if you’ve read this far.

Further gexplorations?

As ever, I’m having a nice time. Also as ever, I may choose to continue this or stop working on it entirely. The most important thing is that {gex} will help me towards the utopia of Hex-Driven Development (HDD), the one true method of developing R packages by starting with the sticker.³

tl;dr

I’ve made {hexbase}, a simple package to create hex stickers in R. The twist: it relies only on base R.

Stick around

Hex stickers are obviously popular in the R community and beyond for advertising your package or other projects¹. So much so that there are packages to organise your stickers.

There’s some existing tools to help you make these:

• {hexSticker} by Guangchuang Yu
• {bunny} by Dmytro Perepolkin, used in conjunction with {magick}
• the hexmake Shiny app² by Colin Fay

Surprise, I’ve made another one: {hexbase}. Why? I wanted to learn about low-level plotting with {grid}, one of R’s built-in packages³. The constraint of using only {grid} in a simple, lightweight package seemed a good test (and a good wheeze).

It’s not perfect, but it does what I need and I learnt a lot.

Do the griddy

I reckon most R users make plots with {ggplot2} otherwise R’s native plot()ting system. I’ll bet {grid}⁴ is used less often. It’s lower-level and you have to build everything up yourself, but it is extremely flexible.

To put it extremely simply, {grid} mostly works through a system of nested ‘viewports’ that you push and pop to add and arrange various graphics objects (grobs⁵) onto a graphics device.

This post isn’t a how-to for {grid} because there’s too much to cover, though I might write a separate post to explain how {hexbase} uses {grid}. I found Prof Paul Murrell’s writings really helpful, which is no surprise as Paul is {grid}’s author. See also Roger’s chapter for an intro.

However, I did learn a few things I wanted to note to myself:

• the grDevices::png() function has a handy bg argument that you can set to "transparent"
• you can clip to a grob, which means you could clip out any text or image that falls outside the hexagon boundary
• you can rotate a viewport but the x and y coordinates will be relative to the angle, so you need to put it inside another viewport that’s relative to the sticker’s coordinates
• the hexagon is not as wide as it is tall, so the x-axis on the default ‘normalised parent coordinate’ system (where the axes are 0 to 1) has to be narrowed by setting the viewport’s xscale to hexagon limits, while the hexagon grob must have default.units = "native" so it’s placed relative to that xscale
• you can make the border by stacking a smaller hexagin on a bigger one, ensuring that the maximum extent of the sticker will fit inside a unit-1 square

Cast a hex

If you want to give it a go, you can install {hexbase} from GitHub like:

install.packages("remotes")  # if not yet installed
remotes::install_github("matt-dray/hexbase")

At time of writing, the package is at version 0.1.0. You can install that specific version by adding @v0.1.0 to the end of the string in install_github().

As mentioned, the package only imports {grid} and {grDevices} from base R. Otherwise it’s BYOIAF (‘bring your own images and fonts’) by importing with packages like {png} and by installing your fonts locally. Is that cheating? Nah, the Imports section in the DESCRIPTION file is clean as far as I’m concerned!

You can then build a sticker additively with a series of {hexbase} function calls:

1. open_device() to set up a PNG graphics device with the dimensions of the Stickers Standard.
2. add_hex() to add the hexagon and border.
3. add_image() to place an image (run multiple times for more images).
4. add_text() to place and style text (run multiple times for more text).
5. close_device() to close the PNG graphics device and save to file.

You can set various text and image properties like position, size, colour and angle. Note that the coordinates are relative to a unit square⁶ with axes of 0 to 1, a lower-left origin at [0, 0] and a centre at [0.5, 0.5]. Text and images will be clipped if they exceed the boundary of the hexagon. Check the help files for all the explanation.

Below is an extremely basic example to demonstrate a number of features. Note how you call each function independently (i.e. no pipes), much like writing base plots with successive calls to plot(), points(), text(), etc.

# Somewhere to save it
temp_path <- tempfile(fileext = ".png")

# 'Bring your own image', e.g. with {png}
image_path <- system.file("img", "Rlogo.png", package = "png")
image_png <- png::readPNG(image_path)

# Build up and write the sticker
hexbase::open_device(  # open with sticker-standard dimensions
  file_path = temp_path
)
hexbase::add_hex(
  border_width = 0.06,
  border_col = "hotpink3",
  bg_col = "bisque"
)
hexbase::add_image(
  image_object = image_png,
  image_y = 0.6,  # y = 0.5 is centre
  image_angle = 20,
  image_width = 0.5  # i.e. half of the npc coord system
)
hexbase::add_text(
  text_string = "example",
  text_x = 0.495,
  text_y = 0.35,
  text_col = "#000000",  # named colour or hexadecimal
  text_family = "Comic Sans MS",  # must be installed locally
  text_face = "bold"  # or 'plain', 'italic', 'bold.italic'
)
hexbase::add_text(  # add multiple text/images (in a loop?)
  text_string = "example",
  text_x = 0.505,
  text_y = 0.34,
  text_col = "red",
  text_family = "Comic Sans MS",
  text_face = "bold"
)
hexbase::add_text(
  text_string = "visit rostrum.blog ftw",
  text_x = 0.73, 
  text_y = 0.18,
  text_angle = 30,  # rotate to match lower-right edge
  text_size = 5,  # point size
  text_col = "blue", 
  text_family = "Papyrus"
)
hexbase::close_device()  # close viewports, write file

You can then open the image for inspection. A quick way to do this from within R would be like system(paste("open", temp_path)). Note that you can’t rely on plot-window previews (they lie) when you’re developing your sticker. You must inspect the generated PNG file instead.

The (stunning) hex produced by this code can be found at the top of this post. Well done for being able to read this far after you burnt your eyes by looking at it.

Don’t get too hexcited

I might play around with this a bit more if I have time and if I want to delve deeper into {grid}. The {hexbase} package seems to work for my use-case, but it can undoubtedly be improved. Let me know if there’s anything you can unstick. I’d be hexstatic, etc.

tl;dr

I made a quick Shiny app that generates randomised characters for your next roguelike game, made with parts designed by Kenney.

Standing on the shoulders of Kenney

Kenney makes free (CC0) assets for videogames, like the 16×16-pixel sprites I used in a previous post, where you could move a little character move around a procedural forest glade while being chased by a mouse.

Kenney also has a roguelike characters pack where you can create your own characters by mixing and matching bodies, clothes and weapons. I’ve had a stab at making a toy roguelike in R before, but the ‘art’ and interface were purely composed of text.

With a long-term goal of creating a ‘real’ roguelike game (maybe in R?), I made a small app to combine sprite parts randomly to create new characters. It’s a pretty simple implementation for now, but I’m recording its current state in case I never come back to it.

An ‘applike’

The app is made with Shiny, deployed for the browser with {shinylive} and served with GitHub Pages. The source for the app is on GitHub. I’ve embedded it below, but you can also visit it in a standalone window. It might take a moment to load.

Hit the reroll button to randomise the sprite parts. You can also download as PNG at 16×16 and 1024×1024 pixels or as an R-specific RDS file containing a nativeRaster representation of the sprite.

Going rogue

The basic approach was to:

1. ‘Cut out’ and save each individual sprite part from a single ‘spritesheet’.
2. Select sprite parts at random given some weighting (bodies are always selected, but weapons aren’t).
3. Store the part names in a reactiveValues() object so they can be called by the draw method (to display the sprite onscreen) and via the download options.
4. Use image_mosaic() from the {magick package} to print sprite parts on top of each other and store this as a nativeRaster object.
5. Read the nativeRaster and use {grid} functions to draw it.

Why not just draw the image_mosaic() object? Two reasons: I specifically want to download the nativeRaster version of the sprite (for later use in R) and because nativeRaster can then be used to produce an image at any size. The nativeRaster object is just a matrix of colour information, where each cell is a pixel of the image. That means you can re-plot it any size you want.

Of course, I could use {nara} by Mike (coolbutuseless) to ‘blit’ sprite parts to a single object, but I had some trouble using the package in a {shinylive} context as its not on CRAN and the GitHub repo doesn’t have any releases with the necessary WebAssembly binaries (yet?).

Expanding the inventory

As ever, there were some learning points, like how:

• I used ignoreNULL = FALSE in shiny::bindEvent() on the step that chooses sprite parts, so that a sprite is created on startup without the need for the user to click the reroll button
• there’s a {shinylive} deployment GitHub Action that can save the step of having to shinylive::export() your app whenever you make changes
• the Chrome browser appears to have a problem downloading the files when the buttons are clicked, so there is a workaround at time of writing that’s used in one of the examples on the {shinylive} website

Even something this simple can be a learning experience.

Permadeath

Obviously this app is more of a proof-of-concept (as ever on this blog). It’s not particularly special or all that useful outside of my needs.

Next steps might involve letting the user select parts manually, styling and theming the app and giving the sprites a transparent background.

You can add a pull request to the GitHub repo if this interests you. But beware, adventurer, I can’t promise my code is less labyrinthine than a classic Rogue dungeon.

tl;dr

As a test, I uploaded an R Shiny app to itch.io, which is a platform for sharing indie games. It worked.

Scratching an itch.io

Where can you host your Shiny app for free? Typical options are services like shinyapps.io or Connect Cloud by Posit.

I have another idea: itch.io is a web-based platform known for hosting indie videogames, assets and other miscellaneous game-adjacent tools¹. Developers can upload file bundles for users to download, or they can serve their HTML apps directly on the site.

Since R is a game engine², why aren’t R users uploading their apps to itch.io?

Well, part of the problem is that you didn’t know this was possible. And also because it’s only recently that you can use {shinylive} to convert your app to be served entirely in the browser with no need for a server³.

shinylive::export() generates a folder containing your app and all the assets needed for deployment. You just need to zip it up and upload it to itch.io.

Which is exactly what I did with a toy pixel editor that I made and wrote about recently.

This requires an itch.io account. When you upload the app you fill in a short pro forma, making sure to set the ‘kind of project’ to HTML and to tick a checkbox to say ‘this game will be played in the browser’. For my example, I also set the ‘classification’ to ‘tools’.

I can’t really think of a catch, but there are limitations around size and complexity: the upload must be under 1 GB and I think there’s a limit of 1000 files (this tripped me up when I tried once before).

Scratch my back

I did this for the lols, of course, but I do think itch.io is a viable option for certain types of app. It’s a platform for people to share their creativity and no-one cares what language was used if the outcome is fun or useful.

And if that wasn’t enough, you can also use itch.io as a payment platform. Users can leave you a little tip for your efforts.

So, what’s stopping you from becoming the first professional indie R game developer?

tl;dr

Use {sortable} in a {shiny} app to build card games, maybe? I mocked up a demo and made it available on the web with {shinylive}.

Balatro

LocalThunk¹—the anonymous creator of Balatro, the hit poker-inspired roguelike videogame²—revealed recently that 11,000 years of gameplay have been sunk into the game.

The average productivity of the universe has continued to drop now that the game is available on mobile. I am one of the suckers that made the purchase.

As a result, I wondered how viable a card game in R might be. Not just a simple blackjack simulator in the console, but a drag-and-droppable interface in the browser.

It must be possible, since R is a game engine (fight me).

Badlatro

And so I began experimenting.

I wanted to use {shiny} and existing R packages and to avoid writing much JavaScript and CSS. After all, it’s hard to fit in this frivolity after I’ve finished grinding all day at work and then grinding all night on Balatro.

Luckily, the {sortable} package does most of the hard work. The package from Andrie, Barrett and Kent wraps the SortableJS library and lets you drag list elements around, including into other lists.

Typically, you would use {sortable} to drag little boxes of text. The order can then be read to record preference or perhaps as part of a quiz³. But now I’ve hijacked it to show little images of cards that you can drag between a ‘pool’ (randomly drawn cards) and a ‘hand’ (cards selected by the user).

App

You can check out the source on GitHub and find the app deployed online, thanks to {shinylive} and GitHub Pages. I’ve embedded it below as well⁴ (it’ll take a moment to load). I recommend using this on desktop for now, rather than mobile.

Features

So far it doesn’t do much, but it does enough to prove the concept. Here’s some notes on a few of the technicals.

Improvements

There’s many features that would improve the demo app. Below are some examples: one seems like it’s not possible, one won’t add that much to what I’ve learnt so far, one is obvious and one is just… bad programming.

A gamble

Obviously this isn’t yet a ‘game’. There’s a few ways this could go:

• remake Balatro in R (absolutely no chance)
• make a small simulator of something like video poker (too basic?)
• create a new, simple game to chase high scores with combos of poker hands, discards and chip ‘bets’, perhaps incorporating some Balatro-inspired joker-activated bonuses or wild cards like in Dungeons and Degenerate Gamblers (might actually be fun)
• do nothing (appealing option)

Feel free to chip (HA HA HA) in your ideas.

tl;dr

I made a simple toy pixel-editor for the browser, which helped me learn about reacting to user clicks and implementing undo/redo in {shiny}.

Just browsing

My {pixeltrix} package is a local pixel editor you can run from the R console¹. It’s intentionally simple. You start a graphics device and click the squares (‘pixels’), cycling through your provided colour palette. You’re returned a little pixeltrix-class matrix as a memento, which you can re-edit later.

It might be nice to have a browser-based version, but I’ve never really had the time and figured it would be too fiddly. Well guess what, I had some time and it wasn’t that fiddly.

I’ve been learning a bit more {shiny} of late. This mini project was a good way to learn a few things that might come in handy later. In particular, how to:

1. Read a clicked point on a plot and react to it.
2. Implement a basic undo/redo feature.

This is a reminder to myself of how to do these things.

App

The app is available via {shinylive} deployed via GitHub Pages and the source is on GitHub (v0.3.0 at time of writing).

There’s (intentionally) only a few features. You can:

• click a pixel to toggle it on/off
• change the colour, thanks to Dean Attali’s {colourpicker}
• undo/redo (with a very short ‘memory’)
• flood fill
• have an assistant ✨AI✨ draw a picture for you²
• download a matrix representation of your treasured art (pixeltrix-class, for my own needs) as an RDS file
• download a png copy of your treasured art

Wow!

Here’s an embedded version of the app (may take a moment to load):

Tricks

I mentioned there were two things I learnt in particular: handling click-reacts and undo/redo.

shiny::plotOutput(
  outputId = "pixel_grid",  # the plot of the pixel grid
  click = shiny::clickOpts(
    id = "clicked_point",  # to retrieve as input$clicked_point in server
    clip = TRUE  # restrict to plot bounds?
  )
)

pixel_matrices <- shiny::reactiveValues(slot1 = .gen_grid(16, "#E5E5E5"))

shiny::observeEvent(input$clicked_point, {  # trigger on click
  
  matrix_updated <- .gen_updated_pixel_matrix(  # update current drawing
    shiny::isolate(pixel_matrices[["slot1"]]),  # the current drawing
    pixel_coords(),  # location of clicked point to update
    input$selected_colour  # current user-selected colour
  )
  
  pixel_matrices[["slot2"]] <- pixel_matrices[["slot1"]]  # current is now old
  pixel_matrices[["slot1"]] <- matrix_updated  # new is now current
  
})

button_icon <- shiny::reactiveVal("rotate-left")  # starting condition

shiny::observeEvent(input$button_undo, {  # trigger on click
    
    # Switch 'memory' slots
    slot1 <- pixel_matrices[["slot1"]]
    slot2 <- pixel_matrices[["slot2"]]
    pixel_matrices[["slot2"]] <- slot1
    pixel_matrices[["slot1"]] <- slot2
    
    # Invert undo/redo icon
    
    current_icon <- undo_button_icon()
    if (current_icon == "rotate-left") undo_button_icon("rotate-right")
    if (current_icon == "rotate-right") undo_button_icon("rotate-left")
    
    shiny::updateActionButton(
      inputId = "button_undo",
      icon = shiny::icon(button_icon())
    )
    
  })

Fiddly is money

There’s a number of features I could implement, like arbitrary pixel-grid sizes, uploading a matrix to continue editing it, or maybe even multi-select with click-and-drag (is this even possible?).

If only I could perceive that I have more time and that the fiddlyometer gauge was lower. Yes, this is current me goading future me.

Until then, drop bug reports and how to fix them in the issues.

Also use the app to draw a classic videogame action scene and send it to me, obviously (see inspiration at top of post).