PLUGIN: Log Writer v1.0

[fjeronimo]

Hello everybody,

It's been a long time and I'm not sure anybody remembers me. I won't dwell into details about my long absence, suffice to say I'm glad to be back and I hope to stay for a long time. Besides, I never forgot about AGS and this great community. And since it's customary for long time absentees to offer a gift, here's my contribution: A new plugin. I hope you enjoy it.

The plugin is a log writer implementation for AGS.

Download here (Thanks Neole!)
(Mirrors wanted)

The first thing we should cover is the definition of logging. Logging is a
systematic method of recording information, usually to a storage device like
an hard drive, that should be, in our specific case:

   * Simple, requiring minimal effort to enter information.
   * Traceable, requiring minimal effort to understand.
   * Maintainable, requiring minimal effort to change information when
        a game is modified.

Logging is usually associated with debugging, which is the process of locating
and correcting errors in a computer program code. Indeed, inserting log
statements in your code is a low-tech, albeit effective, method of debugging.
However useful, debugging is far from being the only utility of logging as more
creative uses can be thought of. For instance, you could use it to keep track
of the actions of the main character and make that available during gameplay.
Or, you could use it to store vital information and statistical data. Or, to
trace the flow of normal game execution or even to form the basis of a
scripting system. It's all up to you.

Logging equips you with detailed context for game failures. On the other hand,
testing provides quality assurance and confidence in the game. Logging and
testing should not be confused. They are complementary. When logging is wisely
used, it can prove to be an essential tool.

This plugin offers a few features, commonly available in logging packages
like log4j, that help in the logging process:

   * Hierarchical level - Log statements with lower priority than
        currently active base level are ignored.
   * Buffered output - Possibility to store several log entries in memory
        before saving them to disk.
   * Formatted output - Possibility to format log entries, like
        AGS functions Display and StrFormat.
   * Enriched output - Possibility to prepend log entries with data, like
        for instance the current time and date, the logging level or a
        user-defined prefix.
   * Multiple loggers - Creates, deletes, modifies and manages a list of logger
        objects, each associated with a log file.
   * Data control - Possibility to append or overwrite existing data.
   * Flexibility - Each function has several different versions
        available, which can affect the currently active logger or one
        referenced by a supplied id or name, or even all existing loggers.
   * Control - Possibility to enable/disable any given logger.

An example of a log file might look like this (taken from the example in the readme.txt file):

---- Log Started ----
This line has no options on. Only plain text
[ 23.27.01 ] WARN -- This is a common prefix -- This same log entry will appear differently in the two loggers
[ 2003.11.08 23.27.01 ] ERROR -- This is a common prefix -- Logged by Id (log 1)
[ 2003.11.08 23.27.01 ] FATAL -- This is a common prefix -- Logged by Name (log 1)
[ 2003.11.08 23.27.01 ] INFO -- This is a common prefix -- This should appear in both logs
[ 2003.11.08 23.27.01 ] INFO -- This is a common prefix -- This should display logger 2' name('my_logger2.txt'): my_logger2.txt
[ 2003.11.08 23.27.01 ] DEBUG -- This is a common prefix -- Active logger id (should be 2): 2
[ 2003.11.08 23.27.01 ] DEBUG -- This is a common prefix -- Active logger name (should be 'my_logger2.txt'): my_logger2.txt
[ 2003.11.08 23.27.01 ] DEBUG -- This is a common prefix -- Number of used buffer lines in logger 1 (should be 2): 2
[ 2003.11.08 23.27.01 ] INFO -- This is a common prefix -- Should print value -4 (LOG_NOT_FOUND): -4
---- Log Stopped ----

For more information, be sure to check the enclosed readme.txt

Although simple in design, this plugin was by far the longest one to complete, mostly due to the sheer number of available functions (62!). Documentation was particularly "painful" (66 pages). So, any feedback/comments/criticism is more than welcome. 

Sorry for the long post

fjeronimo

[Pumaman]

Good to see you back

Nice work with the plugin

[fjeronimo]

Thanks Chris. I'm glad to be back.

By the way, has anybody tried the plugin? Is it working as expected?

fjeronimo

[Scorpiorus]

Ok, I played with it and it's realy cool I must say. I haven't found any bugs btw. I like the formatted output feature. It's cool AGS functions supports a variable number of arguments.