-

Writing a Basic Eggdrop Module

+

Writing a Basic Eggdrop Module

An Eggdrop module is a piece of C code that can be loaded (or unloaded) onto the core Eggdrop code. A module differs from a Tcl script in that modules must be compiled and then loaded, whereas scripts can be edited and loaded directly. Importantly, a module can be written to create new Eggdrop-specific Tcl commands and binds that a user can then use in a Tcl script. For example, the server module loaded by Eggdrop is what creates the “jump” Tcl command, which causes tells the Eggdrop to jump to the next server in its server list.

There are a few required functions a module must perform in order to properly work with Eggdrop

-

Module Header

+

Module Header

A module should include license information. This tells other open source users how they are allowed to use the code. Eggdrop uses GPL 2.0 licensing, and our license information looks like this:

/*
 * This program is free software; you can redistribute it and/or
@@ -130,7 +130,7 @@ 
Module Header
-
Required Code

+
Required Code

 
For this section, you don’t necessarily need to understand what it is doing, but this code is required for a module to function. If you want to learn more about this, check out How to Write an Eggdrop Module

 
You’ll next want to name your module:

 
#define MODULE_NAME "woobie"
@@ -200,7 +200,7 @@ 
Required Code
-
Adding a Partyline Command

+
Adding a Partyline Command

 
A partyline command function accepts three arguments- a pointer to the user record of the user that called the command; the idx the user was on when calling the command; and a pointer to the arguments appended to the command. A command should immediately log that it was called to the LOG_CMDS log level, and then run its desired code. This simple example prints “WOOBIE” to the partyline idx of the user that called it:

 
static int cmd_woobie(struct userrec *u, int idx, char *par)
 {
@@ -221,7 +221,7 @@ 
Adding a Partyline Command
-
Adding a Tcl Command

+
Adding a Tcl Command

 
Eggdrop uses the Tcl C API library to interact with the Tcl interpreter. Learning this API is outside the scope of this tutorial, but this example Tcl command will echo the provided argument:

 
static int tcl_echome STDVAR {
   BADARGS(2, 2, " arg");
@@ -234,10 +234,9 @@ 
Adding a Tcl Commandreturn TCL_ERROR;
   }
 }
-
-A few notes on this example. BADARGS is a macro that checks the input provided to the Tcl command. The first argument BADARGS accepts is the minimum number of parameters the Tcl command must accept (including the command itself). The second argument is the maximum number of parameters that BADARGS will accept. The third argument is the help text that will be displayed if these boundaries are exceeded. For example, BADARGS(2, 4, " name ?date? ?place?") requires at least one argument to be passed, and a maximum of three arguments. Eggdrop code style is to enclose optional arguments between qusetion marks in the help text.
 

 

+
A few notes on this example. BADARGS is a macro that checks the input provided to the Tcl command. The first argument BADARGS accepts is the minimum number of parameters the Tcl command must accept (including the command itself). The second argument is the maximum number of parameters that BADARGS will accept. The third argument is the help text that will be displayed if these boundaries are exceeded. For example, BADARGS(2, 4, “ name ?date? ?place?”) requires at least one argument to be passed, and a maximum of three arguments. Eggdrop code style is to enclose optional arguments between qusetion marks in the help text.

 
Similar to adding a partyline command, you also have to create a function table for a new Tcl command:

 
static tcl_cmds mytcl[] = {
   {"echome",           tcl_echome},
@@ -248,7 +247,7 @@ 
Adding a Tcl CommandAnd now the newly-created Tcl command ‘echome’ is available for use in a script!
-

Adding a Tcl Bind

+

Adding a Tcl Bind

A Tcl bind is a command that is activated when a certain condition is met. With Eggdrop, these are usually linked to receiving messages or other IRC events. To create a bind, you must first register the bind type with Eggdrop when the module is loaded (you added the woobie_start() and woobie_close functions earlier, you still need all that earlier code in here as well):

static p_tcl_bind_list H_woob;
 
@@ -271,7 +270,7 @@ 
Adding a Tcl Bind
-
Defining bind arguments

+
Defining bind arguments

 
The following code example defines a bind that will take two arguments:

 
static int woobie_2char STDVAR
 {
@@ -301,8 +300,8 @@ 
Defining bind argumentsLike before, BADARGS still checks that the number of arguments passed is correct, and outputs help text if it is not. The rest is boilerplate code to pass the arguments when the bind is called.
-

Calling the Bind

-

To call the bind, Eggdrop coding style it to name that function “check_tcl_bindname”. So here, whenever we reach a point in code that should trigger the bind, we’ll call check_tcl_woobie() and pass the arguments we defined- in this case, two arguments that woobie_2char was created to handle. Here is some sample code:

+

Calling the Bind

+

To call the bind, Eggdrop coding style is to name that function “check_tcl_bindname”. So here, whenever we reach a point in code that should trigger the bind, we’ll call check_tcl_woobie() and pass the arguments we defined- in this case, two arguments that woobie_2char was created to handle. Here is some sample code:

check_tcl_woobie(chan, nick);
 
 
@@ -321,11 +320,84 @@ 
Calling the Bind
+
Bind Configuration Settings

+
The last argument to check_tcl_bind sets additional configurations for the bind, these are the defined values:

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Value
Description
MATCH_PARTIAL
Check the triggering value against the beginning of the bind mask, ie DIR triggers a mask for DIRECTORY (case insensitive)
MATCH_EXACT
Check the triggering value exactly against the bind mask value (case insensitive)
MATCH_CASE
Check the triggering value exactly against the bind mask value (case sensitive)
MATCH_MASK
Check if the bind mask is contained within the triggering value, as a wildcarded value
MATCH_MODE
Check if the triggering value is contained within the bind mask, as a wildcarded value
MATCH_CRON
Check the triggering value against a bind mask formatted as a cron entry, ie “30 7 6 7 * “ triggers a mask for “30 7 * * * “
BIND_USE_ATTR
Check the flags of the user match the flags required to trigger the bind
BIND_STACKABLE
Allow multiple binds to call the same Tcl proc
BIND_WANTRET
With stacked binds, if the called Tcl proc called returns a ‘1’, halt processing any further binds triggered by the action
BIND_STACKRET
Used with BIND_WANTRET; allow stacked binds to continue despite receiving a ‘1’
BIND_ALTER_ARGS
Replaces arguments (which ones?) with the result returned from the called Tcl proc

+
The value returned by the bind is often matched against a desired value to return a ‘1’ (often used with BIND_WANTRET and BIND_STACKRET) to the calling function.

+
+
+

Bind Return Values

+ + + + + + + + + + + + + + + + + + + + + + + + +

Value

Description

BIND_NOMATCH

The bind was not triggered due to not meeting the criteria set for the bind

BIND_AMBIGUOUS

The bind was ambiguous, similar to this explanation

BIND_MATCHED

The bind criteria was met, but the Tcl proc it tried to call could not be found

BIND_EXECUTED

The bind criteria was met and the Tcl proc was called

BIND_EXEC_LOG

The bind criteria was met, the Tcl proc was called, and Eggdrop logged the bind being called

BIND_QUIT

The bind was triggered in conjunction with the target leaving the partyline or filesys area (?)

+
-

Exporting the Bind

+

Exporting the Bind

Do we need to do this?

@@ -356,9 +428,9 @@

Exporting the Bind