Safe Haskell | Safe-Infered |
---|
- data PluginDescriptor = PluginDescriptor {}
- data XchatPlugin a
- data XChatPlugin a
- xChatPluginInit :: Ptr (XchatPlugin a) -> a -> IO (XChatPlugin a)
- xChatGetChanList :: XChatPlugin a -> IO [Chan]
- data ChanFlgs = ChanFlgs {}
- data ChanType
- = ChanServer
- | ChanChannel
- | ChanDialog
- data Chan = Chan {}
- xChatGetDccList :: XChatPlugin a -> IO [Dcc]
- data DccStatus
- = DccQueued
- | DccActive
- | DccFailed
- | DccDone
- | DccConnecting
- | DccAborted
- data DccType
- = DccSend
- | DccReceive
- | DccChatRecv
- | DccChatSend
- data Dcc = Dcc {}
- xChatGetIgnList :: XChatPlugin a -> IO [Ign]
- data IgnFlgs = IgnFlgs {}
- data Ign = Ign {}
- xChatGetNotifyList :: XChatPlugin a -> IO [Notify]
- data Notify = Notify {}
- xChatGetUserList :: XChatPlugin a -> IO [User]
- data User = User {}
- data XChatHook a b c
- data Eating = Eating {}
- type Hook a b c d = XChatPlugin a -> (d -> a -> IO (Eating, a)) -> (a -> IO (b, a)) -> IO (b, XChatHook a b c)
- data PriorityC
- data PriorityA
- abstractPriority :: PriorityC -> PriorityA
- concretePriority :: PriorityA -> PriorityC
- data Flags = Flags {}
- xChatHookCommand :: String -> PriorityA -> Maybe String -> Hook a b c String
- xChatHookServer :: String -> PriorityA -> Hook a b c String
- xChatHookPrint :: String -> PriorityA -> Hook a b c [String]
- xChatHookTimer :: Int32 -> Hook a b c ()
- xChatHookFd :: Fd -> Flags -> Hook a b c (Fd, Flags)
- xChatUnhook :: XChatPlugin a -> XChatHook a b c -> (a -> IO (c, a)) -> IO c
- data XChatContext
- xChatSetContext :: XChatPlugin a -> XChatContext -> IO Bool
- xChatFindContext :: XChatPlugin a -> Maybe String -> Maybe String -> IO XChatContext
- xChatGetContext :: XChatPlugin a -> IO XChatContext
- xChatPrint :: XChatPlugin a -> String -> IO ()
- xChatCommand :: XChatPlugin a -> String -> IO ()
- xChatNickcmp :: XChatPlugin a -> String -> String -> IO Ordering
- data SettingResult
- xChatGetPrefs :: XChatPlugin a -> String -> IO SettingResult
- xChatGetInfo :: XChatPlugin a -> String -> IO (Maybe String)
- xChatEmitPrint :: XChatPlugin a -> String -> [String] -> IO Bool
- xChatSendModes :: XChatPlugin a -> [String] -> Maybe Int32 -> Bool -> Char -> IO ()
- data StripRules = StripRules {
- noColor :: Bool
- noAttribute :: Bool
- xChatStrip :: String -> StripRules -> IO String
- xChatPluginguiAdd :: XChatPlugin a -> String -> PluginDescriptor -> IO (XChatPlugin a)
- xChatPluginguiRemove :: XChatPlugin a -> IO ()
- xChatGettext :: String -> IO String
Documentation
This is my first binding in Haskell (and in any other language btw), so I probably lack of good practice.
I tried to do bindings for the XChat plugin system, but some functions were not documented (these are tagged [Undocumented]), those function are expect to have their signature changed once they become documented (and I understand what they truly are for). For these functions, I would gladly accept some enlightment of what they really do.
For the other functions, I would also accept advice on how to improve the binding.
There are also some lacking functions:
- xChatPrintF (special case of xChatPrint)
- xChatCommandF (special case of xChatCommand)
- xChatFree (automatically called)
- all functions on lists but the xChatGetList specialized in 5 versions
To contact me: sed?rikov@gma?il.com (remove the question marks) For more information, read the README.txt file
Functions
data PluginDescriptor Source
The plugin descriptor
data XchatPlugin a Source
data XChatPlugin a Source
The type of plugins; it is associated to a memory which can be used and modified by the hooked callbacks.
All the following functions needs a
as
argument. In fact it is a handle which needs to be initialized
by the XChatPlugin
init
function, and will be freed by an optional deinit
function.
xChatPluginInit :: Ptr (XchatPlugin a) -> a -> IO (XChatPlugin a)Source
The plugin initializer. NEVER call it, it is only used by hsxchat
.
The Lists
All XChat informations are stored in lists. There are 5 lists, each of them having its own section for a further description.
To get access to such a list, you have to request it from XChat, using the provided function. There is no magic you have to get the list each time you have get informations, since it may have changed since the last time.
Channels
xChatGetChanList :: XChatPlugin a -> IO [Chan]Source
ChanFlgs | |
|
Chan | |
|
DCC
xChatGetDccList :: XChatPlugin a -> IO [Dcc]Source
Dcc | |
|
Ignore
xChatGetIgnList :: XChatPlugin a -> IO [Ign]Source
Notify
xChatGetNotifyList :: XChatPlugin a -> IO [Notify]Source
Users
xChatGetUserList :: XChatPlugin a -> IO [User]Source
The hooks system
All
s returned can be passed to XChatHook
.
This is not mandatory, as they are automatically unhooked
at unloading time. All hooks return a xChatUnhook
type.
Hook
a b c
The hook system is not exactly the one used in the original
C
/C++
library. In the original library, some memory was
attached to each hook, but that meant that shared memory
had to be done through pointers. Now all functions of
the original library are given the same plugin memory pointer,
and this memory is attached to the plugin itself,
so all hooking functions are only given a
(which internally contains a memory) and
its memory is not explicitly given anymore at hooking time.
XChatPlugin
Types
The type of hooks; it has three type arguments.
- The first is the type of the plugin memory
- The second one is the type returned at hook creation, it can be used to restore the memory at unhooking time, or to print some debugging information.
- The third one is the type returned at unhooking time, it can be used to display debugging information.
The way callbacks are managed; a callback function can be eat an event, that is make the event unprocessable, either to XChat or to the other plgins.
type Hook a b c d = XChatPlugin a -> (d -> a -> IO (Eating, a)) -> (a -> IO (b, a)) -> IO (b, XChatHook a b c)Source
The returned type of all hooking functions;
if f is a
hooking function, then:
Hook
a b c d
f ph cb init
means that a new
hook
using the callback XChatHook
a b ccb
function is
created for the ph
plugin; the hooking modifies
the a
plugin memory according to init
,
and returns the b
returned by init
as well as the
created hook.
The callback function itself is a function which takes some
d
data, the a
plugin memory at the moment when the
callback function is called and returns how the event which
triggered the callback call is eaten as well as the new
a
plugin memory.
a concrete type to define the priority of a command
an abstract type to define the priority of a command
abstractPriority :: PriorityC -> PriorityASource
to get a (normalized) abstract priority from a concrete one
concretePriority :: PriorityA -> PriorityCSource
to get a concrete priority from an abstract one
flags for file descriptors
Hooks
xChatHookCommand :: String -> PriorityA -> Maybe String -> Hook a b c StringSource
xChatHookCommand
cmd pri help
Description:
Hooking to the /cmd
input box command at priority pri
with an
optional help
message.
To capture text without a '/
' at the start (non-commands),
you may hook a special name of "" as in:
let eatAll =Eating
{eatXChat
=True
,eatPlugin
=True
} startWithYou s a =xChatPrint
p ("you: "++
s)>>
return
(eatAll, a) inxChatHookCommand
""Norm
Nothing
p startWithYou ()
which automatically adds "you:
" at the beginning of each sentence you type
(and is undocumented as the help message argument is
).
Nothing
Commands hooked that begin with a period ('.') will be hidden in
/HELP
and /HELP -l
.
Arguments:
- cmd
- The command (without the forward slash) with some special treatment if it is the empty string or if it begins with a dot
- pri
- Priority of the hook, you should probably use
Norm
- help
- Optionnal help message, displayed at
/HELP cmd
command
Callback Function Main Argument:
The callback function expects a string containing all the arguments passed to the command.
xChatHookServer :: String -> PriorityA -> Hook a b c StringSource
Description:
xChatHookServer
ev pri
Hooking to the server event ev
at priority pri
.
To capture all server events, use "RAW LINE"
.
Arguments:
- ev
- The server event to be captured
- pri
- Priority of the hook, you should probably use
Norm
Callback Function Main Argument:
The callback function expects a string containing all the arguments of the captured server event.
xChatHookPrint :: String -> PriorityA -> Hook a b c [String]Source
Description:
xChatHookPrint
prev pri
Hooking to the print event prev
at priority pri
.
Available events are those in "Advanced > Text Events" plus these ones:
"Open Context"
- Called when a new
XChatContext
is created. "Close Context"
- Called when a xchat_context pointer is closed.
"Focus Tab"
- Called when a tab is brought to front.
"Focus Window"
- Called a toplevel window is focused, or the main tab-window is focused by the window manager.
"DCC Chat Text"
- Called when some text from a DCC Chat arrives.
It provides these arguments for the callback function:
[_, Address, Port, Nick, The Message]
"Key Press"
- Called when some keys are pressed in the input-box.
It provides these arguments for the callback function:
[_, Key Value, State Bitfield (shift, capslock, alt), String version of the key, Length of the string (may be 0 for unprintable keys)]
Arguments:
- prev
- The print event to be captured
- pri
- Priority of the hook, you should probably use
Norm
Callback Function Main Argument:
The callback function expects a list of strings containing all the arguments of the captured print event.
xChatHookTimer :: Int32 -> Hook a b c ()Source
Description:
xChatHookTimeout
timeout
Hooking to call a function every timeout
milliseconds.
Arguments:
- timeout
- The time(ms) to wait before the next triggering of the callback.
Callback Function Main Argument:
The callback function expects just a unit type.
xChatHookFd :: Fd -> Flags -> Hook a b c (Fd, Flags)Source
Description:
xChatHookFd
fd flgs
Hooking to the file descriptor fd
with flags flgs
.
The callback function is called every time the file descriptor is available
to an action described by the flags.
Arguments:
- fd
- The file descriptor or socket
- flgs
- The flags of the file descriptor
Callback Function Main Argument:
The callback function expects a file descriptor and a flag (that may be removed in a newer version).
Removing hooks
xChatUnhook :: XChatPlugin a -> XChatHook a b c -> (a -> IO (c, a)) -> IO cSource
Description:
xChatUnhook
ph hook restore
Unhooking of the given hook
.
According to the xchat plugin documentation,
hooks are automatically removed at deinit time.
But you may wish for some reason to hook or unhook
dynamically some function.
There is an argument that allows you to modify the
memory at unhook time. For example, if you have a counter,
your memory could be a
. When you hook, you may want
to put it Maybe
Int
and when you unhook to put it back to Just
0
.
Nothing
Arguments:
- ph
- The plugin handle of which we want to unhook.
- hook
- The hook to remove from the plugin.
- restore
- The function to be called on the memory of the plugin.
Contexts
Contexts are mainly a tab+window pair. I do not know more as the original documentation is rather sparse on it.
You have 3 functions on contexts (find, get and set).
The
can detect opening and closing of contexts.
xChatHookPrint
data XChatContext Source
the type of contexts
xChatSetContext :: XChatPlugin a -> XChatContext -> IO BoolSource
Description:
xChatSetContext
ph ctx
Changes the current context.
Arguments:
- ph
- Plugin handle whose context is to be changed.
- ctx
- Context (given by
orxChatGetContext
).xChatFindContext
Returns:
xChatFindContext :: XChatPlugin a -> Maybe String -> Maybe String -> IO XChatContextSource
Description:
xChatFindContext
ph servname channel
Finds a context based on a channel and servername.
If servname
is
, it finds the channel (or query) by the
given name in the same server group as the current context. If that doesn't
exists then find any by the given name.
Nothing
If channel is
, it finds the front-most tab/window of the given servname.
Nothing
Arguments:
- ph
- Plugin handle.
- servname
- Servername.
- channel
- Channelname.
Returns:
Context (for use with xChatSetContext).
xChatGetContext :: XChatPlugin a -> IO XChatContextSource
Description:
xChatGetContext
ph
Get the current context.
Arguments:
- ph
- Plugin handle whose context is to be taken.
Returns:
The current context.
Some other commands
xChatPrint :: XChatPlugin a -> String -> IO ()Source
Description:
xChatPrint
ph text
Displays some text in the xchat window.
Arguments:
- ph
- The plugin handle which manages the printing.
- text
- The text to display. May contain mIRC color codes.
xChatCommand :: XChatPlugin a -> String -> IO ()Source
Description:
xChatCommand
ph cmd
Executes a command as if it were typed in xchat's input box.
Arguments:
- ph
- The plugin handle which manages the command.
- text
- The command to execute without the heading '/'.
xChatNickcmp :: XChatPlugin a -> String -> String -> IO OrderingSource
Description:
xChatNickcmp
ph s1 s2
Performs a nick name comparision, based on the current server connection. This might be a RFC1459 compliant string compare, or plain ascii (in the case of DALNet). Use this to compare channels and nicknames. The function works the same way as strcasecmp.
Quote from RFC1459:
Because of IRC's scandanavian origin, the characters {}| are considered to be the lower case equivalents of the characters []\, respectively. This is a critical issue when determining the equivalence of two nicknames.
Arguments:
- ph
- Plugin handle whose context is to be taken.
- s1
- 1st string to compare
- s2
- 2nd string to compare
Returns:
The comparison of the two strings.
data SettingResult Source
The result of a setting request
xChatGetPrefs :: XChatPlugin a -> String -> IO SettingResultSource
Description:
xChatGetPrefs
ph pref
Provides xchat's setting information (that which is available through the "/set" command). A few extra bits of information are available that don't appear in the "/set list", currently they are:
- state_cursor
- Current input-box cursor position (characters, not bytes).
- id
- Unique server id.
Arguments:
- ph
- Plugin handle.
- pref
- Setting name required.
Returns:
A failure, a
, a String
or an Bool
according to
the Int32
case.
SettingResult
xChatGetInfo :: XChatPlugin a -> String -> IO (Maybe String)Source
Description:
xChatGetInfo
ph info
Returns information based on your current context.
Arguments:
- ph
- Plugin handle.
- id
- ID of the information you want. Currently supported IDs are (case sensitive):
- [away] away reason or
if you are not away.Nothing
- [channel] current channel name.
- [charset] character-set used in the current context.
- [event_text] text event format string for name.
- [host] real hostname of the server you connected to.
- [inputbox] the input-box contents, what the user has typed.
- [libdirfs] library directory. e.g. /usr/lib/xchat. The same directory used for auto-loading plugins. This string isn't necessarily UTF-8, but local file system encoding.
- [modes] channel modes, if known, or
.Nothing
- [network] current network name or
.Nothing
- [nick] your current nick name.
- [nickserv] nickserv password for this network or
.Nothing
- [server] current server name (what the server claims to be).
if you are not connected.Nothing
- [topic] current channel topic.
- [version] xchat version number.
- [win_ptr] native window pointer. Unix: (GtkWindow *) Win32: HWND.
- [win_status] window status: "active", "hidden" or "normal".
- [xchatdir] xchat config directory, e.g.: /home/user/.xchat2 This string is encoded in UTF-8, which means you _should_ convert it to "locale" encoding before using functions like open() or OpenFile(). For best Unicode support on Linux, convert this string using g_filename_from_utf8 and on Windows convert this string to UTF-16LE (wide) and use OpenFileW() etc.
- [xchatdirfs] xchat config directory, e.g.: /home/user/.xchat2. This string is encoded in local file system encoding, making it ideal for direct use with functions like open() or OpenFile(). For real Unicode support on Windows, it's best not to use xchatdirfs, but xchatdir instead.
Returns:
A string of the requested information, or
.
Nothing
xChatEmitPrint :: XChatPlugin a -> String -> [String] -> IO BoolSource
Description:
xChatEmitPrint
ph ev args
Generates a print event.
This can be any event found in the Preferences > Advanced > Text Events window.
The args
are the arguments of the event.
Special care should be taken when calling this
function inside a print callback (from
),
as not to cause endless recursion.
xChatHookPrint
Arguments:
- ph
- Plugin handle.
- ev
- Text event to print.
- args
- Arguments of the event to print.
Returns:
in case of success True
else.
False
Example:
xChatEmitPrint
"Channel Message" ["John", "Hi there", "@"]
xChatSendModes :: XChatPlugin a -> [String] -> Maybe Int32 -> Bool -> Char -> IO ()Source
Description:
Sends a number of channel mode changes to the current channel.
For example, you can Op a whole group of people in one go.
It may send multiple MODE lines if the request doesn't fit on one.
Pass xChatSendModes
ph str_list mpl sgn mode
for mpl to use the current server's maximum possible.
This function should only be called while in a channel context.
Nothing
Arguments:
- ph
- The plugin handle
- str_list
- The targets
- mpl
- The number of modes per line
- sgn
- The sign (
True
is '+',False
is '-') - mode
- The mode char, e.g. 'o' for Ops
Example:
xChatSendModes
"Alice":"Bob":[] 3 True 'o'
xChatStrip :: String -> StripRules -> IO StringSource
Description:
xChatStrip
str rules
Strips mIRC color codes and/or text attributes (bold, underlined etc) from the given string and returns a new string. The original function had an unused plugin handle.
Arguments:
- str
- The string to strip
- rules
- The description of the plugin to add
Undocumented
xChatPluginguiAdd :: XChatPlugin a -> String -> PluginDescriptor -> IO (XChatPlugin a)Source
- Undocumented
Description:
xChatPluginguiAdd
ph filename pdesc
Add of a new GUI plugin to the list of the current plugins. Due to lack of documentation, it is not further documented. In the original source code, such added plugins are tagged 'fake'. It seems that beside their name, file name, version, description and position in the list, there is no memory allocation. Furthermore, the original code had an extra unused argument.
Arguments:
- ph
- The plugin handle to be used by default if the USE_PLUGIN directive was not given at compile time for XChat, if the USE_PLUGIN directive was provided, a new plugin handle is created, with the data of [ph] passed by
- filename
- The path name of the file containing the plugin to add
- pdesc
- The description of the plugin to add
xChatPluginguiRemove :: XChatPlugin a -> IO ()Source
- Undocumented
Description:
xChatPluginguiRemove
ph
The counterpart of
function.
So it is used to remove 'fake' plugins. Once again, one of the arguments
is unused in the original source code, so I removed it.
xChatPluginguiAdd
Arguments:
- ph
- The plugin handle to be removed
xChatGettext :: String -> IO StringSource
- Undocumented
Description:
xChatGettext
str
Converts a string to its internal XChat representation. I automatically free it to avoid memory leak, although as I don't know what it really does, it may be a bad idea. The original code had an unused plugin handle.
Arguments:
- str
- The string to convert