espanso/espanso v0.5.0

on GitHub

Hey expanders!
After a long wait, espanso 0.5.0 has finally been released and brings many new features!
Note: it could take me a few days to update the docs.

New features

Passive mode

NOTE: this feature is still in the experimental stage, and must be switched on manually

Originally proposed by @telmotrooper in #62, passive mode has finally been implemented.
This alterative mode allows the user to expand matches after typing them, instead of in realtime.

The feature works as follows:

• Type a message containing any number of matches (passive mode matches are more limited, see the Limitations paragraph below)
• Select the text you want to process (conveniently done with the CTRL+A shortcut)
• Double press the CTRL key (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.

Why should this be useful though? Many things! Let's see them:

Arguments

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

The $0$ keyword indicates where the argument should be placed, and you can also pass multiple arguments, so
that they becomes $1$, $2$, ecc.

Notice the 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:

Integration with Shell

This can be done by including $0, $1 in the cmd parameter:

- trigger: ":rev"
  replace: "{{output}}"
  passive_only: true
  vars:
    - name: output
      type: shell
      params:
        cmd: "echo $0 | rev"
        trim: true

For Windows users: instead of $0, you must use %0.

Integration with Scripts

Using the inject_args parameter, arguments will be appended to the given list when launching a program. For example:

- trigger: ":pyscript"
  replace: "{{output}}"
  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.

Limitations

• 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.

Enabling passive mode

Passive mode is still in its experimental stage, so it must be enabled manually. Add the following lines in the
default.yml file:

enable_passive: true
passive_key: CTRL

Currently, the passive_key parameter accept the following alternatives: CTRL, ALT, SHIFT and META (Win key on Windows and Linux, CMD on macOS). If you'd like other possibilities, please open an issue.

More information can be found in the documentation (could take a few days to update).

Nested matches

Originally proposed by @timorunge in #110, nested matches allow you to include the output of a match inside
another one. For example:

- trigger: ":one"
  replace: "nested"

- trigger: ":nested"
  replace: "This is a {{output}} match"
  vars:
    - name: output
      type: match
      params:
        trigger: ":one"

At this point, if you type :nested you'll see This is a nested match appear.

Global variables

Originally proposed by @simon-wolf in #162, global matches allow the definition of global variables that
can be used in all matches. In your default.yml file, you can add:

global_vars:
  - name: "global1"
    type: "shell"
    params:
      cmd: "echo global var"
  - name: "greet"
    type: "dummy"
    params:
      echo: "Hey"

At this point, you can use global1 and greet in all your matches:

- trigger: ":hello"
  replace: "{{greet}} Jon"

And typing :hello will result in Hey Jon.

For Ubuntu/Debian users

Espanso now ships with a experimental deb package! If you want to try it out, here's how you can migrate:

Before removing the espanso binary, unregister it from Systemd.

espanso unregister

Then remove the old binary (if you followed the instructions it is located in /usr/local/bin/espanso).

At this point, download espanso-debian-amd64.deb and type the following command (making sure you are in
the same directory as the deb file):

sudo apt install ./espanso-debian-amd64.deb

This new approach offers a number of benefits, such as the automatic dependency management and ease of upgrade.

Conflicting triggers warning

Suggested by @tiktuk in #135, espanso now warn the user in case there are conflicting triggers, such as :abcd and :ab.

Bug fixes

• Added support for Yakuake terminal. Fix #153
• Added support for Tilix terminal. Fix #143
• Added delay to fix possibile race condition when using preserve_clipboard. Fix #148
• Fix bug that prevented certain applications, such as Photoshop, from working correctly with espanso on macOS. Fix #159