110 lines
9.1 KiB
Markdown
110 lines
9.1 KiB
Markdown
---
|
|
title: Plugins
|
|
---
|
|
|
|
CProof supports plugins written in Python and C. The CProof-Plugins project includes both official plugins maintained by the CProof team and community-contributed plugins.
|
|
|
|
The master branch of the plugins repository is in sync with the latest developments on the master branch of CProof. Branching is used to maintain plugins for releases of CProof.
|
|
|
|
There is a <a href="https://github.com/profanity-im/profanity/issues/749" target="_blank" rel="noopener noreferrer">known issue</a> that C plugins do not currently work on Cygwin.
|
|
|
|
To install a Python plugin:
|
|
|
|
```bash
|
|
/plugins install ~/projects-git/profanity-plugins/say.py
|
|
```
|
|
|
|
Any module dependencies for the plugin should be on the Python system path. If a plugin imports modules relative to its location, these modules need to manually be copied to _~/.local/share/profanity/plugins/_
|
|
|
|
To install a C plugin:
|
|
|
|
```bash
|
|
/plugins install ~/projects-git/profanity-plugins/pid/pid.so
|
|
```
|
|
|
|
See the [/plugins](/command-reference#plugins) command for more information on installing and enabling/disabling plugins.
|
|
|
|
If a plugin registers it's own commands, the usual [/help](/command-reference#help) command can be used to find out more information:
|
|
|
|
```bash
|
|
/help say
|
|
```
|
|
|
|
## Featured Plugins
|
|
|
|
This section list some of the plugins currently available.
|
|
|
|
| | Plugin | Description |
|
|
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/ascii.py" target="_blank" rel="noopener noreferrer"><code>ascii.py</code></a> | Convert text to ascii art text and send to the current recipient or room. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/browser.py" target="_blank" rel="noopener noreferrer"><code>browser.py</code></a> | Open received links in the system default browser. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/clients.py" target="_blank" rel="noopener noreferrer"><code>clients.py</code></a> | Show client software used by each occupant in the current chat room, using <a href="https://xmpp.org/extensions/xep-0092.html" target="_blank" rel="noopener noreferrer">xep-0092 Software Version</a>. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/imgur.py" target="_blank" rel="noopener noreferrer"><code>imgur.py</code></a> | Send a local image file or a screenshot to a recipient or chat room using imgur.com. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/paste.py" target="_blank" rel="noopener noreferrer"><code>paste.py</code></a> | Send the contents of the clipboard to the current recipient or room. |
|
|
| <a href="https://github.com/Neo-Oli/profanity-termux-notification" target="_blank" rel="noopener noreferrer"><code>termuxnotify.py</code></a> | Notifications for Termux on Android.<br> See also <a href="https://github.com/Neo-Oli/profanity-notifycmd" target="_blank" rel="noopener noreferrer"><code>notifycmd.py</code></a> for a generic version to run any system command on new messages. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/presence_notify.py" target="_blank" rel="noopener noreferrer"><code>presence_notify.py</code></a> | Configure desktop notifications for presence updates from contacts. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/say.py" target="_blank" rel="noopener noreferrer"><code>say.py</code></a> | Read out loud messages from recipients or in chat rooms. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/sounds.py" target="_blank" rel="noopener noreferrer"><code>sounds.py</code></a> | Play sounds when messages received. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/syscmd.py" target="_blank" rel="noopener noreferrer"><code>syscmd.py</code></a> | Display the result shell commands in a new window.<br> Send results of shell commands to recipients or chat rooms. |
|
|
| <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/master/stable/wikipedia-prof.py" target="_blank" rel="noopener noreferrer"><code>wikipedia-prof.py</code></a> | Search wikipedia and show search results, pages, links etc in a new window. |
|
|
|
|
## Developing Plugins
|
|
|
|
CProof provides an API for plugins to access various functionality. Plugins may also implement 'hooks' that CProof will call on specific events.
|
|
|
|
### Python
|
|
|
|
Python plugins need to import the _prof_ module to access the API.
|
|
|
|
CProof may be compiled against Python 2 or Python 3, so plugins should be able to work with both, the <a href="https://pypi.org/project/future/" target="_blank" rel="noopener noreferrer">future</a> library can be used in most cases.
|
|
|
|
Full documentation of the _prof_ module and the hooks a plugin may implement can be found at:
|
|
|
|
[Python API documentation](/python-api-docs)
|
|
|
|
|
|
### C
|
|
|
|
C plugins need to include the _profapi.h_ header to access the API, and must be linked against _libprofanity_ using the linker flag _-lprofanity_.
|
|
|
|
C plugins should include a _Makefile_ to build a shared library (a _.so_ file) which is the file CProof will load.
|
|
|
|
Full documentation of the _profapi.h_ header and the hooks a plugin may implement can be found at:
|
|
|
|
[C API documentation](/c-api-docs)
|
|
|
|
### Themes and Settings
|
|
|
|
Plugins may make use of themes and settings by accessing the following files:
|
|
|
|
```plaintext
|
|
~/.local/share/profanity/plugin_themes
|
|
~/.local/share/profanity/plugin_settings
|
|
```
|
|
|
|
Example theme properties for <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/0.5.1/stable/syscmd.py" target="_blank" rel="noopener noreferrer">syscmd.py</a>:
|
|
|
|
```ini
|
|
[system]
|
|
command=cyan
|
|
result=green
|
|
```
|
|
|
|
Example settings for <a href="https://git.jabber.space/devs/profanity-plugins/src/branch/0.5.1/stable/say.py" target="_blank" rel="noopener noreferrer">say.py</a>:
|
|
|
|
```ini
|
|
[say]
|
|
args=-v english -s 120
|
|
enabled=active
|
|
```
|
|
|
|
API functions are available to read and write to the settings and theme files.
|
|
|
|
Plugins should contain documentation on the available settings and colours, most plugins have a command to manipulate settings.
|
|
|
|
### Contributing Plugins
|
|
|
|
Submit a pull request to the <a href="https://git.jabber.space/devs/profanity-plugins" target="_blank" rel="noopener noreferrer">CProof-plugins</a> project.
|
|
|
|
If the current API doesn't have what you need, raise an issue at the <a href="https://git.jabber.space/devs/profanity" target="_blank" rel="noopener noreferrer">CProof</a> repository.
|