Update the docs
This commit is contained in:
Federico Terzi
parent
2822a72986
commit
1dca22662c
|
|
@ -7,6 +7,9 @@
|
|||
- name: Matches
|
||||
link: /docs/matches/
|
||||
desc: This sections will cover Matches in detail, showing their features and options.
|
||||
- name: Forms
|
||||
link: /docs/forms/
|
||||
desc: An introduction to Forms, a powerful feature to create customizable prompts.
|
||||
- name: Packages
|
||||
link: /docs/packages/
|
||||
desc: This section will cover the basics and the creation of espanso packages.
|
||||
|
|
@ -18,4 +21,7 @@
|
|||
desc: An introduction to espanso's Passive Mode, one of its most powerful features.
|
||||
- name: Synchronization
|
||||
link: /docs/sync/
|
||||
desc: Keep espanso in sync using Dropbox, Google Drive or GitHub.
|
||||
desc: Keep espanso in sync using Dropbox, Google Drive or GitHub.
|
||||
- name: CLI
|
||||
link: /docs/cli/
|
||||
desc: Some useful terminal commands to interact with espanso.
|
||||
BIN
assets/images/form1.png
Normal file
BIN
assets/images/form1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.4 KiB |
BIN
assets/images/form2.png
Normal file
BIN
assets/images/form2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.0 KiB |
BIN
assets/images/form3.png
Normal file
BIN
assets/images/form3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.3 KiB |
BIN
assets/images/form4.png
Normal file
BIN
assets/images/form4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.2 KiB |
BIN
assets/images/macform.png
Normal file
BIN
assets/images/macform.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
44
docs/cli.md
Normal file
44
docs/cli.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: CLI
|
||||
layout: docs
|
||||
---
|
||||
Espanso ships with a few useful terminal commands that can be used to interact with it.
|
||||
|
||||
### Enable or Disable
|
||||
|
||||
Other than using the `toggle_key` shortcut, you can also enable/disable espanso with the following commands:
|
||||
|
||||
```bash
|
||||
# Enable espanso
|
||||
espanso cmd enable
|
||||
|
||||
# Disable espanso
|
||||
espanso cmd disable
|
||||
|
||||
# Toggle between enabled/disabled
|
||||
espanso cmd toggle
|
||||
```
|
||||
|
||||
These makes it a breeze to control espanso from your desktop environment or other scripts.
|
||||
|
||||
### Listing Matches
|
||||
|
||||
When integrating espanso with a script, it might be useful to list the available matches. You can so so with the following command:
|
||||
|
||||
```
|
||||
espanso match list
|
||||
```
|
||||
|
||||
Run `espanso match list --help` to find out other interesting options.
|
||||
|
||||
### Trigger an injection
|
||||
|
||||
Another interesting possibility is injecting a given match from the command line. You can do so with:
|
||||
|
||||
```
|
||||
espanso match exec <trigger>
|
||||
```
|
||||
|
||||
where `<trigger>` is the match trigger.
|
||||
|
||||
This is useful if, for example, you want to trigger an expansion from a script.
|
||||
|
|
@ -32,15 +32,6 @@ you will be working with. You can find a list of all the possible options in the
|
|||
|
||||
The `user` folder is used to store more advanced user configurations, such as [Application-specific](#application-specific-configurations) configs.
|
||||
|
||||
#### Migrating from versions prior to v0.3.0
|
||||
|
||||
Prior to version v0.3.0, espanso located all configurations in the user home directory, into the `.espanso` folder.
|
||||
This location is now deprecated and, while being still supported for compatibility purposes, you should migrate to the new one with the following steps:
|
||||
|
||||
* Copy the `default.yml` and the `user/` directory in the new `espanso` config folder ( you can find the new config location with the `espanso path` command ).
|
||||
* Copy the contents of the `packages` folder into the new `packages` path ( you can find the new package
|
||||
location with the `espanso path` command ).
|
||||
|
||||
### Quick Editing
|
||||
|
||||
Introduced in version 0.5.1, espanso now ships with the `edit` subcommand, which makes editing configuration files much more convenient. Let's see how it works:
|
||||
|
|
@ -141,7 +132,7 @@ Filter | Description | Windows Support | MacOS Support | Linux Support
|
|||
`filter_exec` | Filter based on the current application executable path | Full support | Full support | Partial support
|
||||
`filter_class` | Filter based on the current Window class | Uses the application executable path instead | Uses the App identifier instead | Full support
|
||||
|
||||
The `filter_title`, `filter_exec` and `filter_class` filters support a full **regex** as parameter.
|
||||
The `filter_title`, `filter_exec` and `filter_class` filters support a full **regex** as parameter, but make sure to escape the special characters properly.
|
||||
|
||||
#### Finding the right filters
|
||||
|
||||
|
|
@ -164,6 +155,45 @@ Detected change, current window has properties:
|
|||
These are the parameters espanso detected for your target application, so you can now use them to create the
|
||||
perfect filter.
|
||||
|
||||
### Customizing the Toggle Key
|
||||
|
||||
By default, espanso can be temporarily disabled and enabled by pressing the Alt key twice, resulting in a
|
||||
notification saying "espanso disabled." Pressing Alt twice again will enable it, and you'll receive a
|
||||
notification saying "espanso enabled."
|
||||
|
||||
If you'd like to customize the key, simply add the `toggle_key` option to your
|
||||
`default.yml` configuration and set it to one of the available options:
|
||||
|
||||
| | | | |
|
||||
|--------------|-------------|---------------|--------------|
|
||||
| `CTRL` | `ALT` | `SHIFT` | `META` |
|
||||
| `LEFT_CTRL` | `LEFT_ALT` | `LEFT_SHIFT` | `LEFT_META` |
|
||||
| `RIGHT_CTRL` | `RIGHT_ALT` | `RIGHT_SHIFT` | `RIGHT_META` |
|
||||
|
||||
And if you'd rather turn it off, you can do so with:
|
||||
|
||||
```yml
|
||||
toggle_key: OFF
|
||||
```
|
||||
|
||||
### Hiding the Icon
|
||||
|
||||
You can hide the espanso icon on macOS and Windows by adding the following option to your `default.yml` file:
|
||||
|
||||
```yaml
|
||||
show_icon: false
|
||||
```
|
||||
|
||||
### Hiding the Notifications
|
||||
|
||||
You can hide the espanso notifications by adding the following option to your `default.yml` config:
|
||||
|
||||
```yaml
|
||||
show_notifications: false
|
||||
```
|
||||
|
||||
**Note for macOS users:** if you only want to hide the *SecureInput* notifications, please read the following section.1
|
||||
|
||||
### macOS Notification for SecureInput
|
||||
|
||||
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).
|
||||
|
|
@ -191,5 +221,6 @@ Option | Description | Possible Values | Default | App-Specific
|
|||
`secure_input_notification` | Enable/Disable the Secure Input notification on macOS | `true`/`false` | `true` | No
|
||||
`show_icon` | Show/Hide the icon in the status bar on macOS and Windows | `true`/`false` | `true` | No
|
||||
`show_notifications` | Show/Hide the notifications| `true`/`false` | `true` | No
|
||||
`undo_backspace` | Enable/Disable the Backspace-To-Undo feature | `true`/`false` | `true`| Yes
|
||||
`fast_inject` | Use a faster injection mechanism (Linux only). It uses XSendEvent API rather than XTestFakeKeyEvent API, which is faster but incompatible with some applications.| `true`/`false` | `true`| Yes
|
||||
|
||||
|
|
|
|||
212
docs/forms.md
Normal file
212
docs/forms.md
Normal file
|
|
@ -0,0 +1,212 @@
|
|||
---
|
||||
title: Forms
|
||||
layout: docs
|
||||
---
|
||||
|
||||
Since version 0.7.0, espanso is capable of creating arbirarly complex input forms:
|
||||
|
||||
|
||||
|
||||
These open up a world of possibilities, allowing the user to create matches with many arguments, as well as injecting those values into custom Scripts or Shell commands.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
In order to use forms, espanso requires [modulo](https://github.com/federico-terzi/modulo) to be installed.
|
||||
If you are a Windows or macOS user, then modulo is most likely already installed with recent versions of espanso, but if you are using Linux, you'll need to [install it manually](/install/linux/#installing-modulo).
|
||||
|
||||
### Getting started
|
||||
|
||||
Let's say you want to create a match for birthday greetings, personalized with the person name. With forms, that would translate to:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":greet"
|
||||
form: |
|
||||
Hey {{name}},
|
||||
Happy Birthday!
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Then, after typing `:greet`, you will be prompted with:
|
||||
|
||||
|
||||
|
||||
After entering the desired name, we can submit the form either by clicking "Submit" or pressing CTRL+Enter.
|
||||
|
||||
The key here is to specify the `form` field rather than `replace`, which is a shorthand for the verbose syntax explained in the following sections.
|
||||
|
||||
{% raw %}
|
||||
You can create as many fields as you like, just indicate them with the double-brackets `{{field_name}}` syntax.
|
||||
{% endraw %}
|
||||
|
||||
### Controls
|
||||
|
||||
In the previous example, we've seen how to use simple text fields, but `modulo` supports many controls, such as:
|
||||
|
||||
* Multiline text field
|
||||
* Choice box
|
||||
* List box
|
||||
|
||||
In order to use another control, we need to specify it in the `form_fields` parameter. Let's say we want to add a multiline text field to our previous example to write our custom message inside the greetings:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":greet"
|
||||
form: |
|
||||
Hey {{name}},
|
||||
{{text}}
|
||||
Happy Birthday!
|
||||
form_fields:
|
||||
text:
|
||||
multiline: true
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
After saving and triggering the match, we would be prompted with a form like the following:
|
||||
|
||||
|
||||
|
||||
Let's analyze the most important bits:
|
||||
|
||||
{% raw %}
|
||||
1. Inside the `form` parameter we specified the `{{text}}` field. This name is arbitrary, you can put whatever you want there.
|
||||
2. In the `form_fields` parameter, we specified that the `text` field had property `multiline: true`
|
||||
{% endraw %}
|
||||
|
||||
Each control has its own options, so let's see them separately:
|
||||
|
||||
#### Text Fields
|
||||
|
||||
{% raw %}
|
||||
Text Fields are the default control. Anytime you specify a new field using the `{{field_name}}` syntax, that field is considered a text field, if not specified otherwise.
|
||||
|
||||
| Property | Description | Default value |
|
||||
| ---------|-------------|---------------|
|
||||
| multiline | If `true`, the text field becomes a multiline text area | `false` |
|
||||
| default | Specify the default value of the field | `null` |
|
||||
|
||||
{% endraw %}
|
||||
|
||||
#### Choice Box
|
||||
|
||||
Choice boxes are fields in which the user can select one choice in a list. In order to use it, you have to specify the `type: choice` parameter, along with an array of `values`:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":form"
|
||||
form: |
|
||||
{{choices}}
|
||||
form_fields:
|
||||
choices:
|
||||
type: choice
|
||||
values:
|
||||
- First choice
|
||||
- Second choice
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Which produces:
|
||||
|
||||
|
||||
|
||||
| Property | Description | Default value |
|
||||
| ---------|-------------|---------------|
|
||||
| default | Specify the default value of the field | `null` |
|
||||
|
||||
#### List Box
|
||||
|
||||
List boxes are completely equivalent to Choice Boxes, with the only difference of requiring `type: list` rather than `type: choice`.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":form"
|
||||
form: |
|
||||
{{choices}}
|
||||
form_fields:
|
||||
choices:
|
||||
type: list
|
||||
values:
|
||||
- First choice
|
||||
- Second choice
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Which produces:
|
||||
|
||||
|
||||
|
||||
### Using with Script and Shell extension
|
||||
|
||||
The syntax proposed above works for most cases, but there are times in which you might want to harness the full power of espanso forms, for example using them with the Script and Shell extension.
|
||||
|
||||
The first important thing to understand is that the following syntax:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":form"
|
||||
form: "Hey {{name}}, how are you?"
|
||||
```
|
||||
|
||||
is a shorthand of the following match:
|
||||
|
||||
```yaml
|
||||
- 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. It should be clear now that **forms are extensions themselves**, just like the Date and Script extension.
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
- 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`.
|
||||
|
||||
To understand more about the variable injection mechanism, please read the [Advanced Topics](/docs/matches/#advanced-topics) section.
|
||||
{% endraw %}
|
||||
|
||||
#### Controls with the Verbose syntax
|
||||
|
||||
If you want to use other Controls in a form specified using the above (verbose) syntax, you would have to specify the `fields` parameter:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":form"
|
||||
replace: "Hey {{form1.name}}, how are you?"
|
||||
vars:
|
||||
- name: "form1"
|
||||
type: form
|
||||
params:
|
||||
layout: "Hey {{name}}, how are you?"
|
||||
fields:
|
||||
name:
|
||||
multiline: true
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Note that **the `fields` parameter content is specified as the `form_fields` parameter explaned above**.
|
||||
|
||||
### macOS remarks
|
||||
|
||||
For the expansion to take place on macOS, you have to release the submit keys (CTRL+Enter) after submitting the form.
|
||||
|
|
@ -7,9 +7,9 @@ Make sure to [install espanso](/install) before diving into the next sections.
|
|||
|
||||
### Starting espanso
|
||||
|
||||
If you followed the [Windows](/install/win/) or [MacOS](/install/mac/) installation correctly,
|
||||
If you followed the installation correctly,
|
||||
**espanso will be automatically started** when you power up your computer. There are times,
|
||||
however, when you may need to start espanso explicitly, such as when you're using Linux.
|
||||
however, when you may need to start espanso explicitly.
|
||||
|
||||
It's very easy to check if espanso is currently running: if you're using **MacOS** or **Windows**,
|
||||
you should see the **icon in the status bar**. If you don't see it, or if you're using **Linux**,
|
||||
|
|
@ -55,14 +55,14 @@ reside in the `espanso` directory, whose location depends on the current OS:
|
|||
* macOS: `$HOME/Library/Preferences/espanso` (e.g. `/Users/user/Library/Preferences/espanso`)
|
||||
* Windows: `{FOLDERID_RoamingAppData}\espanso` (e.g. `C:\Users\user\AppData\Roaming\espanso`)
|
||||
|
||||
> By default, configuration folder is hidden in most systems. To open it, copy path of your configuration folder and paste it in the address bar (aka path bar) of your file manager/explorer.
|
||||
|
||||
A quick way to find the path of your configuration folder is by using the following command:
|
||||
|
||||
```bash
|
||||
espanso path
|
||||
```
|
||||
|
||||
> By default, configuration folder is hidden in most systems. To open it, copy path of your configuration folder and paste it in the address bar (aka path bar) of your file manager/explorer.
|
||||
|
||||
While this folder may contain many different files, let's focus on the most important one: `default.yml`.
|
||||
|
||||
The `default.yml` file contain the **main espanso configuration** and uses the widely
|
||||
|
|
@ -133,7 +133,7 @@ matches:
|
|||
...
|
||||
```
|
||||
|
||||
We're almost there! After every configuration change, **espanso must be restarted**. Open a terminal and type:
|
||||
We're almost there! After every configuration change, **espanso must be restarted**. Recent versions **automatically restart when a file change is detected**, but if you disabled that option, you'll need to do so manually by opening a terminal and typing:
|
||||
|
||||
```bash
|
||||
espanso restart
|
||||
|
|
@ -141,12 +141,21 @@ espanso restart
|
|||
|
||||
Now try to type `:br` anywhere. If you did everything correctly, you should see `Best Regards` appear!
|
||||
|
||||
> In version 0.5.1, espanso introduced the `edit` subcommand which makes editing configuration files much easier.
|
||||
Take a look at [Quick Editing](/docs/configuration/#quick-editing) if you are interested.
|
||||
#### Quick Editing
|
||||
|
||||
If you are comfortable using the terminal to edit your configs, you can also use the much quicker:
|
||||
|
||||
```
|
||||
espanso edit
|
||||
```
|
||||
|
||||
command in the terminal, which spawns an instance of the system-default text editor and automatically restarts espanso on exit.
|
||||
|
||||
By default it uses Nano on Unix and Notepad on Windows, but you can customize it as you like. Take a look at [Quick Editing](/docs/configuration/#quick-editing) for more information.
|
||||
|
||||
### Understanding Packages
|
||||
|
||||
Custom matches are amazing, but sometimes it can be tedious to define Matches for every **common operation**,
|
||||
Custom matches are amazing, but sometimes it can be tedious to define Matches for every common operation,
|
||||
and even more when you want to **share them with other people**.
|
||||
|
||||
espanso offers an easy way to **share and reuse matches** with other people, **packages**. In fact,
|
||||
|
|
@ -178,63 +187,29 @@ If you now type `:ook` into any text field, you should see 👍👍👍👍 appe
|
|||
|
||||
### Useful shortcuts
|
||||
|
||||
Let's conclude this introduction with the most important shortcut espanso offers, the **toggle shortcut**:
|
||||
Let's conclude this introduction with the most important shortcuts espanso offers, the **toggle shortcut** and the **backspace undo**.
|
||||
|
||||
#### Toggle Key
|
||||
|
||||
There are times when you may want to **disable espanso to avoid an unwanted expansion**. This can be
|
||||
easily accomplished by quickly **double pressing the `ALT` key** ( Option on MacOS ). You should then
|
||||
see a notification showing "Espanso disabled".
|
||||
|
||||
At this point, espanso will be disabled and will not expand any match.
|
||||
At this point, espanso will be disabled and will not expand any match. To **re-enable** it, double press the `ALT` key again.
|
||||
|
||||
To **re-enable** it, double press the `ALT` key again.
|
||||
**You can disable or change the toggle key**. Take a look at [Customizing the Toggle Key](/docs/configuration/#customizing-the-toggle-key)
|
||||
|
||||
|
||||
#### Customizing the Toggle Key
|
||||
#### Backspace Undo
|
||||
|
||||
By default, espanso can be temporarily disabled & enabled by pressing the Alt key twice, resulting in a
|
||||
notification saying "espanso disabled." Pressing Alt twice again will enable it, and you'll receive a
|
||||
notification saying "espanso enabled." This does not turn off espanso, it simply disables it until
|
||||
you enable it again.
|
||||
> This feature was introduced in version 0.7.0, so make sure to have an up-to-date version.
|
||||
|
||||
If you'd like to customize this behavior, simply add the `toggle_key` option to your previously mentioned
|
||||
`default.yml` and set it to `OFF` or one of the available options:
|
||||
It might happen to accidentally trigger an expansion, even though that was not intended. If you immediately press the `BACKSPACE` key after the expansion, the action is reverted and the trigger recovered.
|
||||
|
||||
| | | | |
|
||||
|--------------|-------------|---------------|--------------|
|
||||
| `CTRL` | `ALT` | `SHIFT` | `META` |
|
||||
| `LEFT_CTRL` | `LEFT_ALT` | `LEFT_SHIFT` | `LEFT_META` |
|
||||
| `RIGHT_CTRL` | `RIGHT_ALT` | `RIGHT_SHIFT` | `RIGHT_META` |
|
||||
You can also disable this behavior by adding the following line on your `default.yml` file:
|
||||
|
||||
|
||||
Using the above example `default.yml`, if I wanted to make it so espanso is disabled/enabled when I press
|
||||
the left control key twice, I add `toggle_key: LEFT_CTRL` to the file like so, and then, pressing
|
||||
the left control key twice disables/enables espanso.
|
||||
|
||||
```yml
|
||||
# espanso configuration file
|
||||
|
||||
# This is the default configuration file, change it as you like it
|
||||
# You can refer to the official documentation:
|
||||
# https://espanso.org/docs/
|
||||
toggle_key: LEFT_CTRL
|
||||
|
||||
# Matches are the substitution rules, when you type the "trigger" string
|
||||
# it gets replaced by the "replace" string.
|
||||
matches:
|
||||
# Simple text replacement
|
||||
- trigger: ":espanso"
|
||||
replace: "Hi there!"
|
||||
|
||||
- trigger: ":br"
|
||||
replace: "Best Regards,\nJon Snow"
|
||||
|
||||
...
|
||||
```yaml
|
||||
undo_backspace: false
|
||||
```
|
||||
|
||||
And if you'd rather it not be possible to disable it on accident, just turn it off like so:
|
||||
|
||||
```yml
|
||||
toggle_key: OFF
|
||||
```
|
||||
|
||||
After the changes are made, if you used `espanso edit` it will automatically restart. If not, issue a `espanso restart` and you'll be ready to go!
|
||||
> Note that backspace undo is not available for every match, namely the ones that specify a [Cursor Hint](/docs/matches/#cursor-hints)
|
||||
173
docs/matches.md
173
docs/matches.md
|
|
@ -48,8 +48,6 @@ There are a number of characters that are special (or reserved) and cannot be us
|
|||
|
||||
These kind of expansions are simple text replacements and are *static*.
|
||||
|
||||
> Special thanks to [@muhlinux](https://github.com/muhlinux) for the help with this section.
|
||||
|
||||
### Dynamic Matches
|
||||
|
||||
Static matches are suitable for many tasks, but can be problematic when we need an **expansion that changes dynamically**. For those situations, espanso introduces the concepts of **variables** and **extensions**.
|
||||
|
|
@ -138,10 +136,12 @@ global_vars:
|
|||
|
||||
At this point, you can use `global1` and `greet` in all your matches:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":hello"
|
||||
replace: "{{greet}} Jon"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
And typing `:hello` will result in `Hey Jon`.
|
||||
|
||||
|
|
@ -173,7 +173,7 @@ If you now type `:div`, you get the `<div></div>` expansion, with the cursor bet
|
|||
|
||||
#### Things to keep in mind
|
||||
|
||||
* You can only define **one cursor hint** per match. Multiple hints will be ignored.
|
||||
* You can only define **one cursor hint** per match. Multiple hints will be ignored. If you need multiple hints, a decent replacement would be to use [Forms](/docs/forms/)
|
||||
* This feature should be used with care in **multiline** expansions, as it may yield
|
||||
**unexpected results** when using it in code editors that support **auto indenting**.
|
||||
This is due to the way the feature is implemented: espanso simulates a series of `left arrow`
|
||||
|
|
@ -314,6 +314,16 @@ Introduced in version 0.5.0, *nested matches* allow to include the output of a m
|
|||
|
||||
At this point, if you type `:nested` you'll see `This is a nested match appear`.
|
||||
|
||||
### Forms
|
||||
|
||||
Since version 0.7.0, espanso is capable of creating arbirarly complex input forms.
|
||||
|
||||
|
||||
|
||||
These open up a world of possibilities, allowing the user to create matches with many arguments, as well as injecting those values into custom Scripts or Shell commands.
|
||||
|
||||
For more informations, visit the [Forms section](/docs/forms/).
|
||||
|
||||
### Script Extension
|
||||
|
||||
There will be tasks for which espanso was not designed for. For those cases, espanso offers the
|
||||
|
|
@ -350,16 +360,45 @@ If you now try to type `:pyscript` anywhere, you should see `Hello from python`
|
|||
|
||||
You can do the same thing with any programming language, just change the `args` array accordingly.
|
||||
|
||||
#### Script Placement
|
||||
|
||||
The current best-practice when creating Script matches is to create a `scripts` directory in the `espanso` 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:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
- trigger: ":pyscript"
|
||||
replace: "{{output}}"
|
||||
vars:
|
||||
- name: output
|
||||
type: script
|
||||
params:
|
||||
args:
|
||||
- python
|
||||
- "%CONFIG%/scripts/script.py"
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This makes it easier to create matches that work across many machines.
|
||||
|
||||
#### A note on 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, look at the [Advanced topics](#advanced-topics) section.
|
||||
|
||||
### Shell Extension
|
||||
|
||||
The **Shell Extension** is similar to the [Script Extension](#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.
|
||||
`bash` shell (and thanks to 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](https://www.ipify.org/).
|
||||
|
|
@ -381,15 +420,38 @@ IP from [ipify](https://www.ipify.org/).
|
|||
As always, restart espanso with `espanso restart`. Now everytime you type `:ip`, it gets expanded to your public
|
||||
IP address!
|
||||
|
||||
#### For macOS users
|
||||
#### Choosing the Shell
|
||||
|
||||
On macOS the shell extension does not read the `PATH` env variable (because it is managed by `launchd`). Therefore, **you need to specify the full path for the commands you are using**. For example, if you are using `jq`, you should write `/usr/local/bin/jq` instead.
|
||||
The shell extension supports many different shells out of the box. By default it uses:
|
||||
|
||||
This will probably change in the future.
|
||||
* `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:
|
||||
|
||||
{% raw %}
|
||||
```yml
|
||||
- trigger: ":ip"
|
||||
replace: "{{output}}"
|
||||
vars:
|
||||
- name: output
|
||||
type: shell
|
||||
params:
|
||||
cmd: "curl 'https://api.ipify.org'"
|
||||
shell: wsl
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
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, such as:
|
||||
This extension also supports bash **pipes** as your shell does, such as:
|
||||
|
||||
{% raw %}
|
||||
```yml
|
||||
|
|
@ -421,6 +483,36 @@ excess spaces/newlines. You can optionally disable the `trim` option:
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
#### 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, look at the [Advanced topics](#advanced-topics) section.
|
||||
|
||||
#### Using Linux commands on Windows
|
||||
|
||||
As you might have already understood from previous sections, espanso supports the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) 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:
|
||||
|
||||
{% raw %}
|
||||
```yml
|
||||
- trigger: ":localip"
|
||||
replace: "{{output}}"
|
||||
vars:
|
||||
- name: output
|
||||
type: shell
|
||||
params:
|
||||
cmd: "ip a | grep 'inet 192' | awk '{ print $2 }'"
|
||||
debug: true
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
At this point, after triggering a match, the logs will be populated with useful information. Too see them, use the `espanso log` command.
|
||||
|
||||
### Date Extension
|
||||
|
||||
The **Date Extension** can be used to include *date* and *time* information in a match.
|
||||
|
|
@ -486,3 +578,68 @@ see the following replacement appear:
|
|||
```
|
||||
<a href='YOUR_COPIED_LINK'></a>
|
||||
```
|
||||
|
||||
### Advanced Topics
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
- 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:
|
||||
|
||||
1. Variable `mytime` is evaluated first (as it's the first declared in the `vars` list).
|
||||
2. It's output is injected in the `myshell` shell command, in particular through the `$ESPANSO_MYTIME` env variable.
|
||||
3. The result is piped through the unix `rev` command
|
||||
4. Finally the output is included in the `replace` 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:
|
||||
|
||||
```yaml
|
||||
# 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`.
|
||||
|
|
@ -112,10 +112,6 @@ allowed)
|
|||
#### Publishing on espanso hub
|
||||
|
||||
After following all these steps, you can request to publish your package to [espanso hub](http://hub.espanso.org)
|
||||
by opening an [Issue](https://github.com/federico-terzi/espanso-hub/issues) with the following format:
|
||||
* Title: 'New package - <package name>'
|
||||
* Body:
|
||||
* The package **repository** url
|
||||
* A short description of your package
|
||||
* List of replacements and optionally, their descriptions
|
||||
* Requirements/Dependencies, if any
|
||||
by opening an [Issue](https://github.com/federico-terzi/espanso-hub/issues) with the following information:
|
||||
|
||||
* The repository **url**
|
||||
|
|
@ -11,7 +11,7 @@ have many problems making it work on others.
|
|||
|
||||
#### Wayland support
|
||||
|
||||
Currently espanso supports X11 systems only.
|
||||
Currently espanso supports X11 systems only, but future support for Wayland is being investigated. Follow [this issue](https://github.com/federico-terzi/espanso/issues/287) to stay updated.
|
||||
|
||||
### Installing on Ubuntu / Debian
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ If you now type `:espanso` in any text field, you should see "Hi there!" appear!
|
|||
|
||||
> **Note**: after executing the previous command, espanso will prompt the user to register a Systemd service. This is needed to automatically start espanso at system startup.
|
||||
|
||||
At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
|
||||
At this point, you should [install `modulo`](#installing-modulo) to enable the GUI features.
|
||||
|
||||
#### Installing using DEB package
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ If you now type `:espanso` in any text field, you should see "Hi there!" appear!
|
|||
|
||||
> **Note**: after executing the previous command, espanso will prompt the user to register a Systemd service. This is needed to automatically start espanso at system startup.
|
||||
|
||||
At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
|
||||
At this point, you should [install `modulo`](#installing-modulo) to enable the GUI features.
|
||||
|
||||
#### Manual installation
|
||||
|
||||
|
|
@ -109,7 +109,7 @@ If you now type `:espanso` in any text field, you should see "Hi there!" appear!
|
|||
|
||||
> **Note**: after executing the previous command, espanso will prompt the user to register a Systemd service. This is needed to automatically start espanso at system startup.
|
||||
|
||||
At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
|
||||
At this point, you should [install `modulo`](#installing-modulo) to enable the GUI features.
|
||||
|
||||
### Installing on Manjaro / Arch
|
||||
|
||||
|
|
@ -141,7 +141,7 @@ If you now type `:espanso` in any text field, you should see "Hi there!" appear!
|
|||
|
||||
> **Note**: after executing the previous command, espanso will prompt the user to register a Systemd service. This is needed to automatically start espanso at system startup.
|
||||
|
||||
At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
|
||||
At this point, you should [install `modulo`](#installing-modulo) to enable the GUI features.
|
||||
|
||||
#### Installing from the prebuilt release
|
||||
|
||||
|
|
@ -178,4 +178,25 @@ If you now type `:espanso` in any text field, you should see "Hi there!" appear!
|
|||
|
||||
> **Note**: after executing the previous command, espanso will prompt the user to register a Systemd service. This is needed to automatically start espanso at system startup.
|
||||
|
||||
At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
|
||||
At this point, you should [install `modulo`](#installing-modulo) to enable the GUI features.
|
||||
|
||||
### Installing Modulo
|
||||
|
||||
Since version 0.7.0, espanso introduced a few gui-related features that require [modulo](https://github.com/federico-terzi/modulo) to be installed in your system. **While not strictly required, it's highly suggested to install it enable some very useful features, such as Forms.**.
|
||||
|
||||
Installing modulo is pretty straight forward, being it packaged as an AppImage. Here's the list of suggested steps:
|
||||
|
||||
```bash
|
||||
# Download the latest Modulo AppImage in the $HOME/opt
|
||||
wget https://github.com/federico-terzi/modulo/releases/latest/download/modulo-x86_64.AppImage -O $HOME/opt/modulo.AppImage
|
||||
|
||||
# Make it executable:
|
||||
chmod u+x $HOME/opt/modulo.AppImage
|
||||
|
||||
# Create a link to make modulo available as "modulo"
|
||||
sudo ln -s $HOME/opt/modulo.AppImage /usr/bin/modulo
|
||||
```
|
||||
|
||||
Note that these steps can be changed in many ways, the only requirement is that the modulo binary is available as `modulo` in the PATH.
|
||||
|
||||
At this point, you are ready to read the [Getting Started](/docs/get-started/) tutorial.
|
||||
|
|
@ -61,6 +61,8 @@ To make sure that espanso was correctly installed, you can open a terminal and t
|
|||
espanso --version
|
||||
```
|
||||
|
||||
**Important:** Some of the most recent espanso features require also `modulo`, so make sure to follow the installation instructions from the [modulo docs](https://github.com/federico-terzi/modulo#macos).
|
||||
|
||||
At this point, you have to [Enable Accessibility](#enabling-accessibility) to use espanso.
|
||||
|
||||
### Enabling Accessibility
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user