Merge pull request #3 from alex1701c/master

Add installation commands for build dependencies (huge contribution provided by alex1701c)

.gitignore

@@ -1,2 +1,7 @@
 build
 __pycache__
+.idea
+cmake-build-debug
+python/build
+python/dist
+python/KRunner_Bridge.egg-info

README.md

@@ -8,7 +8,8 @@ No more pains with ONE plugin for all.
 
 -----
 
-UPDATE: A KDE maintainer has described a way that was newly introduced in KDE 5.11, to make use of DBus to achieve this. See this post: http://blog.davidedmundson.co.uk/blog/cross-process-runners/
+UPDATE: A KDE maintainer has described a way that was newly introduced in KDE 5.11, to make use of DBus to achieve this. See this post: http://blog.davidedmundson.co.uk/blog/cross-process-runners/  
+There are also (unofficial) KDevelop templates for this: https://www.pling.com/c/1355251/
 
 ## Installation
 
@@ -17,25 +18,28 @@ Requirements:
 * Python 3.x
 * KF5 & Qt5
 
+Debian/Ubuntu:  
+`sudo apt install cmake extra-cmake-modules build-essential libkf5runner-dev libkf5textwidgets-dev qtdeclarative5-dev gettext libnotify-bin`
+
+openSUSE:  
+`sudo zypper install cmake extra-cmake-modules libQt5Widgets5 libQt5Core5 libqt5-qtlocation-devel ki18n-devel
+ktextwidgets-devel kservice-devel krunner-devel gettext-tools libnotify-tools`  
+
+Fedora:  
+`sudo dnf install cmake extra-cmake-modules kf5-ki18n-devel kf5-kservice-devel kf5-krunner-devel kf5-ktextwidgets-devel gettext libnotify`  
+
 Clone this repository to local filesystem and cd into it.
 
 ```sh
-mkdir build
-cd build
-
-cmake ..
-make
-make install
+./install.sh
 ```
 
 ## Quick Start
 
-We will try to write a basic calculator using python's eval function.
-
-Follow the installation instructions and then edit `~/.local/share/kservices5/example_calc.py`:
+By executing the installer you get a basic calculator using python's eval function at `~/.local/share/kservices5/example_calc.py`:
 
 ```python
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 import krunner_bridge
 from math import *
@@ -56,26 +60,64 @@ if __name__ == "__main__":
     krunner_bridge.exec()
 ```
 
-Append one line to `~/.local/share/kservices5/krunner_bridge.desktop`, which tells krunner bridge where to find your script.
-
-```
-echo X-KRunner-Bridge-Script-1=example_calc.py >> $HOME/.local/share/kservices5/krunner_bridge.desktop
-```
 
-Kill and restart krunner. (NOTE: It would be more debuggable to run it in terminal than using `kstart5`. All stderr output from your python script will be forwarded and displayed.) That's what it will be like when all's done:
+All stderr output from your python script will be forwarded and displayed in the console.
+That's what it will be like when it is installed:
 
 ![](preview/screenshot-1.png)
 
-For more practical examples, check out `example_search.py` and view the effects by running `./install_examples.sh`. It searches in my useful little scripts and applications, with far better fuzzy match algorithm and selection mechanism. As what shows below, when you type one more key `5` to form a query `kse5`, the 5th choice `KColorSchemeEditor` will automatically be selected.
+For more practical examples, check out `example_search.py`. It searches in my useful little scripts and applications, with far better fuzzy match algorithm and selection mechanism. As what shows below, when you type one more key `5` to form a query `kse5`, the 5th choice `KColorSchemeEditor` will automatically be selected.
 
 ![](preview/screenshot-2.png)
 
+## Configuration
+
+*Note: Whenever you change the config file KRunner has to be restarted: `kquitapp5 krunner;kstart5 krunner`*
+### Timeouts
+In the `krunner_bridge.desktop` file are already the config entries for the timeouts configured, if you want them
+to take indefinitely long, you can set the value to -1.
+
+### Simple Configuration
+You can add python3 scripts by adding `X-KRunner-Bridge-Script###=<path/to/your/script>`, 
+to the `/.local/share/kservices5/krunner_bridge.desktop` file where ### can be a number, an ID or anything unique.
+This way the script is called for init, match and run operations. This is simple but it can be far more efficient to use the config groups.
+
+### Config Groups
+With the config groups you can specify more parameters, an example entry looks like this:  
+```
+[X-KRunner-Bridge-Script-Config-3]  
+FilePath=debug_helper.sh
+LaunchCommand=bash
+MatchRegex=^hello
+Initialize=true
+Prepare=true
+Teardown=true
+RunDetached=true
+```
+In the first line with in the [] you specify the name of the group, this has to start with `X-KRunner-Bridge-Script` and has to be unique.
+Firstly you have to specify the file path, this path can be relative to `~/.local/share/kservices5/` or absolute.
+All other keys are optional.
+The `LaunchCommad` is the command that gets executed when executing the script, it defaults to `python3`.  
+The `MatchRegex` is a regular expression which determines if the match operation should be with the current query executed.  
+In this example the value is `^hello`, this means that the query has to start with `hello`, if not the script does not get called.
+By using this you can avoid a lot of unnecessary plugin executions. It defaults to `.*` which always calls the script.  
+If you want to test your regular expressions https://regex101.com/ can be very useful.
+
+The `Initialize`, `Setup` and `Teardown` keys determine which lifecycle methods should be called. The Setup and Teardown keys refer
+to the KRunner match session, for instance the setup operation gets called when a new KRunner match session is started (before text is typed).
+By default only init is enabled.
+
+The `RunDetached` key determines, if the process calling the run method should be started attached or detached,
+by default it is detached. If set to false you can set a timeout as described above.
+
 ## API
 
 * `exec()`: The entry of a script
 * `match_handler`: Register a function having parameter `query` and returning a list of `datasource` as a match handler
 * `init_handler`: Register a function having no parameter as an init handler
 * `run_handler`: Register a function having parameter `data` as a run handler
+* `setup_handler`: Register a function having no parameter as an setup handler. This function will be called when a new match session is started.
+* `teardown_handler`: Register a function having no parameter as an teardown handler. This function will be called when a match session ended.
 * `datasource`
     - Properties:
         - data: Save a dict/array/string/numeric here for later use (in run handler)
@@ -92,20 +134,30 @@ For more practical examples, check out `example_search.py` and view the effects
 ## FAQs
 
 * Q: How does it work actually?
-* A: The C++ plugin just calls python scripts throw spawning subprocess, and passes parameters like `{"operation":"query","query":"kss"}` through standard input, while the script parses this and returns the result set through standard output, formatted in JSON likewise. This mean you can write the script in any language (even bash) as long as you can parse JSON. To note that the script is called everytime there is an action (run/query/init), so make your script finished as quickly as possible, and do not keep alive in background.
+* A: The C++ plugin just calls python scripts throw spawning subprocess, and passes parameters like `{"operation":"query","query":"kss"}` through standard input, while the script parses this and returns the result set as an launch parameter, formatted in JSON likewise. This mean you can write the script in any language (even bash) as long as you can parse JSON. To note that the script is called everytime there is an action (run/query/init/setup/teardown), so make your script finished as quickly as possible, and do not keep alive in background.
 
 * Q: What if I want multiple scripts?
-* A: Just append one more line `X-KRunner-Bridge-Script###=<path/to/your/script>`, where ### can be a number, an ID or anything unique. KRunner bridge searches all properties starting with `X-KRunner-Bridge-Script` and run them one after another. Distinguish them with the category property.
+* A: Just append one more config entry (line or group), where the key anything unique.
+KRunner bridge searches all properties and groups starting with `X-KRunner-Bridge-Script`.
+
+* Q: How can I update this plugin after with the new features from https://github.com/Shihira/krunner-bridge/pull/3 ?
+* A: You should remove the python api file located at ~/.local/share/kservices5/krunner_bridge.py.
+After this you can install the new version and add the scripts to the config file.
+If you only use python scripts, they should be compatible, otherwise you have to change the json input
+from standard input to the first program argument.
+
 
 -----
 
 * Q: Is it possible to move my scripts somewhere else?
-* A: Yes. Scripts are not required to be in the services directory, for this is just a default searching path. Just specify the right path, adn remember to quote special characters.
+* A: Yes. Scripts are not required to be in the services directory, for this is just a default searching path. Just specify the right path, and remember to quote special characters.
 
 -----
 
 * Q: How can I make some cache to speed up searching?
-* A: Do initialization and slow tasks in `init`, And handle caches by your own. For example, `pickle` your data up and save them in `/tmp`. `datasource` the python class provide some method to generate results, which might be useful.
+* A: Do initialization and slow tasks in `init`, And handle caches by your own. For example, `pickle` your data up and save them in `/tmp`. `datasource` the python class provide some method to generate results, which might be useful.  
+Additionally you can use the config groups instead of a single config line to provide additional information, for instance a regular expression.
+The Configuration section explains this in detail.
 
 -----
 

debug_helper.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+# Just send the data as a notification
+notify-send $1
+
+# Display some hello world text inside of KRunner
+echo '{"result":[{"text":"Hello World", "iconName":"planetkde"}]}'

example_calc.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 import krunner_bridge
 from math import *

example_search.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 import os
 import sys

install.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# Exit immediately if something fails
+set -e
+
+cd python
+python3 setup.py install --user
+cd ..
+
+if [[ ! -d build ]]; then
+    mkdir build
+fi
+
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make -j $(nproc)
+make install
+
+cd ..
+install ./example_search.py $HOME/.local/share/kservices5
+install ./example_calc.py $HOME/.local/share/kservices5
+install ./debug_helper.sh $HOME/.local/share/kservices5
+
+kquitapp5 krunner 2> /dev/null
+kstart5 --windowclass krunner krunner > /dev/null 2>&1 &