Skip to main content

Template functions

Templates are Jinja, so they come with Jinja's own filters: upper, default, join, round and the rest. comb adds its own, for the jobs a prompt or a source actually has. This guide walks through them by job. The template library lists every one with all its options.

comb eval renders a template on the spot, so you can try each of these as you read.

Where a function can run​

Most functions run anywhere: in a template you read, in -f, in comb eval and in a source's lines. A few are limited, because of what they cost:

functionin a template you readin a source
reading files: read, lup, statyesyes
running a command: execyes, with comb get; off by default in librariesyes
fetching a URL: url, and calling a plugin: pluginnoyes
keeping an answer: cache, watch, ttlyesno: a source keeps its answer already

Anything that runs a command or fetches a URL is slow next to everything else. In a source it runs once and is kept; in a template it runs on every read unless you cache it.

Find and read files​

lup looks for a file going up from where you are, the same way the cascade does, and gives its path. read reads a file, and fromjson, fromtoml, fromyaml and fromini turn its text into values:

$ cd ~/code/shop/web
$ comb eval "{{ lup('package.json') }}"
/home/you/code/shop/package.json
$ comb eval "{{ (lup('package.json') | read | fromjson).version }}"
1.5.0
$ comb eval "{{ lup('package.json') | dirname | basename }}"
shop

A file that isn't there reads as nothing, not an error. stat gives a file's size, kind and modification time without reading it.

Run a command​

exec runs a command and gives what it printed. Give it a string to run through the shell, or a list to run directly with no shell involved:

$ comb eval "{{ exec('uname -s') | trim }}"
Darwin
$ comb eval "{{ exec(['echo', 'hi']) | trim }}"
hi

trim takes off the newline the command printed at the end. A command that fails is an error you'll see; add or 'fallback' after it if failing is normal.

Fetch from the web​

url fetches a URL and gives the response body. It runs only in a source, so it runs once and is kept, and never holds up a prompt. From an HTTP API has a full example with headers and authentication.

Shape text​

$ comb eval "{{ '~/code/shop/web/src' | shorten_path }}"
~/c/s/w/src
$ comb eval "{{ 'feature/login-page' | truncate(10) }}"
feature/l…
$ comb eval "{{ git.branch | pad(8) }}|"
main |

truncate and pad count terminal columns, so wide characters and emoji line up.

Colour and style​

fg and bg set the text and background colour, by name (red, bright_blue), number (0 to 255) or #rrggbb. bold, dim, italic and underline set the style:

$ comb eval "{{ git.branch | fg('cyan') }} {{ 'dirty' | fg('red') | bold }}"
main dirty

The colour depth follows your terminal (COLORTERM, then TERM), and --color never or NO_COLOR turns colour off.

Numbers, sizes and time​

$ comb eval "{{ 3725 | duration }}"
1h2m
$ comb eval "{{ (now() - 11520) | ago }}"
3h12m ago
$ comb eval "{{ now() | strftime('%H:%M') }}"
09:41
$ comb eval "{{ 1288490188 | bytes }} {{ 56789 | compact }}"
1.2G 57k

ramp picks a word, icon or colour by where a number falls, which is handy for a battery or a load average:

$ comb eval "{{ battery.percent | ramp([20, 50], ['low', 'mid', 'high']) }}"
high

Icons and bars​

icon gives a Nerd Fonts glyph by name, and file_icon the glyph for a kind of file. You need a Nerd Font in your terminal to see them:

{{ icon('dev-git') }} {{ git.branch }}
{{ file_icon('package.json') }} {{ pkg.version }}

bar draws a fixed-width bar, for things like a battery or disk usage:

{{ bar(10, {'value': battery.percent / 100, 'colour': 'green'}) }}

When a value is missing​

A missing value is empty, and every comb filter passes empty through as empty, so a template doesn't break when something isn't there. Say what to show instead with or, or with default:

$ comb eval "{{ kubecontext.context or 'no cluster' }}"
no cluster
$ comb eval "{{ missing.thing | default('none set') }}"
none set

Keeping an answer​

cache, watch and ttl keep a template's answer so a command in it doesn't run on every read. Caching a template with cache() explains them.