debuglog 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4 @@
1
+ debug.log
2
+ xyz.txt
3
+ tags
4
+ *.gem
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source "http://rubygems.org"
2
+
3
+ # Specify your gem's dependencies in col.gemspec
4
+ gemspec
@@ -0,0 +1,8 @@
1
+ === 1.0.1 / 2023-01-06
2
+
3
+ * Fixed bugs in `trace`
4
+ * Improved documentation and project management (Bundler)
5
+
6
+ === 1.0.0 / 2012-01-03
7
+
8
+ * First release (not yet announced)
data/LICENCE ADDED
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2005 Gavin Sinclair (gsinclair@gmail.com)
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in
11
+ all copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19
+ THE SOFTWARE.
@@ -0,0 +1,47 @@
1
+ debuglog: zero-conf debug.log file for simple and hassle-free debugging
2
+
3
+
4
+ = SYNOPSIS
5
+
6
+ Debuglog gives you debug, trace and time methods that write their output to the
7
+ file ./debug.log.
8
+
9
+ require 'debuglog' # or require 'debuglog/auto'
10
+
11
+ debug "Creating #{n} connections"
12
+ trace "names.first", binding
13
+ time('Process config file') { Subsystem.configure(ARGV.shift) }
14
+
15
+ The log file (default ./debug.log) will look something like this:
16
+
17
+ DebugLog -- 2011-12-28 18:58:22 +1000
18
+ -------------------------------------
19
+ [00.3] Creating 14 connections
20
+ [00.8] names.first == "Sandy White"
21
+ [01.9] Process config file: 1.0831 sec
22
+
23
+ The [00.3] etc. is the number of seconds (rounded) since the program started
24
+ (well, since require 'debuglog', anyway).
25
+
26
+ You can use different method names (to avoid a clash) and a different filename
27
+ with some initial configuration.
28
+
29
+ require 'debuglog/manual'
30
+
31
+ DebugLog.configure(
32
+ :debug => :my_debug,
33
+ :trace => :my_trace,
34
+ :time => :my_time,
35
+ :filename => 'log/xyz.log'
36
+ )
37
+
38
+ my_debug "Creating #{n} connections"
39
+ my_trace "names.first", binding
40
+ my_time('Process config file') { Subsystem.configure(ARGV.shift) }
41
+
42
+
43
+ = HOMEPAGE
44
+
45
+ See http://gsinclair.github.com/debuglog.html for full details.
46
+
47
+ MIT Licence
@@ -0,0 +1 @@
1
+ require "bundler/gem_tasks"
@@ -0,0 +1,11 @@
1
+ * Get it working in 1.8.7
2
+ - one failing test at the moment
3
+ * See if it works in 1.8.6
4
+ - Whitestone doesn't work in 1.8.6 (and never will) so I can only test
5
+ it by tring it
6
+
7
+
8
+ Future features
9
+
10
+ * Colour, whether directly (:red, etc.) or indirectly (traces are yellow,
11
+ timings are cyan, strings with !! are red, ...)
@@ -0,0 +1,29 @@
1
+ # -*- encoding: utf-8 -*-
2
+ $:.push File.expand_path("../lib", __FILE__)
3
+ require "debuglog/version"
4
+
5
+ Gem::Specification.new do |s|
6
+ s.name = "debuglog"
7
+ s.version = DebugLog::VERSION
8
+ s.authors = ["Gavin Sinclair"]
9
+ s.email = ["gsinclair@gmail.com"]
10
+ s.homepage = "http://gsinclair.github.com/debuglog.html"
11
+ s.summary = "Zero-conf debug.log file with 'debug', 'trace' and 'time' methods"
12
+ s.description = <<-EOF
13
+ require 'debuglog' and record debugging information (including variable traces
14
+ and timing information) to the file debug.log -- cheap and easy.
15
+ EOF
16
+
17
+ s.rubyforge_project = ""
18
+ s.has_rdoc = false
19
+
20
+ s.files = `git ls-files`.split("\n")
21
+ s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
22
+ s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
23
+ s.require_paths = ["lib"]
24
+
25
+ s.add_development_dependency "bundler"
26
+ s.add_development_dependency "whitestone"
27
+
28
+ s.required_ruby_version = '>= 1.8.6' # Tested.
29
+ end
@@ -1,262 +1,278 @@
1
- ---
2
- layout: default
3
- title: Debuglog
4
- ---
5
-
6
- # Debuglog -- a zero-conf debug.log file
7
-
8
- **Status: awaiting release (July 2010)**
9
-
10
- * This will be replaced by a table of contents
11
- {:toc}
12
-
13
-
14
- ## Synopsis
15
-
16
- Debuglog gives you `debug`, `trace` and `time` methods that write their output
17
- to the file `./debug.log`.
18
-
19
- {% highlight ruby %}
20
-
21
- require 'debuglog' # or require 'debuglog/auto'
22
-
23
- debug "Message..."
24
- trace :x, binding
25
- time('Task') { action }
26
-
27
- {% endhighlight %}
28
-
29
- You can change the names of the methods and the filename.
30
-
31
- {% highlight ruby %}
32
-
33
- require 'debuglog/manual'
34
-
35
- DebugLog.configure(
36
- :debug => :my_debug,
37
- :trace => :my_trace,
38
- :time => :my_time,
39
- :filename => 'log/xyz.log'
40
- )
41
-
42
- my_debug "Message..."
43
- my_trace :x, binding
44
- my_time('Task') { action }
45
-
46
- {% endhighlight %}
47
-
48
- In either case, the log file will look something like this:
49
-
50
- DebugLog -- 2010-07-25 18:58:22 +1000
51
- -------------------------------------
52
- [00.3] Message...
53
- [00.5] x == 5
54
- [00.6] Task: 1.0831 sec
55
-
56
- The `[00.3]` etc. is the number of seconds (rounded) since the program started
57
- (well, since `require 'debuglog'`, anyway).
58
-
59
- More nuanced configuration is possible; see [Configuration](#Configuration).
60
-
61
- ### Installation
62
-
63
- $ [sudo] gem install debuglog
64
-
65
- Source code is hosted on Github. See [Project details](#project_details).
66
-
67
-
68
- ## Description
69
-
70
- Debuglog allows you easy access to a log file named `debug.log` in the current
71
- directory. In that file, you can record:
72
- * arbitrary messages with `debug`
73
- * the value of variables with `trace`
74
- * the time taken to execute some code with `time`
75
-
76
- Of course, any or all of those methods names might be used by another library or
77
- by your own code. You can choose different method names and a different
78
- filename; see [Configuration](#Configuration). Debuglog will raise an
79
- exception (`DebugLog::Error`) if it detects a method clash.
80
-
81
- ### `debug`
82
-
83
- The `debug` method is straightforward. It calls `to_s` on its argument(s) and
84
- writes them to the log file.
85
-
86
- [col]: http://gsinclair.github.com/col.html
87
-
88
- ### `trace`
89
-
90
- `trace` requires you to pass the binding with the `binding` method. The two
91
- following lines are equivalent:
92
-
93
- {% highlight ruby %}
94
-
95
- trace :radius, binding
96
- debug "radius == #{radius.pretty_inspect}"
97
-
98
- {% endhighlight %}
99
-
100
- > Tip: You may choose to `alias _b binding` for convenience; DebugLog doesn't do that
101
- > for you.
102
-
103
- If you want the output truncated, pass an integer argument:
104
-
105
- {% highlight ruby %}
106
-
107
- trace :text, binding, 30
108
-
109
- {% endhighlight %}
110
-
111
- ### `time`
112
-
113
- `time` calculates the amount of time taken to execute the code in the block
114
- given and records it in the log file.
115
-
116
- {% highlight ruby %}
117
-
118
- time("Process configuration file") { @options = parse_config }
119
-
120
- {% endhighlight %}
121
-
122
- It requires a single string (`#to_s`) argument and a block.
123
-
124
- ### Notes
125
-
126
- `Debuglog` is a synonym for `DebugLog`, so you don't have to trouble yourself to
127
- remember the capitalisation.
128
-
129
- The text written to the log file has some nice touches:
130
- * Multi-line output is indented correctly.
131
- * `-------` is inserted each time an extra second of running time has elapsed.
132
- This gives you a quick visual indication of how much logfile activity is
133
- taking place. If more than one second has elapsed since the last log item,
134
- something like `------- (3 sec)` is emitted.
135
-
136
-
137
- ## Configuration
138
-
139
- The [Synopsis](#synopsis) gave a good example of configuration:
140
-
141
- {% highlight ruby %}
142
-
143
- require 'debuglog/manual'
144
-
145
- DebugLog.configure(
146
- :debug => :my_debug,
147
- :trace => :my_trace,
148
- :time => :my_time,
149
- :filename => 'log/xyz.log'
150
- )
151
-
152
- {% endhighlight %}
153
-
154
- This changes the names of the methods that Debuglog defines. The motivation for
155
- that, of course, is another library or your own code defining methods of those
156
- names. Debuglog will raise an exception (`DebugLog::Error`) if it detects a
157
- method name clash. (Of course, you might load the other library _after_
158
- Debuglog, in which case it won't detect the clash.) This precaution is taken
159
- because they are common method names at the top-level, and it's just not right
160
- for a debugging library to _cause_ bugs.
161
-
162
- If you omit a method name from the configuration, that method will not be
163
- defined. The following code defines the method `d` instead of `debug`, but does
164
- _not_ define `trace` or `time`. The standard filename `debug.log` is used.
165
-
166
- {% highlight ruby %}
167
-
168
- DebugLog.configure(
169
- :debug => :d,
170
- )
171
-
172
- {% endhighlight %}
173
-
174
- If you want to change one or two methods but leave the rest as standard, simply
175
- do:
176
-
177
- {% highlight ruby %}
178
-
179
- DebugLog.configure(
180
- :debug => :d,
181
- :trace => :trace,
182
- :time => :time
183
- )
184
-
185
- {% endhighlight %}
186
-
187
- Once you have called `DebugLog.configure`, any further calls to it will be
188
- ignored with a message on STDERR. That includes this case:
189
-
190
- {% highlight ruby %}
191
-
192
- require 'debuglog' # should be 'debuglog/manual'
193
-
194
- DebugLog.configure(...)
195
-
196
- {% endhighlight %}
197
-
198
- The code `require 'debuglog` is equivalent to the following code, meaning
199
- your one shot at calling `configure` has been taken.
200
-
201
- {% highlight ruby %}
202
-
203
- require 'debuglog/manual'
204
-
205
- DebugLog.configure(
206
- :debug => :debug,
207
- :trace => :trace,
208
- :time => :time,
209
- :file => 'debug.log'
210
- )
211
-
212
- {% endhighlight %}
213
-
214
- Final note: if you specify a file that is not writable, an error
215
- (`DebugLog::Error`) will be raised.
216
-
217
-
218
- ## Endnotes
219
-
220
- ### Motivation
221
-
222
- Debugging to a log file is very useful, even if your program doesn't do
223
- "logging" as such. Ages ago I released `dev-utils/debug` which did this and
224
- intended to do more. That's outdated now, only working on 1.8, so a revisit was
225
- worthwhile with a better name. (If anyone wants the old name for something
226
- else, they're welcome to it.)
227
-
228
- ### Dependencies and requirements
229
-
230
- Debuglog does not depend on any other libraries and works in Ruby 1.8 and Ruby
231
- 1.9.
232
-
233
- Unit tests are implemented in [Attest](http://gsinclair.github.com/attest.html).
234
-
235
- ### Project details
236
-
237
- * Author: Gavin Sinclair (user name: `gsinclair`; mail server: `gmail.com`)
238
- * Date: July 2010
239
- * Licence: MIT licence
240
- * Project homepage: [http://gsinclair.github.com/debuglog.html][home]
241
- * Source code: [http://github.com/gsinclair/debuglog][code]
242
- * Documentation: (project homepage)
243
-
244
- [home]: http://gsinclair.github.com/debuglog.html
245
- [code]: http://github.com/gsinclair/debuglog
246
-
247
- ### Possible future enhancements
248
-
249
- Color. For instance, `debug "!! Object pool overloaded"` could print the
250
- message (minus the exclamation marks) in red. Traces could be in yellow. Times
251
- could be in dark cyan, etc.
252
-
253
- Further to the above: symbol arguments to `debug` could provide some color
254
- using the `Col` library. E.g. `debug "blah...", :yb` for yellow bold.
255
-
256
- Method to turn it off and on: `DebugLog.off` and `DebugLog.on` or something.
257
-
258
- Indenting via `DebugLog.indent` and `DebugLog.outdent`.
259
-
260
- Options for `trace` output: `p` for `:inspect`; `y` for `:to_yaml` etc. I
261
- don't see why the current `:pretty_inspect` would ever be insufficient, but of
262
- course there may be cases.
1
+ ---
2
+ layout: default
3
+ title: Debuglog
4
+ ---
5
+
6
+ # Debuglog -- a zero-conf debug.log file
7
+
8
+ * This will be replaced by a table of contents
9
+ {:toc}
10
+
11
+
12
+ ## Synopsis
13
+
14
+ Debuglog gives you `debug`, `trace` and `time` methods that write their output
15
+ to the file `./debug.log`.
16
+
17
+ {% highlight ruby %}
18
+
19
+ require 'debuglog' # or require 'debuglog/auto'
20
+
21
+ debug "Creating #{n} connections"
22
+ trace "names.first", binding
23
+ time('Process config file') { Subsystem.configure(ARGV.shift) }
24
+
25
+ {% endhighlight %}
26
+
27
+ The log file (default `./debug.log`) will look something like this:
28
+
29
+ DebugLog -- 2011-12-28 18:58:22 +1000
30
+ -------------------------------------
31
+ [00.3] Creating 14 connections
32
+ [00.8] names.first == "Sandy White"
33
+ [01.9] Process config file: 1.0831 sec
34
+
35
+ The `[00.3]` etc. is the number of seconds (rounded) since the program started
36
+ (well, since `require 'debuglog'`, anyway).
37
+
38
+ You can use different method names (to avoid a clash) and a different filename
39
+ with some initial configuration.
40
+
41
+ {% highlight ruby %}
42
+
43
+ require 'debuglog/manual'
44
+
45
+ DebugLog.configure(
46
+ :debug => :my_debug,
47
+ :trace => :my_trace,
48
+ :time => :my_time,
49
+ :filename => 'log/xyz.log'
50
+ )
51
+
52
+ my_debug "Creating #{n} connections"
53
+ my_trace "names.first", binding
54
+ my_time('Process config file') { Subsystem.configure(ARGV.shift) }
55
+
56
+ {% endhighlight %}
57
+
58
+ More nuanced configuration is possible; see [Configuration](#Configuration).
59
+
60
+ ### Installation
61
+
62
+ $ [sudo] gem install debuglog
63
+
64
+ Source code is hosted on Github. See [Project details](#project_details).
65
+
66
+
67
+ ## Description
68
+
69
+ Debuglog allows you easy access to a log file named `debug.log` in the current
70
+ directory. In that file, you can record:
71
+ * arbitrary messages with `debug`
72
+ * the value of variables with `trace`
73
+ * the time taken to execute some code with `time`
74
+
75
+ Of course, any or all of those methods names might be used by another library or
76
+ by your own code. You can choose different method names and a different
77
+ filename; see [Configuration](#Configuration). Debuglog will raise an
78
+ exception (`DebugLog::Error`) if it detects a method clash.
79
+
80
+ ### `debug`
81
+
82
+ The `debug` method is straightforward. It calls `to_s` on its argument(s) and
83
+ writes them to the log file.
84
+
85
+ [col]: http://gsinclair.github.com/col.html
86
+
87
+ ### `trace`
88
+
89
+ `trace` emits the value of an expression. You are required to pass the binding with the `binding` method.
90
+
91
+ The two following lines are equivalent:
92
+
93
+ {% highlight ruby %}
94
+
95
+ trace :radius, binding
96
+ debug "radius == #{radius.pretty_inspect}"
97
+
98
+ {% endhighlight %}
99
+
100
+ > Tip: You may choose to `alias _b binding` for convenience; DebugLog doesn't do that
101
+ > for you.
102
+
103
+ If you want the output truncated, pass an integer argument:
104
+
105
+ {% highlight ruby %}
106
+
107
+ trace :text, binding, 30
108
+
109
+ {% endhighlight %}
110
+
111
+ The above examples use a symbol to trace a variable. You can, however, pass in
112
+ any expression:
113
+
114
+ {% highlight ruby %}
115
+
116
+ trace "names.find { |n| n.length > 7 }", binding
117
+
118
+ {% endhighlight %}
119
+
120
+ ### `time`
121
+
122
+ `time` calculates the amount of time taken to execute the code in the block
123
+ given and records it in the log file.
124
+
125
+ {% highlight ruby %}
126
+
127
+ time("Process configuration file") { @options = parse_config }
128
+
129
+ {% endhighlight %}
130
+
131
+ It requires a single string (`#to_s`) argument and a block.
132
+
133
+ ### Notes
134
+
135
+ `Debuglog` is a synonym for `DebugLog`, so you don't have to trouble yourself to
136
+ remember the capitalisation.
137
+
138
+ The text written to the log file has some nice touches:
139
+ * Multi-line output is indented correctly.
140
+ * `-------` is inserted each time an extra second of running time has elapsed.
141
+ This gives you a quick visual indication of how much logfile activity is
142
+ taking place. If more than one second has elapsed since the last log item,
143
+ something like `------- (3 sec)` is emitted.
144
+
145
+
146
+ ## Configuration
147
+
148
+ The [Synopsis](#synopsis) gave a good example of configuration:
149
+
150
+ {% highlight ruby %}
151
+
152
+ require 'debuglog/manual'
153
+
154
+ DebugLog.configure(
155
+ :debug => :my_debug,
156
+ :trace => :my_trace,
157
+ :time => :my_time,
158
+ :filename => 'log/xyz.log'
159
+ )
160
+
161
+ {% endhighlight %}
162
+
163
+ This changes the names of the methods that Debuglog defines. The motivation for
164
+ that, of course, is to avoid a name clash with another library or your own code.
165
+ Debuglog will raise an exception (`DebugLog::Error`) if it detects a method name
166
+ clash. (Of course, you might load the other library _after_ Debuglog, in which
167
+ case it won't detect the clash.) This precaution is taken because they are
168
+ common method names at the top-level, and it's just not right for a debugging
169
+ library to _cause_ bugs.
170
+
171
+ If you omit a method name from the configuration, that method will not be
172
+ defined. The following code defines the method `d` instead of `debug`, but does
173
+ _not_ define `trace` or `time`. The standard filename `debug.log` is used.
174
+
175
+ {% highlight ruby %}
176
+
177
+ DebugLog.configure(
178
+ :debug => :d,
179
+ )
180
+
181
+ {% endhighlight %}
182
+
183
+ If you want to change one or two methods but leave the rest as standard, simply
184
+ do:
185
+
186
+ {% highlight ruby %}
187
+
188
+ DebugLog.configure(
189
+ :debug => :d,
190
+ :trace => :trace,
191
+ :time => :time
192
+ )
193
+
194
+ {% endhighlight %}
195
+
196
+ Once you have called `DebugLog.configure`, any further calls to it will be
197
+ ignored with a message on STDERR. That includes this case:
198
+
199
+ {% highlight ruby %}
200
+
201
+ require 'debuglog' # should be 'debuglog/manual'
202
+
203
+ DebugLog.configure(...)
204
+
205
+ {% endhighlight %}
206
+
207
+ The code `require 'debuglog'` is equivalent to the following code, meaning
208
+ your one shot at calling `configure` has been taken.
209
+
210
+ {% highlight ruby %}
211
+
212
+ require 'debuglog/manual'
213
+
214
+ DebugLog.configure(
215
+ :debug => :debug,
216
+ :trace => :trace,
217
+ :time => :time,
218
+ :file => 'debug.log'
219
+ )
220
+
221
+ {% endhighlight %}
222
+
223
+ Final note: if you specify a file that is not writable, an error
224
+ (`DebugLog::Error`) will be raised.
225
+
226
+
227
+ ## Endnotes
228
+
229
+ ### Motivation
230
+
231
+ Debugging to a log file is very useful, even if your program doesn't do
232
+ "logging" as such. Years ago I released `dev-utils/debug` which did this and
233
+ intended to do more. That's outdated now, only working on 1.8, so a revisit was
234
+ worthwhile with a better name. (If anyone wants the name `dev-utils` for
235
+ something else, they're welcome to it.)
236
+
237
+ ### Dependencies and requirements
238
+
239
+ Debuglog does not depend on any other libraries. It is tested on Ruby versions
240
+ 1.8.\[67] and 1.9.\[123]. It should continue to work on future 1.9 releases.
241
+
242
+ Unit tests are implemented in [Whitestone](http://gsinclair.github.com/whitestone.html).
243
+
244
+ ### Project details
245
+
246
+ * Author: Gavin Sinclair (user name: `gsinclair`; mail server: `gmail.com`)
247
+ * Licence: MIT licence
248
+ * Project homepage: [http://gsinclair.github.com/debuglog.html][home]
249
+ * Source code: [http://github.com/gsinclair/debuglog][code]
250
+ * Documentation: (project homepage)
251
+
252
+ [home]: http://gsinclair.github.com/debuglog.html
253
+ [code]: http://github.com/gsinclair/debuglog
254
+
255
+ ### History
256
+
257
+ * 6 JAN 2012: Version 1.0.1 released (improved documentation)
258
+ * 3 JAN 2012: Version 1.0.0 released but not announced
259
+ * JULY 2010: Implemented but not released
260
+
261
+ See History.txt for more details.
262
+
263
+ ### Possible future enhancements
264
+
265
+ Color. For instance, `debug "!! Object pool overloaded"` could print the
266
+ message (minus the exclamation marks) in red. Traces could be in yellow. Times
267
+ could be in dark cyan, etc.
268
+
269
+ Further to the above: symbol arguments to `debug` could provide some color
270
+ using the `Col` library. E.g. `debug "blah...", :yb` for yellow bold.
271
+
272
+ Method to turn it off and on: `DebugLog.off` and `DebugLog.on` or something.
273
+
274
+ Indenting via `DebugLog.indent` and `DebugLog.outdent`.
275
+
276
+ Options for `trace` output: `p` for `:inspect`; `y` for `:to_yaml` etc. I
277
+ don't see why the current `:pretty_inspect` would ever be insufficient, but of
278
+ course there may be cases.