blib/lib/Log/Topics.pm untested

filter: Statementstmt 0.0% 0 / 29 Branchbran 0.0% 0 / 14 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 0.0% 0 / 5 Podpod 0.0% 0 / 3 totaltotal 0.0% 0 / 61 CC 8 SCAR 32.0
CC
8
Cov
0%
add_topic
42.0
log_topic
12.0
topics
2.0
CRAP 24.5
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