Note: at the moment, passive mode is still experimental and has to be enabled manually. Please see the “Enabling passive mode” section below.
In version 0.5.0, espanso introduced Passive Mode, a new feature which allows the user to expand matches after typing them, instead of in realtime. The feature works as follows:
CTRLkey (you can customize this key).
As a result, espanso will copy the text, process it expanding all the matches, and then paste it back in the field.
Passive mode is still in its experimental stage, so it must be enabled manually. Add the following lines in the
enable_passive: true passive_key: CTRL
passive_key parameter accept the following alternatives:
META (Win key on Windows and Linux, CMD on macOS). If you’d like other possibilities, please open an issue.
Passive match triggers are a bit more limited than normal triggers. In particular, they have to start with a
: prefix (though you can customize it, see below)
and should not contain spaces.
The default format of passive matches is:
But arguments are optional:
You can customize the default format by changing the configuration file, please take a look at the “Advanced Configuration” below.
One of the most requested features has always been match arguments. Due to the realtime nature of espanso, this problem was very difficult to solve in a solid way. The solution is to use passive mode, so that espanso can analyze whole sentences and execute a more complex elaboration.
Which can be obtained with the following:
- trigger: ":greet" replace: "Hey $0$, how are you?\nIt's been a while!" passive_only: true
If you select
:greet/Jon/ and trigger the passive mode, the match will be expanded producing:
Hey Jon, how are you? It's been a while!
$0$ keyword indicates where the argument should be placed, and you can also pass multiple arguments, so
that they becomes
passive_only keyword, which makes espanso ignore the match when typing it (otherwise, espanso would
expand it right away).
The really powerful thing is that you can pass these arguments to the shell or custom scripts as well:
This can be done by including
$1 in the
- trigger: ":rev" replace: "" passive_only: true vars: - name: output type: shell params: cmd: "echo $0 | rev" trim: true
For Windows users: instead of
$0, you must use
inject_args parameter, arguments will be appended to the given list when launching a program. For example:
- trigger: ":pyscript" replace: "" vars: - name: output type: script params: inject_args: true args: - python - /path/to/your/script.py
At this point, if you expand
:pyscript/hello/, your script will receive “hello” as the first argument.
Passive mode does not work in terminals. Unfortunately, because this feature heavily uses selections and copy/pasting to work, I still haven’t figured out a way to reliably make them work in terminals.
Matches have to start with a specific character. The default character is
:, but that can be customized
by changing the
passive_match_regex parameter. This constraint has been added to improve the analysis efficiency.
Passive matches do not support images.
If you don’t like the
:trigger/arg1/arg2/ syntax, you can customize it by changing a few parameters in your
default.yml config as follow:
passive_match_regex you can customize the main trait of the passive matches, such as the prefix character and the external argument separators.
By default, it has the following value (notice the
\\ escaping which is mandatory):
It may seem scary at first, but it’s pretty easy to change. For example, let’s say you want to start passive matches with
. instead of
:, you can write:
<name> instead of the
Another thing you may want to change are the external argument separators, let’s say you want to use parenthesis
() instead of the default
//. A solution would be:
\\) difference before and after the
A thing to keep in mind here is that, although you changed the external argument char, you
didn’t change the argument delimiter, and therefore you still need to write
:trigger(arg1/arg2). To solve the problem, you have to change the following parameter:
Let’s say you want to separate inner arguments by a comma
,, such as
:trigger/arg1,arg2/. You can do so by customizing the
An important thing to keep in mind here is escaping: what if one of the arguments contains the arg delimiter?
By default, you can escape the character with
\, such as
:trigger/Today is the 10\/12/, but you can also change this escaping char by using the following parameter:
This option regulates which character will act as an escape, by default is
Hi! I'm Federico, the creator of espanso. I developed 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 :)Donate with PayPal Become a GitHub Sponsor