
::: airc++
::: a modular script for mIRC
::: by Kamek and tabo


(if your name isn't tabo or Kamek, please don't write modules for airc++ yet. Lots of things may change and you'll have to rewrite your code and you'll blame us, please don't write modules yet. Thanks)


Part I: Scripting Conventions used for airc++
---------------------------------------------


*** File extensions
Currently the used extensions are:
- .amd : Modules
- .ams : Module section


*** Modules
A module is a file with the extension ".amd". It has a structure that wil be defined later. The module "id" must be the same as the module filename (without the .amd). A module name can only contain letters and numbers. The number in the module name must not be used as a version indicator.


*** Versions
The versions of the engine, and of the core modules will be of the format ymmdd[.#] New York time.
For example, something released today (January 5, 2002) should have a version of "20105". If we release a new version during the day, the version would be "20105.1", then "20105.2" and so on...
Using this system we can know exactly the day we released something, we can safely use the "<>" operators and the version is "short", only 5 characters, with 7 chars in very rare ocassions (we should _never_ release 2 versions of the same thing in one day)


*** Functions
Commands and identifiers will be called "functions".
Functions can be named only using letters, numbers and the '_' character, a function's name can't start with a number.
The '^' prefix for functions is reserved for themes.
There are 3 types of functions:
- User functions: These functions will be used by the final user, there is no special naming conventions for this kind of functions but the module writer should use descriptive names. Maybe we will need a "shortcut" module for very short aliases like /b ?
- Internal functions: These functions will be used only by it's module, should be declared as local aliases. Must be named as "module_function".
- Exported functions: These are functions that are "exported" for other modules. Must be named as "module_function", unless they are very commonly used, like the functions in stdlib.amd. In that case the function should be named "_function". We need to discuss this.


*** Groups
The "ini" section of the .amd file must be inside a group called #aircmodule so mirc won't try to "parse" it. More about this later.
Module groups must use the #module_groupname convention.


*** Variables
Will we use variables?
Anyway, if a module wants to use a variable it must use the %module_varname convention


*** Timers, dialogs, hash tables, hidden custom windows and future mIRC's additions that use names
"module_thingname"


*** Flags
The internal engine options will use "flags" since they are flexible and easy to understand. The engine-specific flags will use lowercase chars (a-z) and the script-specific flags will use uppercase chars (A-Z). This is _not_ for modules,  modules can use their own methods to do stuff, this is for the engine and engine hacks.



Part II: airc++ Modules
-----------------------


All the functions in airc++ will be in modules. A module is a file with a .amd extension. A .amd file is an ini file with module directives and _can_ have code in it, when it happens, the file has a header and a body. The header is in ini format and is inside a group called #aircmodule, the body of the module contains the code. A sample airc++ module would be:

---------------------------
#aircmodule off
[module]
; module section
;
; id, the internal "id" of the module, MUST be the same as the .amd file name
id=theme
; name, a descriptive name of the module _without_ the version
name=Theme module
; version, the version of the module, must be a number so the engine can use the <> operators
version=11204
; aircver, airc++ engine version needed (don't know if this is necesary)
aircver=11204
; author, the author of the module
author=khaled_the_moo_freak
; helpcmd, the general help command of the module (if any)
helpcmd=
; helpfile, we need to talk about this, i was thinking about something like this:
;   "helpfile=+m basichelp somefile.dat" means that the helpfile needs the module (+m) basichelp.
;   "helpfile=+f sos.hlp" means that the help file just needs a "/run <file> [topic]"
;   (.hlp, .htm, .txt, etc)
helpfile=
; setup, the command used for setting options in the module
setup=
; onload, execute this line after the module is succesfully loaded
onload=
; reqfiles, required external files (.dat, .ico, etc)
reqfiles=
; reqmods, required modules, format: "reqmods=mod1/1 mod2/2 mod3/3"
;   this means that the module requires mod1 version 1 or higher, mod2 version 2 or
;   higher and mod3 version 3 or higher.
reqmods=
; reqdlls, required dlls, using the same format as reqmods, like
; "reqdlls=mdx/0.91a aircdll/20105"
reqdlls=
; scriptfiles, load -rs these files, usually it'll be just the .amd file but more files
; can be indluded. Also, if the .amd is only an ini without code, it shouldn't be
; included here. Note that there can be modules that load nothing to remotes, don't
; know the use for this but it can be done.
scriptfiles=theme.amd theme.mrc

[unload]
; the "unload" section
;
; before trying to unload the module, call this command, if it returns a non-$null or
; non-zero, the module can't be unloaded
command=
; variables, unset all the variables that match any entry in the following list
variables=%^^* %theme_* %!loadedtheme
; windows, close all the windows that match any entry in the following list
windows=@theme_*
; dialogs, close all the dialogs that match any entry in the following list
dialogs=theme_*
; timers, kill all the timers that match any entry in the following list
timers=theme_*
; sockets, kill all the sockets that match any entry in the following list
sockets=
; hashtables, close all the hashtables that match any entry in the following list
hashtables=theme_* ^^*

[windows]
; i use this in aIRC addons to tell aIRC how to handle custom windows and i think we
; should have a cstomwin.amd module to do something similar.
; for example, in aIRC all the custom windows that are visible to the user have some
; menu entries in the lower part of their menus, entries like close, fonts, size,
; remember position, etc... the thing is that everything is handled by the script,
; not by the addon, the addon just declares something like "1=@Q_* @Query" in the
; [windows] section, which means that all the windows matching @Q_* are of @Query
; type, and then the script handles everything, also the on close event...
; We also need to discuss this.

[hooks]
; the hooks section, this is what the airc++ compiler checks when building the script
; (we all know what a hook is so there is no need to explain what they are)
; as we know, there are no normal "on event" definitions in airc++, because a big file
; may be generated merging all the modules in a single file (maybe belf forgot this again ;)
; a normal hook definition looks like "1=<hook> <priority> +[flags] <alias> [params]"
;   hook, the name of the hook, can be engine hooks (like most remotes) or module hooks:
;     module_hookname (yes, a module can declare and call hooks, for example, the
;     maintimer_hourly hook)
;   priority, the priority of this hook when compiling the event, from 01 to 99 (2 digits),
;     lower number means higher priority.
;   +flags, the options, flags are sexy
;   alias params, what is actually called when the hook is called
; now, there are two kind of hooks:
; 1 remote hooks, these are the hooks called from mirc events, for example, a compiled
;   "kick" event looks like:
;   ON ^*:KICK:#:{
;     dummy8_onkick $1-
;     dummy3_onkick $1-
;     if (!$haltdef) { theme_onkick $1- }
;   }
; 2 module hooks, these hooks are declared by a module and called by it, other modules can
;   declare hooks for it, a compiled "maintimer_hourly" looks like:
;   alias hook_maintimer_hourly {
;     somemodule_doshit
;     othermodule_blah
;   }

[settings]
; the settings section, from here a module writer can define settings that will be
; registered when the module is loaded. The settings can be modified using the
; "settings.amd" module
; a settings line looks like this:
; settings line from the [settings] section in the modules:
;   <setting> <+flags> <options|-> <updatecmd|-> <default_value|-> [desc]
;      a setting name cant start with a "-" character
;      flags: +s STRING, can be null, by default all settings are strings
;             +S STRING, but this string can't be null
;             +i INT, natural number
;             +f FLOAT, floating point number
;             +b BOOL, you can also add the +b flag to strings, ints and float settings
;                to indicate that the setting's first word is a "toggle" value (0 or 1)
;             +p positive numbers only > 0 (used with +i or +f)
;             +z number can be zero (used with +i or +f)
;             +N network specific setting
;             +C channel specific setting
;      options: in +s and +S settings, a number will indicate the max string length
;               in +i and +f settings, a n-n option like the "isnum" parameter can be given
;               if there are no options, a "-" character must be given
;      updatecmd: this command will be called when a setting is modified, parms:
;                 <setting> <+[nc]> [netw] [chan] [value]
;      default_value: the default value of the setting, must be a single word, a "-"
;                     character means that there is no default value for this setting
;                     All '_' characters will be replaced to spaces.
;      desc: a brief description of the setting
;
lagmethod +izpN  0-1 -              0    Lag checking method 0=raw, 1=ctcpreply
lagcheck  +ibzpN  -  lag_modsetting 1_10 Check lag every X seconds


[desc]
; the desc section contains a full, multiline description of the module, to be
; /loadbufed
The theme module,
blah
this is the damn theme module
; if the .amd file has code on it, the [desc] section must end in a [main] section,
; so the engine knows where the [desc] section ends and to make the merging of the
; modules faster
[main]
#aircmodule end

; this is the "code" of the module

; this alias is called when the "kick" hook is triggered, as you can see, there is no difference in the code, it's just that it is an alias now, instead of an event.
alias theme_onkick {
  echo $colour(kick) -t $chan *** $nick kicked off $chan by $knick ( $+ $1- $+ )
  haltdef
}

---------------------------

i said this would be ready for 8pm and it's 8:43pm =/
there is still shit to be done, like elaborate on flags, compilation and popups, but let's discuss the "basics" first, let's discuss this file
