| 1 | # $Id: Topics.pm,v 1.5 1996/01/04 20:45:38 willijar Exp $ | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | Log::Topics - control flow of logging messages | ||
| 6 | |||
| 7 | =head1 SYNOPSIS | ||
| 8 | |||
| 9 | use Log::Topics qw(add_topic log_topic topics); | ||
| 10 | add_topic $topic_name,$filehandle,$overload | ||
| 11 | add_topic $topic_name,$filename,$overload | ||
| 12 | log_topic $topic_name,@messages | ||
| 13 | @topicslist=topics(); | ||
| 14 | |||
| 15 | =head1 DESCRIPTION | ||
| 16 | |||
| 17 | This package provides services for controlling the output of logging | ||
| 18 | messages from an application. Log messages are identified by named | ||
| 19 | topics, and the messages for each topic can be directed or redirected | ||
| 20 | to file handles or files. | ||
| 21 | |||
| 22 | The add_topic() function can be used to associate a named topic with a | ||
| 23 | particular file handle. If a value of 0 then logging of that | ||
| 24 | particular topic is switched off. If the file handle is not connected | ||
| 25 | to a file then it will be created and connected to a file of the same | ||
| 26 | name. add_topic() returns the name of the file handle. The third | ||
| 27 | $overload parameter, if specified and false will only set the file | ||
| 28 | handle if the specified topic is not already associated with a file | ||
| 29 | handle. | ||
| 30 | |||
| 31 | Log messages are written using the log_topic() function which takes | ||
| 32 | the topic name, and if that particular topic is enabled will print its | ||
| 33 | remaining arguments to the associated file handle. It is an error to | ||
| 34 | use a topic name that has not been declared using add_topic() first. | ||
| 35 | |||
| 36 | The topics() function returns a list of all the current registered | ||
| 37 | topics. | ||
| 38 | |||
| 39 | This package can usefully be used for controlling all the output of a | ||
| 40 | program, not just debugging and logging messages. | ||
| 41 | |||
| 42 | If you have Getopt::Regex package then the following lines of code | ||
| 43 | allow the user to control the log messages from the command | ||
| 44 | line using either '-Lname=FILE' or '-Lname FILE' syntaxes. | ||
| 45 | |||
| 46 | use Log::Topics qw(add_topic log_topic); | ||
| 47 | use Getopt::Regex qw(GetOptions); | ||
| 48 | GetOptions(\@ARGV, | ||
| 49 | ['-L(.+)=(.+)',sub { add_topic $1,$2; } ,0], | ||
| 50 | ['-L(.+)', sub { add_topic $1; $_[0]; },1]); | ||
| 51 | |||
| 52 | =head1 HISTORY | ||
| 53 | |||
| 54 | $Log: Topics.pm,v $ | ||
| 55 | Revision 1.5 1996/01/04 20:45:38 willijar | ||
| 56 | Renamed module to Log::Topics, and renamed functions to more | ||
| 57 | accurately reflect modules operation. | ||
| 58 | Added topics() function to obtain list of available topics and removed | ||
| 59 | internal hash variable from export list. | ||
| 60 | Reduced to one the hash dereference in log_topic for slight efficiency | ||
| 61 | gain. | ||
| 62 | |||
| 63 | Revision 1.4 1995/12/17 17:16:31 willijar | ||
| 64 | Fixed bug that crept in in non-overloading case of diagnose | ||
| 65 | |||
| 66 | Revision 1.3 1995/12/16 11:59:19 willijar | ||
| 67 | Removed function for reading arguments from commandline - | ||
| 68 | use Getopt::Regex instead. | ||
| 69 | Added ability to open files for undefined filehandles. | ||
| 70 | Improvements to documentation | ||
| 71 | Changed name to be closer to module guidlines. | ||
| 72 | |||
| 73 | Revision 1.2 1995/09/20 19:11:44 willijar | ||
| 74 | Added pod documentation and RCS control | ||
| 75 | |||
| 76 | =head1 TO DO | ||
| 77 | |||
| 78 | Could perhaps have the idea of groups of related topics which could be | ||
| 79 | set and changed together. Would this be useful? | ||
| 80 | |||
| 81 | =head1 BUGS | ||
| 82 | |||
| 83 | Please let me know of any bugs. | ||
| 84 | Suggestions for improvements gladly received. | ||
| 85 | |||
| 86 | =head1 AUTHOR | ||
| 87 | |||
| 88 | John A.R. Williams, <J.A.R.Williams@aston.ac.uk> | ||
| 89 | |||
| 90 | Thanks to Tim Bunce <Tim.Bunce@ig.co.uk> for helpful suggestions and comments. | ||
| 91 | |||
| 92 | =cut | ||
| 93 | |||
| 94 | require Exporter; | ||
| 95 | package Log::Topics; | ||
| 96 | @ISA=qw(Exporter); | ||
| 97 | @EXPORT_OK=qw(add_topic log_topic topics); | ||
| 98 | use Carp; | ||
| 99 | |||
| 100 | %topics={}; | ||
| 101 | |||
| 102 | sub add_topic { | ||
| 103 | my ($d,$fhandle,$overload)=@_; | ||
| 104 | if (!defined $overload) { $overload=1; } | ||
| 105 | if (defined $fhandle and ($overload or !exists($topics{$d}))) { | ||
| 106 | if (!$fhandle) { $topics{$d}=0; } | ||
| 107 | else { | ||
| 108 | if ($fhandle==1) { $fhandle=STDERR; } | ||
| 109 | if (!defined(fileno($fhandle))) { open $fhandle,">$fhandle"; } | ||
| 110 | $topics{$d}=$fhandle; | ||
| 111 | } | ||
| 112 | } | ||
| 113 | return $topics{$d}; | ||
| 114 | } | ||
| 115 | |||
| 116 | sub log_topic { | ||
| 117 | my $d=shift; | ||
| 118 | my $fhandle=$topics{$d}; | ||
| 119 | if (defined($fhandle)) { | ||
| 120 | if ($fhandle) { print {$fhandle} @_; } | ||
| 121 | } | ||
| 122 | else { | ||
| 123 | carp "Undefined Log topic $d used\n"; | ||
| 124 | } | ||
| 125 | } | ||
| 126 | |||
| 127 | sub topics { return keys(%topics); } | ||
| 128 | |||
| 129 | 1; | ||
| 130 |