-------------------------------------- The X-Log Library - By: Nick Cash/Odis -------------------------------------- -------- License: -------- The X-Log Library, helpping you log what you need to know :) Copyright (C) 2005 Nick Cash (admin@ew.xidus.net) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Note: A copy of the GPL license should be within the directory as gpl.txt --------- Synopsis: --------- The X-Log Library (referred to as xlib hereafter) is an attempt to spread the use of readable and useful log files. Logging can be vital in programming. Printing the value of variables, knowing when something happens, or flat out knowing that it happened can make a huge difference in the amount of time it takes to debug your application. The library sports two different but useful ways of logging information. The first way is basic. It provides a chronological output of logs by number in a text document. It will append, putting several spaces and dash's between each "new" block every time the program is run. All of your logs will be in one file. See glog() and log_it() below. The second is a little more complicated, but a bit more useful, organized, and has potential for easier analysis. It will tell the line number, function, file and message for each log entry. It will also display when the log was created, and list the time when each log was entered. They will all be put in seperate files, with an increasing numerical prefix. It is all formated in XML format. See L() below. To avoid crashes, if your log directory doesnt happen to exist, it will create it for you. Each logging function uses an ellipsis (...) to accept a variable number of arguments and slap them into your message for you, taking out the trouble of printing your own strings. -------------- Example Output -------------- Check the log directory included with this release. It should contain at least 3 files. Open any XML files in your standard browser to view them. Open the log.txt file with Notepad/Wordpad or equivilant to view it. These were generated by the program that is also located in the log directory, created just to test the library. Note: To test the crashguard, the program is modified to crash. To change that, remove the printf() that refers to a woof struct. ---------- How to use ---------- First, read the function descriptions (mainly of L(), glog(), log_it() and log_entry()) so you know what each one entails. Setting up your program to use the library is very easy. First, include xlog.h with your other includes. Second, call init_log() in your main function (main() or WinMain()). When or where doesnt really matter as long as it is called before you log anything. Thats all there is to it. You don't have to call end_log anymore, as the log is automatically completed for you. ------------------------ Whats new in version 1.3 ------------------------ The end tags are now flushed, to make sure they print before your program dies. While you could add them in by hand, or open the log and view it in text form, why bother? :P The library should be alright to directly include in C++ projects. You can now specify what you want the name of your log to be. See log_it() below. File checking now takes place whenever log_it()/glog() is called. It will ensure that the log directory exists, and the file you are trying to write within the directory. Again, see log_it(). --------------------------- What was new in version 1.2 --------------------------- Safe-XML crashguard. I originally saw this proposed on the forums at Game-Dev. When the program crashed it wouldn't finish off the ending tags, which isn't a big deal but you can get around it. In general, the ending tags are written every time a log event is written, then they are overwritten by the next log event. No more incomplete log files hopefully. I removed the global pointer to the xml log. You must open the file each time you want to use it. The filename is stored in a global string named "fname". Also new in this are the introduction of types. The types are as follows: COMMENT, UNKNOWN, ERR, WARNING, EVENT, DEBUG, MESSAGE Use them however you see fit. Basically, if you use the XSLT, you will just see different colors instead of the traditional all green. ------------------ Comming Eventually ------------------ A fix so new log files generated with log_it() start at 1 and continue in order. *nix port --------------------------------------- ---------- Functions: ---------- void log_it(char *Fname, const char *txt, ... ); This is the easy to use function. You specify the file you wish to log in (.txt will automatically append, and so will the path to the log directory) as Fname, your text as txt, and whatever arguments go with it. The ellipsis makes all of the logging functions flexible. Log_it() contains one macro, which remains intact to provide old compatibility, though it may require adding some 0's: glog( txt, s... ) Glog goes straight to "log/log.txt", which is also where log_it() will default to if Fname is null. -- Examples of using log_it()/glog(): log_it( "moo", "MOOOOO says the cow!" ); log_it( "woof", "Woof says the %s", dog ); log_it( "123", "1 + 2 + 3 = %d", (1+2+3) ); glog( "WARNING! Windows is about to crash... again!", 0 ); glog( "%d + %d = %d", 1, 1, (1+1) ); glog( "The system, is %s, the system, is %s", "down", "down" ); glog( "Whoa buddy!", 0 ); Note 1: If you want to log -outside- of the log directory, you must include the path -from- the log directory. Note 2: If you have old statements that use glog() and you are getting errors, your statements probably lack arguments. Add the comma (,) and 0 to the end (like above) and things should clear up. ----- void log_entry( char *source_file, char *function, int line, const int type, const char *message, ... ); This is the main function for the XML-style log. Everything will print nicely, and Firefox/IE will display it quite well. To avoid entering some of the variables shown, there are these macro's: L( function, linetext, s... ); LT( function, type, linetext, s... ) All you have to do is enter your function, your message and any variables you may need. This, of course, won't stop you from using log_entry flat out, but it will probably be easier to use. The L() macro defaults to the MESSAGE type, where as LT you can use any type you wish. Types are detailed earlier up in this readme. Examples: void myfun( void ) { int i = 444; L( "Myfun", "Running myfun, i = %d, i/2 = %d", i, i/2 ); } L( "Wooty", "Wooty function called", 0 ); LT( "Crashing!", ERR, "ERROR! ERROR! THE CRASHING FUNCTION IS CRASHING! %d", 1 ); log_entry( __FILE__, "Wooty", __LINE__, "Wooty function called" ); ----- void init_log( void ); This must be called once before any log_entry() functions are called. It creates the current log and opens the file handle. Anyways, if you plan on using log_entry() then you MUST put this in your initialization stuff. ----- void end_log( void ); This function will print the closing tags needed (and flush the file). It is called every time your logging is called to reflect the crash-guard. No need to worry about this one. :P ----- int exists_file( char *filen ); This checks to see if a file exists. Merely plug in the file path as filen and it returns TRUE (1) if it exists, or FALSE (0) if it doesnt. ----- int xml_fprintf( FILE *fp, const char *tag, const char *txt, short embed ); This function is quite useful. As the name would imply, this prints stuff to a file. L() calls this several times, using the global handle to the xml log, but you could easily use your own file if you wish. Here's the lowdown: FILE *fp -> the file you wish to print to const char *tag -> the tag that goes around your txt, fomat is: txt here const char *txt -> the text that will go inbetween the tag's, like "txt here" above. short embed -> this determines the number of spaces before the beginning tag, essentially the indentation so the format is ok. Max of 50. The number you put in is the number it will use. L() uses 8. --------------------------------------- -------- Defines: -------- If they arent defined, it will define TRUE and FALSE. ---------- Log Types: ---------- COMMENT, UNKNOWN, ERR, WARNING, EVENT, DEBUG, MESSAGE --------------------------------------- The X-Log Library was happily developed in Dev-C++ v4.9.9.2 --------------------------------------- I hope this library is useful for you, it is not overly complicated, just an include and a link and you're on your way. May you log in peace. Don't drink and code! :P Please send any bugs, comments, praise, or improvements to my e-mail! ~Nick Cash/Odis Web : http://ew.xidus.net Email: admin@ew.xidus.net Last Modified: Wednesday, October 19th, 2005