New Plugin - Log Writer V1.00

[fjeronimo]

Note - This is a cross-post. I did it because I think this might interest everybody.

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. It has been added to the AGS plugin page (http://www.agsforums.com/games.php?category=21) or you
can get it directly from my site at (http://mega.ist.utl.pt/~fjds/programming.html)

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.  

fjeronimo

[After]

Another excellent extension.
Sophisticated game design becomes even more accessible. Thanks.

[fjeronimo]

It's been my pleasure After.

Have you or anybody else tried the plugin yet? I wanted to make sure everything is working as expected...

fjeronimo

[After]

Not yet, I must admit. I'm still at the stage of ensuring that I (a) use the AGS core effectively, and (b) finish something.

I don't really have a rich enough code base down to put it through its paces yet anyway.

I understand its potential, but I must resist the temptation to overreach.
Although my next game ...  :

[TerranRich]

Awesome!

Isn't this already in the Tech forum?

Yes? It IS?

Well, then, I must do this, sorry!