Scribe - Advanced
Now that you know the basics, let's move on!
Scribe contains several internal components that you can manipulate directly if you wish to. These are the logging engine, the script engine, the utility commands, the event engine, the web page builder, the web parsing engine, and the indexer.
Note that text in this font is normal text meant to be read and understood. Text in this font is meant to be used literally as a command, value, or as source code. Text in this font is meant to be replaced with what it names, for example name should be replaced with something's name or channel should be replaced with a channel.
The logging engine allows all significant events that occur in a channel to be written to a 'raw' log file. This file must live under the logs directory. For those of you who may wish to parse the logs with your own code, the file format is discussed here.
You can activate the logging system with
a single command:
/as chan channel log on filename
This will cause Scribe to immediately begin logging that channel. You cannot issue this command unless there is already a server bot in that channel. You can stop logging with:
/as chan channel log off
This will create only the log file. It
will not create a web page to view the log file. You can create one manually
by copying a .tem file from the template directory, renaming it to a .htm file,
and adding a line at the top of it:
%_set l_file filename%
This is exactly what the web page builder would do if it had to build a web page for this log. The other as chan log commands are documented in the reference manual.
The script engine allows you create a group of as commands and have them execute as a unit. You can configure a script to be executed by a server command, and you can set the access level for the script.
To make the script engine more useful, the utility commands allow as commands to do more than just configure the server. There are utility commands to send a message to everyone on a channel, send a global notice, or send newsflashes. You can access the online help for these commands by typing: /as help util
In addition some utility commands have been added to the chan family of as commands. These include furl and flash to send a URL or newsflash to a channel.
As a contrived example, suppose you wanted
to allow the IRC command FORCE, when issued by a channel operator on
#Corp to force every Java user in the channel to go to http://www.webmaster.com,
you issue the following as commands:
script Force add
script Force set command FORCE
script Force set access @#Corp
script Force command append chan #Corp furl http://www.webmaster.com
script Force enable
The script command set is useful for creating preset groups of configuration commands to allow easier or more controlled reconfiguration of the server. You can create scripts to change the server for an event or to 'tighten up' security on the server in an emergency. You can also use scripts to allow specific groups of people to issue a limited set of configuration commands.
The event engine is used to launch scripts at preset times or intervals. An event can have a start time, a stop time, a start script, and a stop script.
Suppose you want to have a different autogreet on a channel at night. You can create an event that launches the 'night mode' and 'day mode' scripts at the appropriate times. You can do the same thing for weekends versus weekdays. You can also schedule various notices to be sent globally as desired.
To continue our contrived example, suppose
we want to force that URL on people in #Corp every hour. We can do:
event HourForce add
event HourForce set time start now
event HourForce set script start Force
event HourForce set interval hourly
event HourForce enable
Since this event has no stop script or stop time, it is instantaneous.
Scribe internally creates scripts and events to manage the log events that you create. Each log event will normally have one event and two scripts associated with it. Once you understand scripts and events, you can modify the created scripts and events to enhance Scribe's functionality.
For example, you can modify the start script that Scribe creates to change the channel bot's autogreet during the event. Or you can modify the stop script to send a channel notice telling people when the event is over. Or modify the start script to send a global newsflash letting everyone know that the event is happening.
By default, the event Scribe creates is called ScribeEvent_name. The start script is called ScribeScript1_name and the stop script is called ScribeScript2_name.
Note that events and logging events have their own namespace. A logging event called MyLog will have an associated event called ScribeEvent_MyLog. You can have events and logging events with the same name. You can also change the name of the event associated with a particular log event.
It may help to create a fairly complex log event, enable it, and then shut down the server. Look at the ConfRoom.conf file. You can see how the log interface created an event and two scripts to manage the internals of the logging.
To understand the web page log parsing engine, you must first understand the basic web parsing engine. This is documented here. It is worth spending the time to read and understand it and maybe even try a few examples until you get the hang of it. Then you'll be ready to understand how this engine has been enhanced for Scribe.