Bot releases are visible (Hide)
Published by federico-terzi about 4 years ago
Version 0.7.0 is here, and brings a few very powerful features!
Note: this feature is still experimental, so expect a few rough edges. If you encounter any problem, please open an issue :)
One of the most requested features is finally here: forms!
This opens up a world of possibilities, such as creating matches with multiple parameters and scripts with arguments.
To avoid bloating espanso with unnecessary dependencies, this feature is extracted as a separate component, modulo.
If you are a Windows or macOS user, the latest version of espanso automatically ships with modulo, so you don't have to install anything.
Due to the great fragmentation in the linux world, I decided to package modulo
as an AppImage. In order to use it from espanso, you'll have to complete these steps:
$HOME/opt
chmod u+x modulo*.AppImage
modulo
has to be visible in the PATH as modulo
. The easiest way to achieve it is creating a link with:sudo ln -s $HOME/opt/modulo*.AppImage /usr/bin/modulo
To try out the new feature, create a new match as follows:
- trigger: ":form"
form: "Hey {{name}}, how are you?"
Reload the changes and type ":form". If you did everything correctly, you should see a form appear!
To submit the value you have 2 alternatives, you can either:
As you can see from the example, instead of using the usual replace
clause, we used form
. This is just syntactic sugar to make it easier to use forms, but in the following sections you will learn the complete syntax, necessary if you want to use forms with scripts.
The only important thing to notice is that where we wanted to put a field in the form, we used the double brakets syntax {{field_name}}
.
In the example we've just seen, only a simple text field was used, but modulo supports other controls, such as multiline text fields, choice boxes and list boxes (with more to come in future versions).
To specify the control type, you have to specify the form_fields
param. An example would be:
- trigger: ":form"
form: |
Hey {{name}},
{{text}}
{{greet}}
form_fields:
text:
multiline: true
greet:
type: choice
values:
- First choice
- Second choice
Which produces this result:
Some of you might be confused with the
|
char. That is used to specify a multiline string in YAML
In this example we can see:
text
field is now a multiline text fieldgreet
field is a Choice boxBefore diving into the next section, it might be useful to explain some of the variable system improvements that were introduced to support forms in the first place.
Starting from version 0.7.0, most variables can now use the value of other (previously declared) variables in their body.
Not all variable types support variable injection, but notably Shell and Script extensions do through the use of ad-hoc environment variables. Take the following example:
Let's say we want to reverse the string produced by the Date Extension:
- trigger: ":reversed"
replace: "Reversed {{myshell}}"
vars:
- name: mytime
type: date
params:
format: "%H:%M"
- name: myshell
type: shell
params:
cmd: "echo $ESPANSO_MYTIME | rev"
This match produces the result we expected. If the current time was 11:54
, it produces:
Reversed 45:11
Let's analyze it step by step:
mytime
is evaluated first (as it's the first declared in the vars
list).myshell
shell command, in particular through the $ESPANSO_MYTIME
env variable.rev
commandreplace
text and expanded.As you might have already guessed, the previous variables are injected in the Shell variable (and the Script extension works in the same way) with the naming ESPANSO_UPPERCASE-VAR-NAME
.
Make sure to avoid spaces in the variable names, as they can become problematic in this situation
If you are using global variables, you have to be careful in this case, as they are implicitly evaluated before the local ones.
If you need to evaluate a global variable after a local one (which might be necessary if you want to inject another variable value inside it), you can do so as follows:
# Considering the following global variable
global_vars:
- name: "reversed"
type: shell
params:
cmd: "echo $ESPANSO_VARNAME | rev"
matches:
- trigger: ":rev"
replace: "{{reversed}}"
vars:
- name: "varname"
type: echo
params:
echo: "hello"
- name: "reversed"
type: "global"
The key element here is the global
type, which tells espanso to evaluate variable reversed
only at that point, and not before varname
.
Hopefully, you now understand how variable values are injected between one another. Turns out, forms are variables as well!
In fact, our first example:
- trigger: ":form"
form: "Hey {{name}}, how are you?"
is a shorthand for the following match:
- trigger: ":form"
replace: "Hey {{form1.name}}, how are you?"
vars:
- name: "form1"
type: form
params:
layout: "Hey {{name}}, how are you?"
What this does is simply generating a form with the given layout, and then injecting the resulting fields (form1.name
) into the replacement text.
All right, but how can we use forms with the shell extension?
Let's say that we want to create a match that prompts for user input, and then expands to the reverse of what the user inserted.
That could be implemented with:
- trigger: ":rev"
replace: "{{reversed}}"
vars:
- name: form1
type: form
params:
layout: |
Reverse {{name}}
- name: reversed
type: shell
params:
cmd: "echo $ESPANSO_FORM1_NAME | rev"
The key aspect here is that the value of the form field is injected in the shell variable as ESPANSO_FORM1_NAME
. The naming is pretty straightforward, as the form variable is called form1
and the field is called name
.
For the expansion to take place on macOS, you have to release the submit keys (CTRL+Enter) after submitting the form.
Another highly requested feature was backspace-to-undo:
If you press backspace immediately after an expansion takes place, the expansion is reversed:
If for some reason you need to backspace without reverting the expansion, press SHIFT+BACKSPACE instead.
You can disable it with:
undo_backspace: false
Please note that this feature is experimental, so if you notice any problem please open an issue!
offset
parameter to Date extension to express dates before/after the current one. See #311Published by federico-terzi over 4 years ago
Version 0.6.3 is here, and brings a series of bug fixes and a new feature!
You can now list all the registered matches with the command:
espanso match list
And trigger an expansion from the CLI with the command:
espanso match exec <trigger>
This is particularly useful when integrating with tools like Rofi. See example
Note: there are still a few rough edges in this feature, so if you notice any bug please open an issue!
bash
instead of wsl
command..git
suffix when installing packages from custom repositories. Fix #326Published by federico-terzi over 4 years ago
Version 0.6.2 is here! Nothing too special, just some bug fixes ¯\(ツ)/¯
In this version, the auto-restart on config changes is turned on by default. If you don't like this approach, you can disable it by adding this line to your default.yml
file:
auto_restart: false
Published by federico-terzi over 4 years ago
Version 0.6.1 is here, bringing mostly bug fixes and minor features:
trim
option in Shell Extension is now set to true by default. #272CONFIG
env variable to the spawned process with the path of the config directory, making it easier to write cross-machine scripts. #277Published by federico-terzi over 4 years ago
Version 0.6.0 is here, bringing a couple of new features and a many improvements!
This feature, requested many times before, allows espanso to "listen" for changes in the configuration files and automatically restart itself when needed, making frequent changes much more convenient!
To try this new feature, enable it in your default.yml
file with:
auto_restart: true
And then restart espanso!
There are times in which a full restart is still beneficial, such as after installing a package, to make sure espanso picks up all new changes.
If you notice any strange behavior or bug, don't hesitate to open an issue.
Requested by many users in #55, espanso now allows to install packages from GitHub repositories outside the espanso hub.
The command to use has the following format:
espanso install <package_name> <repo_url> --external
Those repositories must comply with the format specified in the package-example.
The Shell Extension now allows the user to select the preferred shell, which is particularly beneficial on Windows. In particular, this new version also allows to execute a shell command on WSL, harnessing the full power of Linux shell on Windows!
Example of usage:
- trigger: ":shell"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "echo hello from linux!"
shell: "wsl"
The shell
parameter can be either: cmd
, powershell
or wsl
on Windows.
Note: now the default shell on Windows is Powershell.
espanso edit
subcommand to accept EDITOR
with parameters. Fix #245%HOME%
to the user home directory in paths, making it possibile to define cross-platform script paths. Fix #265Published by federico-terzi over 4 years ago
Version 0.5.5 is here, and brings massive improvements on Linux.
NOTE: This feature is still experimental, so it must be enabled manually.
In the last few days I've been working hard to improve the expansion speed on Linux.
This version brings an improved text injection mechanism that relies on XSendEvent
rather than XTestFakeKeyEvent
, which is much faster.
I've tested it on various distros and applications, and it always worked pretty well. That said, I don't exclude the possibility of some compatibility problems. If you experience any of them, please open an issue.
This improvement should be particularly noticeable on Gnome distros (such as stock Ubuntu).
To enable fast injection, just add the following line on your default.yml
config:
fast_inject: true
NOTE: make sure you didn't specify
backend: Clipboard
, otherwise this setting won't have any effect.
A special thanks to AutoKey, a great open-source text expander for Linux, from which I took some inspiration for this feature.
Originally proposed by @timorunge in #95, now espanso gives the possibility to hide the status icon on Windows and macOS, as well as disabling notifications.
In particular, you can add the following to your default.yml
config:
show_icon: false # Disable the status icon
show_notifications: false # Disable the notifications
Auto
backend is now the default one on Linux.Published by federico-terzi over 4 years ago
Version 0.5.4 is here! Let's see the changes:
To add a layer of security, now most Hub packages have been moved to the core repository.
The end user shouldn't experience any difference from the previous version, with the only exception being:
Some packages (namely the bigger ones that would make the core repository too large) are now considered external, and espanso will block the installation by default, prompting the user to verify the source of the package (the repository).
In case the user wants to proceed with the installation, a the --external
flag could be used:
espanso install <package> --external
On macOS there is a security feature known as SecureInput
, which blocks text expanders from detecting input when entering text in sensitive areas, such as password fields (but also other apps, even the Terminal if configured).
As a result, espanso will not work in those situations, and many users didn't understand this apparently strange behavior.
To better inform the user, now espanso will trigger a notification (as well as logging it) to warn the user if an app triggers SecureInput.
If you want to disable the notification, just add the following line in your config file:
secure_input_notification: false
Espanso has removed its git2
dependency, which means macOS users won't have to install openssl
anymore, making it much easier to install without Homebrew.
For more information, see: #218.
Published by federico-terzi over 4 years ago
Version 0.5.3 brings a couple of bugfixes and general improvements:
vcruntime140_1.dll
. Fix #203conflict_check
by default, as it yield a lot of false positives while not providing much value.Published by federico-terzi over 4 years ago
Version 0.5.2 is here!
It ships various improvements and optimizations, let's see them:
This feature is still experimental, and thus must be enabled manually. Check the section below for more information
On Linux systems there was a long standing issue with text injection, which prevented certain apps from correctly handling special characters (such as emojis or accented letters) when injected (for example on Firefox).
For this reason, espanso initially defaulted on the Clipboard backend on Linux, as it was the most reliable (working in 99% of cases), even though it was less efficient and with a few inconveniences (for example, the previous clipboard content being overwritten).
Espanso now ships with the Auto backend, which tries to take it a step further, by automatically determining when an injection is possible (only ascii characters in the replacement), and falling back to the Clipboard backend otherwise.
This new approach should offer substantial benefits to Linux users.
Add the following line to your default.yml
configuration to enable the backend:
backend: Auto
and restart espanso.
Please let me know if you experience any problem with this new mode :)
Originally proposed by @lkrms in #117, you can now specify a more specific toggle_key
option (and the same goes for passive_key
).
The new options are:
LEFT_CTRL
RIGHT_CTRL
LEFT_ALT
RIGHT_ALT
LEFT_META
RIGHT_META
LEFT_SHIFT
RIGHT_SHIFT
All the other options are still valid, for example specifying CTRL
is equivalent to accepting both LEFT_CTRL
and RIGHT_CTRL
.
Published by federico-terzi over 4 years ago
Version 0.5.1 is finally here and brings a few interesting features!
Let's see them:
Originally proposed by @GJKrupa in #171 , espanso now ships with the edit
subcommand, which makes editing configuration files much more convenient. Let's see how it works:
If you open a terminal and type:
espanso edit
the default system editor (Notepad on Windows and Nano on Unix systems) will be spawned, editing the default.yml
. Then, after you saved the file and exited the editor, espanso will automatically restart, loading the new changes.
But wait! Nano? Are you serious?
I thought about it for a while, and eventually I opted for a newby-friendly approach (what if one of our fellows
expanders gets trapped into VIM? :)
Jokes aside, customizing the editor is super easy, just specify your choice in the EDITOR
(or VISUAL
)
envorionment variables, such as:
EDITOR=/usr/bin/vim
If you invoke espanso edit
without further arguments, it will open the default.yml
file. But what if you want to edit files in the user/*
directory? Luckily, you can simply specify the name as an additional argument (without the extension).
For example, if you want to edit the user/email.yml
file, you can type:
espanso edit email
Espanso now allows to include the current clipboard content in a match, which can be useful in many situations.
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 and then CTRL+C) and then type :a
, you'll
see the following replacement appear:
<a href='YOUR_COPIED_LINK'></a>
Too see the reasons behind this feature, see #192.
Originally proposed by @muhlinux in #144, now espanso allows matches to have multiple triggers, by using
the triggers
keyword and specifying a list of valid triggers:
- triggers: [":lol", ":xd"]
replace: ":laughing:"
Originally proposed by @muhlinux in #152, espanso now support matches that propagate the casing of the trigger. Just add the propagate_case: true
option in a match, such as:
- trigger: foo
replace: bar
propagate_case: true
word: true
Based on the case style you use in the trigger, espanso will trigger the replacement as:
foo => bar
Foo => Bar
FOO => BAR
preserve_clipboard
option is enabled by default.Published by federico-terzi over 4 years ago
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.
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:
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:
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:
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
.
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.
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.
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).
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.
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
.
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.
Suggested by @tiktuk in #135, espanso now warn the user in case there are conflicting triggers, such as :abcd
and :ab
.
preserve_clipboard
. Fix #148Published by federico-terzi almost 5 years ago
Hello fellow expanders!
Version 0.4.1 brings some interesting new features, as well as many bug fixes.
Espanso now supports a way to partially preserve your previous clipboard when expanding a match instead of overwriting it. At the moment, it only preserve text-based clipboards, so if you had pasted an image, espanso will overwrite it even with this option enabled.
Because this is still experimental, you will need to enable it manually by adding the following line in your default.yml
config:
preserve_clipboard: true
In the next release, unless any problems arise, the feature will be turned on by default.
A great thank you to @matt-h, who laid the foundations of this new feature.
You how have the possibility to write non-deterministic replacement texts. Said in other words, you can now specify a set of possible expansions for a match, useful to avoid repetitions.
This feature works as any other extension. You declare a variable of type random
and then pass 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.
trim: true
parameter in a shell extension to trim the output from any space/newline character. For example: - trigger: ":shell"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: "echo Hello from your shell"
trim: true
Published by federico-terzi almost 5 years ago
Version 0.4.0 is here!
Before we start, a quick announcement: we now have an official espanso subreddit!
Join the community if you want to stay updated with the latest news, tips and tricks :)
Initially proposed in issue #96, you can now use espanso to expand matches into images!
They are pretty easy to use, just use the following match syntax:
- trigger: ":cat"
image_path: "/path/to/image"
For more information, check out the documentation.
Published by federico-terzi almost 5 years ago
Published by federico-terzi almost 5 years ago
Add the espanso path default
command line option to print the configuration file path. This is useful to quickly edit the configuration file (for example, by using vim $(espanso path default)
). Other options are available, you can check them out with espanso path help
.
Fix bug #112 that prevented Simple terminal from working correctly on Linux with Clipboard backend.
Make the ZIP crate dependency macOS specific, to reduce binary size on other platforms.
Published by federico-terzi almost 5 years ago
I've been quite busy this week, so I only managed to fix a couple of bugs.
But as my grandmother always says: something is better than nothing :)
Published by federico-terzi almost 5 years ago
This week I introduced a couple of great features proposed by the community:
Please note that at this point you should consider both of these features as
experimental and be prepared for some changes.
I highly suggest you to open an issue if you encounter any problem or have suggestions
on ways to improve them.
Originally proposed by @cambid in #92, espanso now supports cursor hints in matches
to move the cursor on the given position after the expansion.
You just need to add $|$
in the replace
clause where you want the cursor to be
positioned afterwards. For example:
- trigger: ":div"
replace: "<div>$|$</div"
If you now type :div
, espanso will expand the match and put the cursor between the tags.
Documentation: https://espanso.org/docs/matches/#cursor-hints
Originally proposed by @timorunge in #82, espanso now supports word matches, a way
to define matches that are expanded only when surrounded by word separators, such as
spaces or commas.
This makes possible to use espanso as an autocorrection tool for typos. For example:
Let's say you occasionally type ther
instead of there
. Before this release,
you could have used espanso like this:
- trigger: "ther"
replace: "there"
This would correctly replace ther
with there
, but it also has the problem of expanding
other
into othere
, making it unusable.
With word triggers you can now add the word: true
property to a match, telling espanso
to only trigger that match if surrounded by word separators. So in this case it becomes:
- trigger: "ther"
replace: "there"
word: true
At this point, espanso will only expand ther
into there
when used as a standalone word.
Documentation: https://espanso.org/docs/matches/#word-triggers
Published by federico-terzi about 5 years ago
Nothing too interesting this week, mostly bug fixing.
I've been very busy with some upcoming exams, but next week I plan to release a couple of great features proposed by the community.
Stay tuned :)
Published by federico-terzi about 5 years ago
.espanso
config directory to new locations to better integrate with the OS. Fixed #73. More info here: https://espanso.org/docs/configuration/
Published by federico-terzi about 5 years ago
Fixed bugs #65 #63 #67 #66