Skip to main content
Version: v2.1.5-beta

Extensions

Extensions are the heart of Espanso's dynamic matches and can be used to accomplish complex tasks.

Date Extension

The Date Extension can be used to include date and time information in a match. For example, the following match will be expanded into It's 09:30 if triggered at 9:30 am:

  - trigger: ":now"
replace: "It's {{mytime}}"
vars:
- name: mytime
type: date
params:
format: "%H:%M"

The most important aspect to consider is the format parameter, which specifies how the date will be rendered.

To see a list of all the possible formatting options, click here.

Date specifiers

OptionExampleDescription
%Y2001The full proleptic Gregorian year, zero-padded to 4 digits.
%C20The proleptic Gregorian year divided by 100, zero-padded to 2 digits.
%y01The proleptic Gregorian year modulo 100, zero-padded to 2 digits.
%m07Month number (01--12), zero-padded to 2 digits.
%bJulAbbreviated month name. Always 3 letters.
%BJulyFull month name. Also accepts corresponding abbreviation in parsing.
%hJulSame as %b.
%d08Day number (01--31), zero-padded to 2 digits.
%e 8Same as %d but space-padded. Same as %_d.
%aSunAbbreviated weekday name. Always 3 letters.
%ASundayFull weekday name. Also accepts corresponding abbreviation in parsing.
%w0Sunday = 0, Monday = 1, ..., Saturday = 6.
%u7Monday = 1, Tuesday = 2, ..., Sunday = 7. (ISO 8601)
%U28Week number starting with Sunday (00--53), zero-padded to 2 digits.
%W27Same as %U, but week 1 starts with the first Monday in that year instead.
%G2001Same as %Y but uses the year number in ISO 8601 week date.
%g01Same as %y but uses the year number in ISO 8601 week date.
%V27Same as %U but uses the week number in ISO 8601 week date (01--53).
%j189Day of the year (001--366), zero-padded to 3 digits.
%D07/08/01Month-day-year format. Same as %m/%d/%y.
%x07/08/01Locale's date representation (e.g., 12/31/99).
%F2001-07-08Year-month-day format (ISO 8601). Same as %Y-%m-%d.
%v 8-Jul-2001Day-month-year format. Same as %e-%b-%Y.

Time specifiers

OptionExampleDescription
%H00Hour number (00--23), zero-padded to 2 digits.
%k 0Same as %H but space-padded. Same as %_H.
%I12Hour number in 12-hour clocks (01--12), zero-padded to 2 digits.
%l12Same as %I but space-padded. Same as %_I.
%Pamam or pm in 12-hour clocks.
%pAMAM or PM in 12-hour clocks.
%M34Minute number (00--59), zero-padded to 2 digits.
%S60Second number (00--60), zero-padded to 2 digits.
%f026490000The fractional seconds (in nanoseconds) since last whole second.
%.f.026490Similar to .%f but left-aligned. These all consume the leading dot.
%.3f.026Similar to .%f but left-aligned but fixed to a length of 3.
%.6f.026490Similar to .%f but left-aligned but fixed to a length of 6.
%.9f.026490000Similar to .%f but left-aligned but fixed to a length of 9.
%3f026Similar to %.3f but without the leading dot.
%6f026490Similar to %.6f but without the leading dot.
%9f026490000Similar to %.9f but without the leading dot.
%R00:34Hour-minute format. Same as %H:%M.
%T00:34:60Hour-minute-second format. Same as %H:%M:%S.
%X00:34:60Locale's time representation (e.g., 23:13:48).
%r12:34:60 AMHour-minute-second format in 12-hour clocks. Same as %I:%M:%S %p.

Time zone specifiers

OptionExampleDescription
%ZACSTLocal time zone name. Skips all non-whitespace characters during parsing.
%z+0930Offset from the local time to UTC (with UTC being +0000).
%:z+09:30Same as %z but with a colon.
%#z+09Parsing only: Same as %z but allows minutes to be missing or present.

Date & Time specifiers

OptionExampleDescription
%cSun Jul 8 00:34:60 2001Locale's date and time (e.g., Thu Mar 3 23:05:25 2005).
%+2001-07-08T00:34:60.026490+09:30ISO 8601 / RFC 3339 date & time format.
%s994518299UNIX timestamp, the number of seconds since 1970-01-01 00:00 UTC.

Special specifiers

OptionExampleDescription
%tLiteral tab (\t).
%nLiteral newline (\n).
%%Literal percent sign.

It is possible to override the default padding behavior of numeric specifiers %?. This is not allowed for other specifiers and will result in the BAD_FORMAT error.

ModifierDescription
%-?Suppresses any padding including spaces and zeroes. (e.g. %j = 012, %-j = 12)
%_?Uses spaces as a padding. (e.g. %j = 012, %_j = 12)
%0?Uses zeroes as a padding. (e.g. %e = 9, %0e = 09)

The list was taken from the official chrono documentation, please follow the link for more information.

Future and past dates

In the previous section, we discussed how to add the current date to your matches, but you might also want to add future and past dates.

Luckily, Espanso supports the concept of offset, that is, the number of seconds to be added to the current time when expanding a match. An example will surely make it easier to understand:

Let's say we need tomorrow's date as part of a snippet. We could do that with:

  - trigger: ":tomorrow"
replace: "{{mytime}}"
vars:
- name: mytime
type: date
params:
format: "%x"
offset: 86400

If you now type :tomorrow, you should see tomorrow's date appear (something like 03/20/2022)!

What made this possible was the offset parameter set to 86400, which equals to 24 hours in the future, expressed in seconds (60 seconds x 60 minutes x 24 hours = 86400 seconds).

If you need past dates, you can specify a negative offset as well. Such as:

  - trigger: ":yesterday"
replace: "{{mytime}}"
vars:
- name: mytime
type: date
params:
format: "%x"
offset: -86400

Advanced: Localized dates

info

Localized dates have been introduced in version v2.1.4-beta, so make sure to have an up-to-date release.

Espanso automatically localize dates based on your system's country and language, but advanced users might want to force a particular locale.

For this reason, the Date extension supports the locale option to override your system preferences. For example, the following snippet always expand to the current date in US format:

matches:
- trigger: ":today"
replace: "{{mytime}}"
vars:
- name: mytime
type: date
params:
format: "%x"
locale: "en-US"

The locale parameter must be specified in the BCP47 format. You can find a list of the available locales here.

Choice Extension

New in version 2.1.2

The Choice extension was introduced in version 2.1.2.

The Choice extension can be used to open a selection dialog, letting you choose the right value from a list. For example, lets consider the following snippet:

  - trigger: ":quote"
replace: "{{output}}"
vars:
- name: output
type: choice
params:
values:
- "Every moment is a fresh beginning."
- "Everything you can imagine is real."
- "Whatever you do, do it well."

In this case, typing :quote will open the Search bar, letting you choose the right value:

Choice Extension

Difference with Match Disambiguation

If your goal is to choose between different replacements starting from a single trigger, you should prefer the built-in Match Disambiguation feature.

In a nutshell, Espanso automatically shows a selection dialog after typing a trigger that's shared between multiple matches. For example, the previous example is functionally equivalent to adding these 3 matches:

  - trigger: ":quote"
replace: "Every moment is a fresh beginning."
- trigger: ":quote"
replace: "Everything you can imagine is real."
- trigger: ":quote"
replace: "Whatever you do, do it well."

Because all three matches share the same trigger, Espanso will let you choose the right one after typing :quote.

At this point, you might be wondering why the Choice extension was needed in the first place. The answer is that for some advanced use-cases (including scripts and other transformations), having an extension that lets you choose a value comes handy.

Advanced use with IDs

Using the Choice extension as shown in the previous section is enough for most use-cases, but it has one significant limitation: the label shown in the list and the final value are the same.

For example, if you select "Every moment is a fresh beginning." from the search bar, the value of output will be "Every moment is a fresh beginning."

For advanced use-cases, you might want to differentiate between the label (the text shown in the selection dialog), with the actual value of the item:

matches:
- trigger: ":quote"
replace: "{{output}}"
vars:
- name: output
type: choice
params:
values:
- label: "Every moment is a fresh beginning."
id: "bar"
- label: "Everything you can imagine is real."
id: "foo"
- label: "Whatever you do, do it well."
id: "foobar"

In this case, typing :quote and selecting "Every moment is a fresh beginning" will insert bar instead.

Random Extension

The Random Extension can be used to write non-deterministic replacement texts. In other words, you can specify a set of possible expansions for a match and Espanso will choose a random one, useful to avoid repetitions.

You can use this feature by declaring a variable of type random and then passing a number of choices as a parameter:

  - trigger: ":quote"
replace: "{{output}}"
vars:
- name: output
type: random
params:
choices:
- "Every moment is a fresh beginning."
- "Everything you can imagine is real."
- "Whatever you do, do it well."

In this case, typing :quote will expand randomly to one of the tree quotes.

Clipboard Extension

The Clipboard Extension enables to include the current clipboard content in a match.

For example, let's imagine you want to create the ultimate HTML link shortcut:

  - trigger: ":a"
replace: "<a href='{{clipboard}}' />$|$</a>"
vars:
- name: "clipboard"
type: "clipboard"

If you now copy a link in the clipboard (for example by selecting it and then CTRL+C) and then type :a, you'll see the following replacement appear:

<a href='YOUR_COPIED_LINK'></a>

Echo Extension

The Echo extension makes it easy to create variables containing a fixed value. For example:

  - trigger: ":greet"
replace: "Hello {{myname}}"
vars:
- name: myname
type: echo
params:
echo: "John"

In this case, typing :greet gets expanded to Hello John.

This extension is particularly useful to define common global variables, such as:

global_vars:
- name: myname
type: echo
params:
echo: "John"

matches:
- trigger: ":greet"
replace: "Hello {{myname}}"

- trigger: ":sig"
replace: "Best regards, {{myname}}"

Script Extension

There will be tasks for which espanso was not designed for. For those cases, espanso offers the Script Extension, that enables you to call an external script, written in any language, and use its output in a match.

To better understand this feature, let's dive into an example:

We want to use the output of a Python script as an expansion. Let's create the script.py file, place it anywhere you want and paste the following code:

print("Hello from python")

Now take note of the path of the script, and add the following match to the espanso configuration:

  - trigger: ":pyscript"
replace: "{{output}}"
vars:
- name: output
type: script
params:
args:
- python
- /path/to/your/script.py

If you now try to type :pyscript anywhere, you should see Hello from python appear.

You can do the same thing with any programming language, just change the args array accordingly.

script location

The current best-practice when creating Script matches is to create a scripts directory in the espanso directory (at the same level of the match and config directory) and store the scripts there.

That way, you can use the %CONFIG% wildcard to automatically replace the config directory with the correct path, such as:

  - trigger: ":pyscript"
replace: "{{output}}"
vars:
- name: output
type: script
params:
args:
- python
- "%CONFIG%/scripts/script.py"

This makes it easier to create matches that work across many machines.

a note about performance

Because of the execution time, you should limit yourself to fast-running scripts to avoid any lag.

Useful Environment Variables

When triggering the shell command, Espanso also injects a few useful Environment Variables that you can use:

  • CONFIG: Points to the path of the espanso config directory
  • All the values of the previously evaluated match variables. For more information, check out the Variables section.

Shell Extension

The Shell Extension is similar to the Script Extension, but instead of executing a script, it executes shell commands. This offers a lot of flexibility on Unix systems thanks to the bash shell (and thanks to PowerShell/WSL support also on Windows).

Let's say you regularly send your IP address to your coworkers. You can setup a match to fetch your public IP from ipify.

Note: this example uses the curl command, usually preinstalled on most Unix systems.

  - trigger: ":ip"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "curl 'https://api.ipify.org'"

Now everytime you type :ip, it gets expanded to your public IP address!

Choosing the Shell

The shell extension supports many different shells out of the box. By default it uses:

  • Powershell on Windows
  • bash on Linux
  • sh on macOS

You can also specify different shells by using the shell param. For example, let's say we want to use bash on Windows through the Windows Subsystem for Linux. We would use:

  - trigger: ":ip"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "curl 'https://api.ipify.org'"
shell: wsl

Other possible values for the shell parameter are:

  • On Windows: cmd, powershell, wsl
  • On macOS: sh, bash
  • On Linux: sh, bash

Bash pipes

This extension also supports bash pipes as your shell does, such as:

  - trigger: ":localip"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "ip a | grep 'inet 192' | awk '{ print $2 }'"

Trimming the output

It's very common for commands to have outputs that also spawn a newline at the end. By default a trim option is enabled to remove any excess spaces/newlines. You can optionally disable the trim option:

  - trigger: ":localip"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "ip a | grep 'inet 192' | awk '{ print $2 }'"
trim: false

Useful Environment Variables

When triggering the shell command, espanso also injects a few useful Environment Variables that you can use:

  • CONFIG: Points to the path of the espanso config directory
  • All the values of the previously evaluated match variables. For more information, check out the Variables section.

Using Linux commands on Windows

As you might have understood from previous sections, Espanso supports the Windows Subsystem for Linux through the shell: wsl parameter. This allows Windows users to execute Linux commands from their machine.

Debugging

Sometimes it's useful to understand what get's executed exactly, what are the return codes and error messages returned by the command. In order to do that, you can use the debug: true option:

  - trigger: ":localip"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "ip a | grep 'inet 192' | awk '{ print $2 }'"
debug: true

At this point, after triggering a match, the logs will be populated with useful information. Too see them, use the espanso log command.

Form Extension

Espanso's forms are implemented as extensions under the hood, and therefore you can use them as you would do with any other extension.

Espanso Form

Besides regular expansions, you can also pass the values inserted inside the form to other extensions, such as scripts, opening up a world of possibilities.

For more information, please visit the Forms section.

Donate

Hi! I'm Federico, the creator of espanso. I develop espanso in my (little) spare time and I decided to make it open source because I thought it could be useful to many people.

If you liked the project, please consider making a small donation, it really helps :)

A special thanks goes to all the wonderful people who supported espanso along the way

Together, we will make espanso the first universal text expander, open to everyone.

Contributing

Espanso is open source and hosted on GitHub.

Star

If you find a bug or have an idea for a new feature, please open an issue on GitHub.