esplus

README

esplus

A cli helper tool for espanso.

It has three commands:

• template that allows you to use golang templates as espanso variables,
• run that allows you to run a command without waiting for it to finish (returns empty string).
• clipin that allows you to run a command with the clipboard content as input.

Installation

Dowload it from the releases page and put it in your path. Or build it yourself:

go install github.com/kpym/esplus@latest

Usage

help

When you run esplus, it displays the following help message

> esplus
esplus is a helper cli for espanso.
Version: 0.4.0
Usage: esplus <command> <args>

Commands:
    template <file> <args> : if file exists, use it as template with args (using {{ and }} as delimiters)
    template <template string> <args> : execute a template with args (using [[ and ]] as delimiters)
    run [milliseconds] <cmd> <args> : run a command (with delay) without waiting for it to finish
    clipin <cmd> <args> : run a command with the clipboard content as input

Examples:
    esplus template 'Hello [[.|upper]]' 'World'
    esplus template 'Hello [[range .]][[.|upper|printf "%s\n"]][[end]]' 'World' 'and' 'Earth'
    esplus template 'file.template.txt' 'World'
    esplus run 200 code .
    esplus clipin html2md

Project repository:
    https://github.com/kpym/esplus

template

The templates are executed with the text/template golang package. The sprig functions are available. If there is a single parameter it is passed as a string, else the parameters are passed as array of strings.

To see how go templates work, you can check hashicorp's help.

The following espanso trigger will replace !lo with the clipboard content in lowercase.

  - trigger: "!lo"
    replace: "{{output}}"
    vars:
      - name: "clipboard"
        type: "clipboard"
      - name: output
        type: script
        params:
          args:
            - esplus
            - template
            - "[[.|lower]]"
            - "{{clipboard}}"

The following espanso trigger will replace !snippet with the snippet.txt file content used as a template.

  - trigger: "!snippet"
    replace: "{{output}}"
    vars:
      - name: "ask"
        type: form
        params:
          layout: "Name [[name]], Age [[age]]"
      - name: output
        type: script
        params:
          args:
            - esplus
            - template
            - "full/path/to/snippet.txt"
            - "{{ask.name}}"
            - "{{ask.age}}"

The file snippet.txt could looks like this:

The name is {{index . 0}} and the age is {{index . 1}}.

If the file is not found, it is interpreted as a template string, so probably it will be returned as is.

run

The following espanso trigger will :

• immediately return an empty string,
• wait for 210 ms, the time for espanso to remove !edit (replace it with the empty string),
• then open the espanso config folder in vscode.

  - trigger: "!edit"
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args:
            - esplus
            - run
            - "210"
            - code
            - '%CONFIG%'

clipin

Clipin exists because there are somme issues with the clipboard content in espanso. One is the clipboard truncation, the other is related to the encoding of the clipboard content. The clipin command allows you to run a command with the clipboard content as utf-8 input.

The following espanso trigger will run the html2md command with the clipboard content as input.

  - trigger: "!html2md"
    replace: "{{output}}"
    vars:
      - name: output
        type: script
        params:
          args:
            - esplus
            - clipin
            - html2md

Configuration

The file ~/.config/esplus/config.toml (if it exists) is used to configure esplus. For now, it is only used to provide aliases to some commands. The reasons is that under MacOS espanso runs scripts with some minimal PATH, so programs that are in the path could not be found. The aliases are used to provide the full path to that programs. For example, the following config.toml file will allow to use code and subl as aliases for Visual Studio Code and Sublime Text:

[aliases]
code = "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"
subl = "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl"

Note

I hope this tool to become usless one day (see espanso#1449 and espanso#1415).

License

MIT License

Documentation

Overview

esplus is a helper cli for espanso run : esplus <command> <args>