File: scripting.rst

package info (click to toggle)
copyq 3.7.3-1~bpo9+1
  • links: PTS, VCS
  • area: main
  • in suites: stretch-backports
  • size: 10,480 kB
  • sloc: cpp: 51,894; sh: 734; python: 211; xml: 57; makefile: 34
file content (73 lines) | stat: -rw-r--r-- 2,417 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
Scripting
=========

If you need to process items in some non-trivial way you can take
advantage of the scripting interface the application provides. This is
accessible on command line as ``copyq eval SCRIPT`` or
``copyq -e SCRIPT`` where ``SCRIPT`` is string containing commands
written in JavaScript-similar scripting language (Qt Script is
ECMAScript scripting language, currently equivalent to ES5).

Every command line option is available as function in the scripting
interface. Command ``copyq help tab`` can be written as
``copyq eval 'print(help("tab"))'`` (note: ``print`` is needed to print
the return value of ``help("tab")`` function call).

Searching Items
---------------

You can print each item with ``copyq read N`` where N is item number
from 0 to ``copyq size`` (i.e. number of items in the first tab) and put
item to clipboard with ``copyq select N``. With these commands it's
possible to search items and copy the right one with a script. E.g.
having file ``script.js`` containing

::

    var match = "MATCH-THIS";
    var i = 0;
    while (i < size() && str(read(i)).indexOf(match) === -1)
        ++i;
    select(i);

and passing it to CopyQ using ``cat script.js | copyq eval -`` will put
first item containing "MATCH-THIS" string to clipboard.

Working with Tabs
-----------------

By default commands and functions work with items in the first tab.
Calling ``read(0, 1, 2)`` will read first three items from the first
tab. To access items in other tab you need to switch the current tab
with ``tab("TAB_NAME")`` (or ``copyq tab TAB_NAME`` on command line)
where ``TAB_NAME`` is name of the tab.

For example to search for an item as in the previous script but in all
tabs you'll have to run:

::

    var match = "MATCH-THIS";
    var tabs = tab();
    for (var i in tabs) {
        tab(tabs[i]);
        var j = 0;
        while (j < size() && str(read(j)).indexOf(match) === -1)
            ++j;
        if (j < size())
            print("Match in tab \"" + tabs[i] + "\" item number " + j + ".\n");
    }

Scripting Functions
-------------------

As mentioned above, all command line options are also available for
scripting e.g.: ``show()``, ``hide()``, ``toggle()``, ``copy()``,
``paste()``.

Reference for available scripting functions can be found at
:ref:`scripting-api`.

Other supported functions can be found at `ECMAScript
Reference <http://doc.qt.io/qt-5/ecmascript.html>`__.