jabber.space/src/content/docs/guides/plugins.md

title

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 known issue that C plugins do not currently work on Cygwin.

To install a Python plugin:

/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:

/plugins install ~/projects-git/profanity-plugins/pid/pid.so

See the /plugins command for more information on installing and enabling/disabling plugins.

If a plugin registers it's own commands, the usual /help command can be used to find out more information:

/help say

Featured Plugins

This section list some of the plugins currently available.

	Plugin	Description
ascii.py	Convert text to ascii art text and send to the current recipient or room.
browser.py	Open received links in the system default browser.
clients.py	Show client software used by each occupant in the current chat room, using xep-0092 Software Version.
imgur.py	Send a local image file or a screenshot to a recipient or chat room using imgur.com.
paste.py	Send the contents of the clipboard to the current recipient or room.
termuxnotify.py	Notifications for Termux on Android. See also notifycmd.py for a generic version to run any system command on new messages.
presence_notify.py	Configure desktop notifications for presence updates from contacts.
say.py	Read out loud messages from recipients or in chat rooms.
sounds.py	Play sounds when messages received.
syscmd.py	Display the result shell commands in a new window. Send results of shell commands to recipients or chat rooms.
wikipedia-prof.py	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 future 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

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

Themes and Settings

Plugins may make use of themes and settings by accessing the following files:

~/.local/share/profanity/plugin_themes
~/.local/share/profanity/plugin_settings

Example theme properties for syscmd.py:

[system]
command=cyan
result=green

Example settings for say.py:

[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 CProof-plugins project.

If the current API doesn't have what you need, raise an issue at the CProof repository.