LulzBot/API

From Botdom Wiki
Jump to: navigation, search

This page details some of the specifics of the APIs provided by lulzBot for extension developers.


Packets

Packets are passed around using an object format that makes using them relatively simple. The name of the type is dAmnPacket. Assuming you've had a packet named packet passed to your event, you can access things easily using this object. For example, the command and parameter are at packet.Command and packet.Parameter, where-as the sub-command and sub-parameter are at packet.SubCommand and packet.SubParameter. And, you guessed it, the body is simply packet.Body (which has already had tablumps parsed.)

To access arguments, you access the dictionary directly. For example, to get the "from" argument of a message packet, you would use packet.Arguments["from"].


Extension Development

Starting Point

Starting out, the base extension template is quite simple. You set the name, author, and version of the extension using an attribute above the main class (which must be named Extension):

<c>using System; using lulzbot; using lulzbot.Extensions;

// Extension Name, Author Name, Version [ExtensionInfo("Something Epic", "DivinityArcane", "1.0")] public class Extension { // Body goes here }</c>


Adding Commands

Adding commands to your extension is equally easy. To do so, you use an attribute to assign a name, description, and priv level to a method. For example:

<c>using System; using lulzbot; using lulzbot.Extensions;

// Extension Name, Author Name, Version [ExtensionInfo("Something Epic", "DivinityArcane", "1.0")] public class Extension { // Command Name, Description, Minimum Priv Level [BindCommand("epic", "Do something epic!", Privs.Guest)] public void cmd_epic(String chan, String msg, String[] args, String from) { // Do something here! } }</c>

You can use multiple attributes to assign multiple command names and descriptions to one method. Remember, however, that only one command per name may exist! You cannot use the same name more than once!

The minimum priv levels are Privs.Guest, Privs.Members, Privs.Operators, Privs.Admins, and Privs.Owner


Adding Events

Adding events to your extension is even easier. To do so, you use an attribute to an event name to a method to a method. For example:

<c>using System; using lulzbot; using lulzbot.Extensions;

// Extension Name, Author Name, Version [ExtensionInfo("Something Epic", "DivinityArcane", "1.0")] public class Extension { // Event Name [BindEvent("recv_msg")] public void evt_on_msg(dAmnPacket packet) { // Do something here! } }</c>

You can, of course, use multiple attributes to assign multiple events to a single method. When working with events, you are given the packet object instead of broken down pieces. The layout of the packet object can be found here.


Interaction

Interacting with the chats is fairly simple as well. Every extension has access to an object named LulzBot. This object has various methods that make things easier for extension developers. The methods are:

<c>public static String Trigger; public static String Username; public static String Owner;

public static void Print (String msg);

public static void Say (String chan, String msg);

public static void NPSay (String chan, String msg);

public static void Act (String chan, String msg);

public static void Join (String chan);

public static void Part (String chan);

public static void Kick (String chan, String who, String why = null);

public static void Promote (String chan, String who, String privclass = null);

public static void Demote (String chan, String who, String privclass = null);

public static void Ban (String chan, String who);

public static void UnBan (String chan, String who);

public static void Admin (String chan, String cmd);

public static void Topic (String chan, String content);

public static void Title (String chan, String content);

public static void Save (String filename, object data);

public static T Load<T> (String filename);</c>

The Save and Load methods are extensions of Storage.Save and Storage.Load, and save data to storage, or load it back out.

Aside from these, there are a few other things that may be useful for extension development.

MySQL

The bot has a built-in MySQL wrapper [albeit simple,] which can be used to access or utilize MySQL databases. The methods may be accessed by the static MySQL object, and are as such:

<c>public static MySqlConnection CreateConnection (String connection_string);

public static MySqlConnection CreateConnection (String username, String password, String database, String hostname, int port = 3306);

public static bool SelectDatabase (MySqlConnection connection, String database);

public static void CloseConnection (MySqlConnection connection);

public static bool NonQuery (MySqlConnection connection, String query);

public static List<KeyValuePair<String, Object>> Query (MySqlConnection connection, String query);</c>

One would create a connection with the CreateConnection method, and then use NonQuery or Query to access or modify data, optionally switch databases with SelectDatabase, and then close the connection with CloseConnection.


Timers

The bot provides access to a timers class, which allows extensions to utilize delayed and/or repeated events. It can be accessed using the static Timers object, and provides the following:

<c>public static int Count;

public static String Add (int delay, ElapsedEventHandler action, bool repeat = false);

public static bool Remove (String id);</c>

Using Add will return a hash string which corresponds to the timer created. This is considered the ID of the timer, and timers cannot be deleted without it. To stop a repeating timer, or stop a timer before it goes off, you would simply call Remove with the ID returned by Add.


Tools

The bot provides some useful functions using the static Tools object. The methods are as follows:

<c>// Format a channel name based on the current format. // DEPRECATED: Recommended to use FormatNamespace instead. public static String FormatChat (String channel);

// Attempt to format a namespace to the given format. Failure results in an exception // being thrown. format is of type Types.NamespaceFormat which includes the following: // Channel, Packet, Username, PrivateChat public static String FormatNamespace (String ns, NamespaceFormat format);

// Format two usernames into a private chat namespace. [pchat:whoA:whoB] public static String FormatPCNS (String who1, String who2);

// Encode all characters greated than 127 to their specific HTML entity code. public static String UnicodeString (byte[] data);

// Parse the tablumps of a message. public static String ParseTablumps (String message);

// Return the MD5 hash of the input. public static String md5 (String input);

// Return the current Unix Epoch timestamp. public static int Timestamp (bool milliseconds = false);

// Format the specified amount of seconds into a human readable string. public static String FormatTime (int seconds);

// Format the specified amount of bytes into a human readable string. public static String FormatBytes (ulong bytes, bool verbose = false);

// Write the contend to the specified file name. public static void WriteFile (String filename, String content, bool append = false);

// Basic strftime implementation. public static String strftime (String format, DateTime date);

// Overload of the above. public static String strftime (String format, int timestamp);

Overload of the above. public static String strftime (String format);

// Returns a list of the channels that the bot and user have in common, if any. public static List<String> MutualChannels (String user);

// Convert some Json to the specified type. public static T Json2Data<T> (String json);

// Convert the specified object to Json. public static String Obj2Json (object obj);

// Strip the HTML tags out of the content. public static String StripTags (String data);

// Grab the HTML of a webpage. public static String GrabPage (String url, bool strip_tags = false, bool gzip = true, String accept = null);

// Perform a regex replace on haystack, replaying "what" with "with". public static String RegexReplace (String haystack, String what, String with);</c>