1[comment {-*- tcl -*- doctools manpage}]
2[comment {$Id: loggerUtils.man,v 1.7 2009/01/29 06:16:19 andreas_kupries Exp $}]
3[manpage_begin logger::utils n 1.3]
4[copyright {2005 Aamer Akhter <aakhter@cisco.com>}]
5[moddesc {Object Oriented logging facility}]
6[titledesc {Utilities for logger}]
7[category  {Programming tools}]
8[require Tcl 8.4]
9[require logger::utils [opt 1.3]]
10[description]
11[keywords logger appender]
12
13This package adds template based [term appenders].
14
15[list_begin definitions]
16
17[call [cmd ::logger::utils::createFormatCmd] [arg formatString]]
18
19This command translates [arg formatString] into an expandable command
20string.
21
22The following strings are the known substitutions (from log4perl)
23allowed to occur in the [arg formatString]:
24
25[list_begin definitions]
26[def %c] Category of the logging event
27[def %C] Fully qualified name of logging event
28[def %d] Current date in yyyy/MM/dd hh:mm:ss
29[def %H] Hostname
30[def %m] Message to be logged
31[def %M] Method where logging event was issued
32[def %p] Priority of logging event
33[def %P] Pid of current process
34[list_end]
35
36
37[call [cmd ::logger::utils::createLogProc] \
38	[option -procName] [arg procName] \
39	[opt [arg options]...]]
40
41This command ...
42
43[list_begin options]
44
45[opt_def -procName procName]
46
47The name of the procedure to create.
48
49[opt_def -conversionPattern pattern]
50
51See [cmd ::logger::utils::createFormatCmd] for the substitutions
52allowed in the [arg pattern].
53
54[opt_def -category category]
55
56The category (service).
57
58[opt_def -priority priority]
59
60The priority (level).
61
62[opt_def -outputChannel channel]
63
64channel to output on (default stdout)
65
66[list_end]
67
68
69[call [cmd ::logger::utils::applyAppender] \
70	[option -appender] [arg appenderType] \
71	[opt [arg options]...]]
72
73This command will create an appender for the specified logger
74services. If no service is specified then the appender will be added
75as the default appender for the specified levels. If no levels are
76specified, then all levels are assumed.
77
78[para]
79
80[list_begin options]
81
82[opt_def -service    loggerservices]
83[opt_def -serviceCmd loggerserviceCmds]
84
85Name of the logger instance to modify. [option -serviceCmd] takes as
86input the return of [cmd logger::init].
87
88[opt_def -appender appenderType]
89
90Type of the appender to use.
91One of [const console], [const colorConsole].
92
93[opt_def -conversionPattern pattern]
94
95See [cmd ::logger::utils::createFormatCmd] for the
96format of the pattern. If this option is not provided
97the default pattern
98
99	[example {[%d] [%c] [%M] [%p] %m}]
100
101is used.
102
103[opt_def -levels levelList]
104
105The list of levels to apply this appender to. If not specified all
106levels are assumed.
107
108[list_end]
109[para]
110
111Example of usage:
112
113[para]
114[example {
115   % set log [logger::init testLog]
116   ::logger::tree::testLog
117   % logger::utils::applyAppender -appender console -serviceCmd $log
118   % ${log}::error "this is an error"
119   [2005/08/22 10:14:13] [testLog] [global] [error] this is an error
120}]
121
122
123
124[call [cmd ::logger::utils::autoApplyAppender] \
125	[arg command] [arg command-string] [arg log] [arg op] [arg args]... \
126]
127
128This command is designed to be added via [cmd {trace leave}] to calls
129of [cmd logger::init]. It will look at preconfigured state (via
130[cmd ::logger::utils::applyAppender]) to autocreate appenders for
131newly created logger instances.
132
133It will return its argument [arg log].
134
135[para]
136Example of usage:
137[para]
138[example {
139  logger::utils::applyAppender -appender console
140  set log [logger::init applyAppender-3]
141  ${log}::error "this is an error"
142}]
143[list_end]
144
145[section {BUGS, IDEAS, FEEDBACK}]
146
147This document, and the package it describes, will undoubtedly contain
148bugs and other problems.
149
150Please report such in the category [emph logger] of the
151[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
152
153Please also report any ideas for enhancements you may have for either
154package and/or documentation.
155
156
157[manpage_end]
158