tbd 3.2.3 → 3.3.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -29,229 +29,285 @@
29
29
  # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
30
 
31
31
  module OSlg
32
- DEBUG = 1
33
- INFO = 2
34
- WARN = 3
35
- ERROR = 4
36
- FATAL = 5
37
-
38
- @@logs = []
39
- @@level = INFO
40
- @@status = 0
41
-
42
- @@tag = []
43
- @@tag[0 ] = ""
44
- @@tag[DEBUG] = "DEBUG"
45
- @@tag[INFO ] = "INFO"
46
- @@tag[WARN ] = "WARNING"
47
- @@tag[ERROR] = "ERROR"
48
- @@tag[FATAL] = "FATAL"
49
-
50
- @@msg = []
51
- @@msg[0 ] = ""
52
- @@msg[DEBUG] = "Debugging ..."
53
- @@msg[INFO ] = "Success! No errors, no warnings"
54
- @@msg[WARN ] = "Partial success, raised non-fatal warnings"
55
- @@msg[ERROR] = "Partial success, encountered non-fatal errors"
56
- @@msg[FATAL] = "Failure, triggered fatal errors"
32
+ DEBUG = 1 # e.g. for debugging e.g. "argument String? expecting Integer"
33
+ INFO = 2 # e.g. informative e.g. "success! no errors, no warnings"
34
+ WARN = 3 # e.g. warnings e.g. "partial success, see non-fatal warnings"
35
+ ERROR = 4 # e.g. erros e.g. "partial success, see non-fatal errors"
36
+ FATAL = 5 # e.g. failures e.g. "stopping! encountered fatal errors"
37
+
38
+ # each log is a Hash with keys :level (Integer) and :message (String)
39
+ @@logs = []
40
+
41
+ # preset strings matching log levels
42
+ @@tag = [
43
+ "", # (empty string)
44
+ "DEBUG", # DEBUG
45
+ "INFO", # INFO
46
+ "WARNING", # WARNING
47
+ "ERROR", # ERROR
48
+ "FATAL" # FATAL
49
+ ].freeze
50
+
51
+ # preset strings matching log status
52
+ @@msg = [
53
+ "", # (empty string)
54
+ "Debugging ...", # DEBUG
55
+ "Success! No errors, no warnings", # INFO
56
+ "Partial success, raised non-fatal warnings", # WARNING
57
+ "Partial success, encountered non-fatal errors", # ERROR
58
+ "Failure, triggered fatal errors" # FATAL
59
+ ].freeze
60
+
61
+ @@level = INFO # initial log level
62
+ @@status = 0 # initial status
57
63
 
58
64
  ##
59
- # Return log entries.
65
+ # Returns log entries.
60
66
  #
61
- # @return [Array] current log entries
67
+ # @return [Array<Hash>] log entries (see @@logs)
62
68
  def logs
63
69
  @@logs
64
70
  end
65
71
 
66
72
  ##
67
- # Return current log level.
73
+ # Returns current log level.
68
74
  #
69
- # @return [Integer] DEBUG, INFO, WARN, ERROR or FATAL
75
+ # @return [DEBUG, INFO, WARN, ERROR, FATAL] log level
70
76
  def level
71
77
  @@level
72
78
  end
73
79
 
74
80
  ##
75
- # Return current log status.
81
+ # Returns current log status.
76
82
  #
77
- # @return [Integer] DEBUG, INFO, WARN, ERROR or FATAL
83
+ # @return [0, DEBUG, INFO, WARN, ERROR, FATAL] log status
78
84
  def status
79
85
  @@status
80
86
  end
81
87
 
82
88
  ##
83
- # Return whether current status is DEBUG
89
+ # Returns whether current status is DEBUG.
84
90
  #
85
- # @return [Bool] true if DEBUG
91
+ # @return [Bool] whether current log status is DEBUG
86
92
  def debug?
87
93
  @@status == DEBUG
88
94
  end
89
95
 
90
96
  ##
91
- # Return whether current status is INFO
97
+ # Returns whether current status is INFO.
92
98
  #
93
- # @return [Bool] true if INFO
99
+ # @return [Bool] whether current log status is INFO
94
100
  def info?
95
101
  @@status == INFO
96
102
  end
97
103
 
98
104
  ##
99
- # Return whether current status is WARN
105
+ # Returns whether current status is WARN.
100
106
  #
101
- # @return [Bool] true if WARN
107
+ # @return [Bool] whether current log status is WARN
102
108
  def warn?
103
109
  @@status == WARN
104
110
  end
105
111
 
106
112
  ##
107
- # Return whether current status is ERROR
113
+ # Returns whether current status is ERROR.
108
114
  #
109
- # @return [Bool] true if ERROR
115
+ # @return [Bool] whether current log status is ERROR
110
116
  def error?
111
117
  @@status == ERROR
112
118
  end
113
119
 
114
120
  ##
115
- # Return whether current status is FATAL
121
+ # Returns whether current status is FATAL.
116
122
  #
117
- # @return [Bool] true if FATAL
123
+ # @return [Bool] whether current log status is FATAL
118
124
  def fatal?
119
125
  @@status == FATAL
120
126
  end
121
127
 
122
128
  ##
123
- # Return string equivalent of level
129
+ # Returns preset OSlg string that matches log level.
124
130
  #
125
- # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
131
+ # @param lvl [#to_i] 0, DEBUG, INFO, WARN, ERROR or FATAL
126
132
  #
127
- # @return [String] "DEBUG", "INFO", "WARN", "ERROR" or "FATAL"
128
- def tag(level)
129
- return @@tag[level] if level >= DEBUG && level <= FATAL
133
+ # @return [String] preset OSlg tag (see @@tag)
134
+ def tag(lvl)
135
+ return "" unless lvl.respond_to?(:to_i)
136
+
137
+ lvl = lvl.to_i
138
+ return "" if lvl < DEBUG
139
+ return "" if lvl > FATAL
140
+
141
+ @@tag[lvl]
130
142
 
131
- ""
132
143
  end
133
144
 
134
145
  ##
135
- # Return preset OSlg message linked to status.
146
+ # Returns preset OSlg message that matches log status.
136
147
  #
137
- # @param status [Integer] DEBUG, INFO, WARN, ERROR or FATAL
148
+ # @param stat [Integer] 0, DEBUG, INFO, WARN, ERROR or FATAL
138
149
  #
139
- # @return [String] preset OSlg message
140
- def msg(status)
141
- return @@msg[status] if status >= DEBUG && status <= FATAL
150
+ # @return [String] preset OSlg message (see @@msg)
151
+ def msg(stat)
152
+ return "" unless stat.respond_to?(:to_i)
153
+
154
+ stat = stat.to_i
155
+ return "" if stat < DEBUG
156
+ return "" if stat > FATAL
142
157
 
143
- ""
158
+ @@msg[stat]
144
159
  end
145
160
 
146
161
  ##
147
- # Set level.
162
+ # Converts object to String and trims if necessary.
148
163
  #
149
- # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
164
+ # @param txt [#to_s] a stringable object
165
+ # @param length [#to_i] maximum return string length
150
166
  #
151
- # @return [Integer] current level
152
- def reset(level)
153
- @@level = level if level >= DEBUG && level <= FATAL
167
+ # @return [String] a trimmed message string (empty unless stringable)
168
+ def trim(txt = "", length = 60)
169
+ length = 60 unless length.respond_to?(:to_i)
170
+ length = length.to_i if length.respond_to?(:to_i)
171
+ return "" unless txt.respond_to?(:to_s)
172
+
173
+ txt = txt.to_s.strip
174
+ txt = txt[0...length] + " ..." if txt.length > length
175
+
176
+ txt
154
177
  end
155
178
 
156
179
  ##
157
- # Log new entry.
180
+ # Resets level, if lvl (input) is within accepted range.
158
181
  #
159
- # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
160
- # @param message [String] user-provided message
182
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
161
183
  #
162
- # @return [Integer] current status
163
- def log(level = DEBUG, message = "")
164
- if level >= DEBUG && level <= FATAL && level >= @@level
165
- @@logs << {level: level, message: message}
166
- @@status = level if level > @@status
167
- end
184
+ # @return [DEBUG, INFO, WARN, ERROR, FATAL] updated/current level
185
+ def reset(lvl = DEBUG)
186
+ return @@level unless lvl.respond_to?(:to_i)
168
187
 
169
- @@status
188
+ lvl = lvl.to_i
189
+ return @@level if lvl < DEBUG
190
+ return @@level if lvl > FATAL
191
+
192
+ @@level = lvl
170
193
  end
171
194
 
172
195
  ##
173
- # Log template 'invalid object' message and return user-set object.
196
+ # Logs a new entry, if provided arguments are valid.
174
197
  #
175
- # @param id [String] invalid object identifier
176
- # @param mth [String] calling method identifier
177
- # @param ord [Integer] calling method argument order number of obj (optional)
178
- # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
179
- # @param res [Object] what to return (optional)
198
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
199
+ # @param message [#to_s] user-provided log message
200
+ #
201
+ # @example A user warning
202
+ # log(WARN, "Surface area < 100cm2")
203
+ #
204
+ # @return [DEBUG, INFO, WARN, ERROR, FATAL] updated/current status
205
+ def log(lvl = DEBUG, message = "")
206
+ return @@status unless lvl.respond_to?(:to_i)
207
+ return @@status unless message.respond_to?(:to_s)
208
+
209
+ lvl = lvl.to_i
210
+ message = message.to_s
211
+ return @@status if lvl < DEBUG
212
+ return @@status if lvl > FATAL
213
+ return @@status if lvl < @@level
214
+
215
+ @@logs << {level: lvl, message: message}
216
+ return @@status unless lvl > @@status
217
+
218
+ @@status = lvl
219
+ end
220
+
221
+ ##
222
+ # Logs template 'invalid object' message, if provided arguments are valid.
180
223
  #
181
- # @return [Object] return object if specified by user
182
- # @return [Nil] nil if return object undefined
224
+ # @param id [#to_s] 'invalid object' identifier
225
+ # @param mth [#to_s] calling method identifier
226
+ # @param ord [#to_i] calling method argument order number of obj (optional)
227
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
228
+ # @param res what to return (optional)
229
+ #
230
+ # @example An invalid argument, logging a FATAL error, returning FALSE
231
+ # return invalid("area", "sum", 0, FATAL, false) if area > 1000000
232
+ #
233
+ # @return user-provided object
234
+ # @return [nil] if user hasn't provided an object to return
183
235
  def invalid(id = "", mth = "", ord = 0, lvl = DEBUG, res = nil)
184
236
  return res unless id.respond_to?(:to_s)
185
237
  return res unless mth.respond_to?(:to_s)
186
238
  return res unless ord.respond_to?(:to_i)
187
239
  return res unless lvl.respond_to?(:to_i)
188
240
 
189
- id = id.to_s.strip
190
- mth = mth.to_s.strip
191
241
  ord = ord.to_i
192
242
  lvl = lvl.to_i
193
-
194
- id = id[0...60] + " ..." if id.length > 60
243
+ id = trim(id)
244
+ mth = trim(mth)
195
245
  return res if id.empty?
196
-
197
- mth = mth[0...60] + " ..." if mth.length > 60
198
246
  return res if mth.empty?
247
+ return res if lvl < DEBUG
248
+ return res if lvl > FATAL
199
249
 
200
250
  msg = "Invalid '#{id}' "
201
251
  msg += "arg ##{ord} " if ord > 0
202
252
  msg += "(#{mth})"
203
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
253
+ log(lvl, msg)
204
254
 
205
255
  res
206
256
  end
207
257
 
208
258
  ##
209
- # Log template 'instance/class mismatch' message and return user-set object.
259
+ # Logs template 'instance/class mismatch' message, if provided arguments are
260
+ # valid. The message is not logged if the provided object to evaluate is an
261
+ # actual instance of the target class.
210
262
  #
211
- # @param id [String] mismatched object identifier
212
- # @param obj [Object] object to validate
263
+ # @param id [#to_s] mismatched object identifier
264
+ # @param obj the object to validate
213
265
  # @param cl [Class] target class
214
- # @param mth [String] calling method identifier
215
- # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
216
- # @param res [Object] what to return (optional)
266
+ # @param mth [#to_s] calling method identifier (optional)
267
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
268
+ # @param res what to return (optional)
217
269
  #
218
- # @return [Object] return object if specified by user
219
- # @return [Nil] nil if return object undefined
270
+ # @example A mismatched argument instance/class
271
+ # mismatch("area", area, Float, "sum") unless area.is_a?(Numeric)
272
+ #
273
+ # @return user-provided object
274
+ # @return [nil] if user hasn't provided an object to return
220
275
  def mismatch(id = "", obj = nil, cl = nil, mth = "", lvl = DEBUG, res = nil)
221
276
  return res unless id.respond_to?(:to_s)
277
+ return res unless mth.respond_to?(:to_s)
222
278
  return res unless cl.is_a?(Class)
223
279
  return res if obj.is_a?(cl)
224
- return res unless mth.respond_to?(:to_s)
225
280
  return res unless lvl.respond_to?(:to_i)
226
281
 
227
- mth = mth.to_s.strip
228
- id = id.to_s.strip
229
282
  lvl = lvl.to_i
230
-
231
- id = id[0...60] + " ..." if id.length > 60
283
+ id = trim(id)
284
+ mth = trim(mth)
232
285
  return res if id.empty?
233
-
234
- mth = mth[0...60] + " ..." if mth.length > 60
235
286
  return res if mth.empty?
287
+ return res if lvl < DEBUG
288
+ return res if lvl > FATAL
236
289
 
237
- msg = "'#{id}' #{obj.class}? expecting #{cl} (#{mth})"
238
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
290
+ log(lvl, "'#{id}' #{obj.class}? expecting #{cl} (#{mth})")
239
291
 
240
292
  res
241
293
  end
242
294
 
243
295
  ##
244
- # Log template 'missing hash key' message and return user-set object.
296
+ # Logs template 'missing hash key' message, if provided arguments are valid.
297
+ # The message is not logged if the provided key exists.
245
298
  #
246
- # @param id [String] Hash identifier
299
+ # @param id [#to_s] Hash identifier
247
300
  # @param hsh [Hash] hash to validate
248
- # @param key [Object] missing key
249
- # @param mth [String] calling method identifier
250
- # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
251
- # @param res [Object] what to return (optional)
301
+ # @param key missing key
302
+ # @param mth [#to_s] calling method identifier
303
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
304
+ # @param res what to return (optional)
305
+ #
306
+ # @example A missing Hash key
307
+ # hashkey("floor area", floor, :area, "sum") unless floor.key?(:area)
252
308
  #
253
- # @return [Object] return object if specified by user
254
- # @return [Nil] nil if return object undefined
309
+ # @return user-provided object
310
+ # @return [nil] if user hasn't provided an object to return
255
311
  def hashkey(id = "", hsh = {}, key = "", mth = "", lvl = DEBUG, res = nil)
256
312
  return res unless id.respond_to?(:to_s)
257
313
  return res unless hsh.is_a?(Hash)
@@ -259,121 +315,117 @@ module OSlg
259
315
  return res unless mth.respond_to?(:to_s)
260
316
  return res unless lvl.respond_to?(:to_i)
261
317
 
262
- id = id.to_s.strip
263
- mth = mth.to_s.strip
264
318
  lvl = lvl.to_i
265
-
266
- id = id[0...60] + " ..." if id.length > 60
319
+ id = trim(id)
320
+ mth = trim(mth)
267
321
  return res if id.empty?
268
-
269
- mth = mth[0...60] + " ..." if mth.length > 60
270
322
  return res if mth.empty?
323
+ return res if lvl < DEBUG
324
+ return res if lvl > FATAL
271
325
 
272
- msg = "Missing '#{key}' key in '#{id}' Hash (#{mth})"
273
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
326
+ log(lvl, "Missing '#{key}' key in '#{id}' Hash (#{mth})")
274
327
 
275
328
  res
276
329
  end
277
330
 
278
331
  ##
279
- # Log template 'empty (uninitialized)' message and return user-set object.
332
+ # Logs template 'empty' message, if provided arguments are valid.
280
333
  #
281
- # @param id [String] empty object identifier
282
- # @param mth [String] calling method identifier
283
- # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
284
- # @param res [Object] what to return (optional)
334
+ # @param id [#to_s] empty object identifier
335
+ # @param mth [#to_s] calling method identifier
336
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
337
+ # @param res what to return (optional)
285
338
  #
286
- # @return [Object] return object if specified by user
287
- # @return [Nil] nil if return object undefined
339
+ # @example An uninitialized variable, logging an ERROR, returning FALSE
340
+ # empty("zone", "conditioned?", FATAL, false) if space.thermalZone.empty?
341
+ #
342
+ # @return user-provided object
343
+ # @return [nil] if user hasn't provided an object to return
288
344
  def empty(id = "", mth = "", lvl = DEBUG, res = nil)
289
345
  return res unless id.respond_to?(:to_s)
290
346
  return res unless mth.respond_to?(:to_s)
291
347
  return res unless lvl.respond_to?(:to_i)
292
348
 
293
- id = id.to_s.strip
294
- mth = mth.to_s.strip
295
349
  lvl = lvl.to_i
296
-
297
- id = id[0...60] + " ..." if id.length > 60
350
+ id = trim(id)
351
+ mth = trim(mth)
298
352
  return res if id.empty?
299
-
300
- mth = mth[0...60] + " ..." if mth.length > 60
301
353
  return res if mth.empty?
354
+ return res if lvl < DEBUG
355
+ return res if lvl > FATAL
302
356
 
303
- msg = "Empty '#{id}' (#{mth})"
304
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
357
+ log(lvl, "Empty '#{id}' (#{mth})")
305
358
 
306
359
  res
307
360
  end
308
361
 
309
362
  ##
310
- # Log template 'near zero' message and return user-set object.
363
+ # Logs template 'zero' value message, if provided arguments are valid.
311
364
  #
312
- # @param id [String] zero object identifier
313
- # @param mth [String] calling method identifier
314
- # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
315
- # @param res [Object] what to return (optional)
365
+ # @param id [#to_s] zero object identifier
366
+ # @param mth [#to_s] calling method identifier
367
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
368
+ # @param res what to return (optional)
369
+ #
370
+ # @example A near-zero variable
371
+ # zero("floor area", "sum") if floor[:area].abs < TOL
316
372
  #
317
- # @return [Object] return object if specified by user
318
- # @return [Nil] nil if return object undefined
373
+ # @return user-provided object
374
+ # @return [nil] if user hasn't provided an object to return
319
375
  def zero(id = "", mth = "", lvl = DEBUG, res = nil)
320
376
  return res unless id.respond_to?(:to_s)
321
377
  return res unless mth.respond_to?(:to_s)
322
378
  return res unless lvl.respond_to?(:to_i)
323
379
 
324
- id = id.to_s.strip
325
- mth = mth.to_s.strip
326
380
  ord = ord.to_i
327
381
  lvl = lvl.to_i
328
-
329
- id = id[0...60] + " ..." if id.length > 60
382
+ id = trim(id)
383
+ mth = trim(mth)
330
384
  return res if id.empty?
331
-
332
- mth = mth[0...60] + " ..." if mth.length > 60
333
385
  return res if mth.empty?
386
+ return res if lvl < DEBUG
387
+ return res if lvl > FATAL
334
388
 
335
- msg = "Zero '#{id}' (#{mth})"
336
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
389
+ log(lvl, "Zero '#{id}' (#{mth})")
337
390
 
338
391
  res
339
392
  end
340
393
 
341
394
  ##
342
- # Log template 'negative' message and return user-set object.
395
+ # Logs template 'negative' message, if provided arguments are valid.
343
396
  #
344
- # @param id [String] negative object identifier
397
+ # @param id [#to_s] negative object identifier
345
398
  # @param mth [String] calling method identifier
346
399
  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
347
400
  # @param res [Object] what to return (optional)
348
401
  #
349
- # @return [Object] return object if specified by user
350
- # @return [Nil] nil if return object undefined
402
+ # @example A negative variable
403
+ # negative("floor area", "sum") if floor[:area] < 0
404
+ #
405
+ # @return user-provided object
406
+ # @return [nil] if user hasn't provided an object to return
351
407
  def negative(id = "", mth = "", lvl = DEBUG, res = nil)
352
408
  return res unless id.respond_to?(:to_s)
353
409
  return res unless mth.respond_to?(:to_s)
354
410
  return res unless lvl.respond_to?(:to_i)
355
411
 
356
- id = id.to_s.strip
357
- mth = mth.to_s.strip
358
- ord = ord.to_i
359
412
  lvl = lvl.to_i
360
-
361
- id = id[0...60] + " ..." if id.length > 60
413
+ id = trim(id)
414
+ mth = trim(mth)
362
415
  return res if id.empty?
363
-
364
- mth = mth[0...60] + " ..." if mth.length > 60
365
416
  return res if mth.empty?
417
+ return res if lvl < DEBUG
418
+ return res if lvl > FATAL
366
419
 
367
- msg = "Negative '#{id}' (#{mth})"
368
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
420
+ log(lvl, "Negative '#{id}' (#{mth})")
369
421
 
370
422
  res
371
423
  end
372
424
 
373
425
  ##
374
- # Reset log status and entries.
426
+ # Resets log status and entries.
375
427
  #
376
- # @return [Integer] current level
428
+ # @return [Integer] current log level
377
429
  def clean!
378
430
  @@status = 0
379
431
  @@logs = []