Building a HexChat plugin with Python

HPWP.md

Building a HexChat plugin with Python

Copyright 2015 Mackan90096

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

So, you're using HexChat as your IRC Client! But, you're not quite satisfied. You want that little bit more.

What if I told you, you can get that extra as easy as ABC by making a custom plugin!

You've come to the right guide.

In this guide, I'll go through making a simple Hello World plugin.

Getting started

To get started, locate your addons folder.

On Windows, this is usually at %appdata%/HexChat/Addons

You'll have to browse around for it on OSX and Linux as I do not have these systems.

In this folder, make a new file, I'll call mine HelloWorld.py (Make sure it has the .py extension)

Open this with your favorite editor. I'm using Sublime Text 3.

In this file, add the line

# -*- coding: UTF-8 -*-

This will declare the encoding of the file as UTF-8, allowing us to use special characters.

Then we're going to import the HexChat module, allowing us to call the HexChat methods wich will handle things from cathing commands to printing messages. This is done like so:

import hexchat

When this is done, we'll need to declare the plugins name for HexChat to be able to load it properly. We do this by adding these lines:

__module_name__ = "helloworld"
__module_version__ = "1.0"
__module_description__ = "A Hello World plugin for HexChat"

Now, you might be asking what all of this means. Don't worry, I'll tell you.

The __module_name__ declares the name of the module that HexChat will use, this needs to be one word and all lowercase.

The __module_version__ declares the version of the plugin. This can only contain numbers and dots.

Lastly, the __module_description__ declares the description of the plugin. This can be any characters.

Now, we're going to catch a command wich we'll bind to hello, and then print the classical Hello, World! string.

We're going to need a function to use as a callback when we catch the command.

We'll declare it as so

def hello(word, word_eol, userdata):
	print("Hello, World!")
	return hexchat.EAT_ALL

Now, you're probably asking what all of this means again. As before, I'll tell you.

The def hello(word, word_eol, userdata): statement is as you probably know, a function.

The word, word_eol, userdata of the function is the variables the callback recieves from the command cathing. We'll worry about this later.

The print("Hello, World!") will print the string Hello, World! to your client, this won't be seen by anyone else on the network.

Lastly, return hexchat.EAT_ALL eats the callback from the IRC server. If we didn't add this, we would get the error hello :Unknown command

And, at last, we'll catch the actual command. We do this by adding the following to the end of the file

hexchat.hook_command('hello', hello, help="Prints Hello, World!")

I'll tell you what this means again.

So, the 'hello' is the command we want to catch. In this case, it's /hello.

The hello is the function to use as our callback and the help="Prints Hello, World!" is the text we wan't to print when we do /help hello

To summarize, the final result should look like this:

# -*- coding: UTF-8 -*-
import hexchat

__module_name__ = "helloworld"
__module_version__ = "1.0"
__module_description__ = "A Hello World plugin for HexChat"

def hello(word, word_eol, userdata):
	print("Hello, World!")
	return hexchat.EAT_ALL

hexchat.hook_command('hello', hello, help="Prints Hello, World!")

This concludes this guide. Feel free to experiment with other commands and other things to print.