Arguments

Writing new perl modules

Basics

Every perl module is file named like modulename.pm and is located in usual modules directories.
The file must contain package with exactly the same name as the module itself.
The module should be derived from ZNC::Module.

If you want to define several perl packages inside your module, you should name them as subpackages of your module package.
See Sockets section for example.

Description of the module is the return value from a sub description.
All callbacks have the same name as in C++, and have the same arguments, but with reference to self before first argument, as usually in perl.
The exception is callbacks which get vector<...> as last argument:

sub OnShutdown is used as destructor (instead of perl's DESTROY).
OnShutdown is called when the module is going to be unloaded.

If a callback returns undef, a reasonable default is substituted.
Remember that if execution comes to end of sub, last evaluated value is returned!
If a callback dies/croaks, the default value is assumed too, the behavior of what happens to arguments is undefined.
When a module callback should return CModule::EModRet, you can use values as $ZNC::CModule::CONTINUE or just $ZNC::CONTINUE.

Don't begin names of your member data fields with underscore (_) - some of them are used by modperl internally.

As you see, to get normal string from ZNC::String there's a method GetPerlStr. Since ZNC 1.7.0 it's called automatically when string is needed.
You can construct non-empty ZNC::String using an argument to new.
This constructor can get string scalars, integer scalars, float scalars.

When you implement a module hook which accepts CString&, no ZNC::String magic is needed, it just works:

Message types

Since ZNC 1.7.0.

To convert between various subclasses of CMessage, use this:

my $num_msg = $msg->As('CNumericMessage');

Module's NV

There're some issues with using std iterators from perl, so class CModule got new methods: GetNVKeys which returns list of names of all NV values of the module, and ExistsNV which checks if specified variable exists.

All sockets are instances of special classes derived from ZNC::Socket.
ZNC::Socket has all the same methods as Csock, except Connect and Listen.
Csock's reference can be found here.
To get reference to the associated module, use GetModule.
Callbacks have different names from ones of Csock, they are described later.

To create socket, use module's method CreateSocket.
First argument is the name of your socket class.
The function creates socket and calls method Init of it with the rest of arguments.
Reference to the new socket is returned.

To connect socket, use method Connect.
It gets 2 required arguments - hostname and port, and several optional named arguments:

OnReadLine - is called for every new line from socket. The line, including ending \n (or \r\n) is in argument. It's called only if you enabled this feature for the socket.

OnAccepted - is called for listening socket for every new connection. Arguments are hostname and port of remote end. The callback should return undef if you don't need the connection, or reference to new socket, which will be used for this connection.

OnShutdown - (since 0.097) destructor of the socket.

If callback On* dies/croaks, the socket is closed, but if you want to close socket, use method Close instead. If Init croaks, behavior is undefined.

Getting ZNC version

If you just want to show ZNC version to humans, usually just ZNC::CZNC::GetTag is good.