oslg 0.2.7 → 0.2.8

Sign up to get free protection for your applications and to get access to all the features.
Files changed (7) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/pull_request.yml +1 -81
  3. data/README.md +35 -37
  4. data/lib/oslg/oslog.rb +136 -120
  5. data/lib/oslg/version.rb +1 -1
  6. data/oslg.gemspec +2 -2
  7. metadata +5 -5
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6309b9c37cd0135fc85fd44a2903d7594ccf1b0d952f64cec3df1b7c9d5f32e9
4
- data.tar.gz: 1d4b53beb732dd9d0680f59e79e1d078f5d4d0b2289bfe3ac8f224bae3bb0ff4
3
+ metadata.gz: 56637f835e16299c31183815be32900cc972e6b15f1a68368af56d27d5b5aaaa
4
+ data.tar.gz: 3fe4cc6657e348b5b8f0d8307b93e72e1a91336baef903597ac020435c250048
5
5
  SHA512:
6
- metadata.gz: 1edc4f411a77d1aaa0e2c6d48a9847ef3239af027d4699894519a8f1286b639c4a11dbd6bc96c2ef1cec43047d0601b5d01d38f178efde2e638786e890103b5a
7
- data.tar.gz: 29899ed065067829900502b40ecd053c354a9255954bc18a1b735c30aaf1d6edab6a5c369a37af01b63e5330ef0b27cd8c4855dbecadfc352d1e5733b18f7ff0
6
+ metadata.gz: cc8332dca2148f53bda258a5f2ac302a6f9e2a2e63392c64776afedda9a3c4484e4c3ad5bf815b8d27356b3be4e568049b95cf13e903b1d0565ff9d40f46bbf5
7
+ data.tar.gz: 8bd64e2988531d00e8e15443bebecc38317aaa9d2a90fbe764efe105726ca539050832b9dd3a37536eae41c30cb8727ad0d9c9a8ab4f77679c814d66c55c91e2
data/.github/workflows/pull_request.yml CHANGED
@@ -6,87 +6,7 @@ on:
6
6
  - dev
7
7
 
8
8
  jobs:
9
- test_300x:
10
- runs-on: ubuntu-22.04
11
- steps:
12
- - name: Check out repository
13
- uses: actions/checkout@v2
14
- - name: Run Tests
15
- run: |
16
- echo $(pwd)
17
- echo $(ls)
18
- docker pull nrel/openstudio:3.0.0
19
- docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.0.0
20
- docker exec -t test pwd
21
- docker exec -t test ls
22
- docker exec -t test bundle update
23
- docker exec -t test bundle exec rake
24
- docker kill test
25
- test_321x:
26
- runs-on: ubuntu-22.04
27
- steps:
28
- - name: Check out repository
29
- uses: actions/checkout@v2
30
- - name: Run Tests
31
- run: |
32
- echo $(pwd)
33
- echo $(ls)
34
- docker pull nrel/openstudio:3.2.1
35
- docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.2.1
36
- docker exec -t test pwd
37
- docker exec -t test ls
38
- docker exec -t test bundle update
39
- docker exec -t test bundle exec rake
40
- docker kill test
41
- test_330x:
42
- runs-on: ubuntu-22.04
43
- steps:
44
- - name: Check out repository
45
- uses: actions/checkout@v2
46
- - name: Run Tests
47
- run: |
48
- echo $(pwd)
49
- echo $(ls)
50
- docker pull nrel/openstudio:3.3.0
51
- docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.3.0
52
- docker exec -t test pwd
53
- docker exec -t test ls
54
- docker exec -t test bundle update
55
- docker exec -t test bundle exec rake
56
- docker kill test
57
- test_340x:
58
- runs-on: ubuntu-22.04
59
- steps:
60
- - name: Check out repository
61
- uses: actions/checkout@v2
62
- - name: Run Tests
63
- run: |
64
- echo $(pwd)
65
- echo $(ls)
66
- docker pull nrel/openstudio:3.4.0
67
- docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.4.0
68
- docker exec -t test pwd
69
- docker exec -t test ls
70
- docker exec -t test bundle update
71
- docker exec -t test bundle exec rake
72
- docker kill test
73
- test_351x:
74
- runs-on: ubuntu-22.04
75
- steps:
76
- - name: Check out repository
77
- uses: actions/checkout@v2
78
- - name: Run Tests
79
- run: |
80
- echo $(pwd)
81
- echo $(ls)
82
- docker pull nrel/openstudio:3.5.1
83
- docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.5.1
84
- docker exec -t test pwd
85
- docker exec -t test ls
86
- docker exec -t test bundle update
87
- docker exec -t test bundle exec rake
88
- docker kill test
89
- test_361x:
9
+ test_oslg:
90
10
  runs-on: ubuntu-22.04
91
11
  steps:
92
12
  - name: Check out repository
data/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # oslg
2
2
 
3
- A logger module for _picky_ [OpenStudio](https://openstudio.net) [Measure](https://nrel.github.io/OpenStudio-user-documentation/reference/measure_writing_guide/) developers who wish to select what gets logged to which target (e.g. OpenStudio _runner_ vs custom JSON file). Add:
3
+ A logger, initially for _picky_ [OpenStudio](https://openstudio.net) [Measure](https://nrel.github.io/OpenStudio-user-documentation/reference/measure_writing_guide/) developers who wish to select what gets logged to which target (e.g. OpenStudio _runner_ vs custom JSON files). Yet __oslg__ has no OpenStudio dependency; it can be integrated within any other environment. Just add:
4
4
 
5
5
  ```
6
6
  gem "oslg", git: "https://github.com/rd2/oslg", branch: "main"
7
7
  ```
8
8
 
9
- ... in a v2.1 [bundled](https://bundler.io) _Measure_ development environment "Gemfile" (or instead as a _gemspec_ dependency), and then run:
9
+ ... in a v2.1 [bundled](https://bundler.io) development environment "Gemfile" (or instead as a _gemspec_ dependency), and then run:
10
10
 
11
11
  ```
12
12
  bundle install (or 'bundle update')
@@ -14,7 +14,7 @@ bundle install (or 'bundle update')
14
14
 
15
15
  ### OpenStudio & EnergyPlus
16
16
 
17
- In most cases, critical (and many non-critical) OpenStudio anomalies will be caught by EnergyPlus at the start of a simulation. Standalone applications (e.g. _Apply Measures Now_) or [SDK](https://openstudio-sdk-documentation.s3.amazonaws.com/index.html)-based iterative solutions can't rely on EnergyPlus to catch such errors - and somehow warn users of potentially invalid results. This Ruby module provides developers a means to log warnings, as well as non-fatal & fatal errors, that may eventually put OpenStudio's (or EnergyPlus') internal processes at risk. Developers are free to decide how to harness __oslg__ as they see fit, e.g. output logged WARNING messages to the OpenStudio _runner_, while writing out DEBUG messages to a bug report file.
17
+ In most cases, critical (and many non-critical) OpenStudio anomalies will be caught by EnergyPlus at the start of a simulation. Standalone applications (e.g. _Apply Measures Now_) or [SDK](https://openstudio-sdk-documentation.s3.amazonaws.com/index.html) based iterative solutions can't rely on EnergyPlus to catch such errors - and somehow warn users of potentially invalid results. __oslg__ provides developers a means to log warnings, as well as non-fatal & fatal errors, that may eventually put OpenStudio's (or EnergyPlus') internal processes at risk. Developers are free to decide how to harness __oslg__ as they see fit, e.g. output logged WARNING messages to the OpenStudio _runner_, while writing out DEBUG messages to a bug report file.
18
18
 
19
19
  ### Recommended use
20
20
 
@@ -39,7 +39,7 @@ FATAL
39
39
 
40
40
  DEBUG messages aren't benign at all, but are certainly less informative for the typical Measure user.
41
41
 
42
- Initially, __oslg__ sets 2x internal attributes: `level` (INFO) and `status` (< DEBUG). The `level` attribute is a user-set threshold below which less severe logs (e.g. DEBUG) are ignored. For instance, if `level` were _reset_ to DEBUG (e.g. `M.reset(M::DEBUG)`), then all DEBUG messages would also be logged. The `status` attribute is reset with each new log entry when the latter's log level is more severe than its predecessors (e.g. `status == M::FATAL` if there is a single log entry registered as FATAL). To check the curent __oslg__ `status` (true or false):
42
+ Initially, __oslg__ sets 2 _global_ internal attributes: `level` (INFO) and `status` (< DEBUG). The `level` attribute is a user-set threshold below which less severe logs (e.g. DEBUG) are ignored. For instance, if `level` were _reset_ to DEBUG (e.g. `M.reset(M::DEBUG)`), then all DEBUG messages would also be logged. The `status` attribute is reset with each new log entry when the latter's log level is more severe than its predecessors (e.g. `status == M::FATAL` if there is a single log entry registered as FATAL). To check the curent __oslg__ `status` (true or false):
43
43
 
44
44
  ```
45
45
  M.debug?
@@ -54,7 +54,7 @@ It's sometimes not a bad idea to rely on a _clean_ slate (e.g. within RSpecs). T
54
54
  M.clean!
55
55
  ```
56
56
 
57
- EnergyPlus will run with e.g. out-of-range material or fluid properties, while logging ERROR messages in the process. It remains up to users to decide what to do with simulation results. We recommend something similar with __oslg__. For instance, we suggest logging as __FATAL__ any error that should halt Measure processes and prevent OpenStudio from launching an EnergyPlus simulation. This could be missing or poorly-defined OpenStudio files.
57
+ EnergyPlus will run with e.g. out-of-range material or fluid properties, while logging ERROR messages in the process. It remains up to users to decide what to do with simulation results. We recommend something similar with __oslg__. For instance, we suggest logging as __FATAL__ any error that should halt Measure processes and prevent OpenStudio from launching an EnergyPlus simulation. This could be missing or poorly formatted files.
58
58
 
59
59
  ```
60
60
  M.log(M::FATAL, "Missing input JSON file")
@@ -66,7 +66,7 @@ Consider logging non-fatal __ERROR__ messages when encountering invalid OpenStud
66
66
  M.log(M::ERROR, "Measure won't process MASSLESS materials")
67
67
  ```
68
68
 
69
- A __WARNING__ could be triggered from inherit limitations of the underlying Measure scope or methodology (something users may have little knowledge of beforehand). For instance, surfaces the size of dinner plates are often artifacts of poor 3D model design. It's usually not a good idea to have such small surfaces in an OpenStudio model, but neither OpenStudio nor EnergyPlus will necessarily warn users of such occurrences. It's up to users to decide on the suitable course of action.
69
+ A __WARNING__ could be triggered from inherit limitations of the underlying Measure scope or methodology (something users may have little knowledge of beforehand). For instance, surfaces the size of dinner plates are often artifacts of poor 3D modelling. It's usually not a good idea to have such small surfaces in an OpenStudio model, but neither OpenStudio nor EnergyPlus will necessarily warn users of such occurrences. It's up to users to decide on the suitable course of action.
70
70
 
71
71
  ```
72
72
  M.log(M::WARN, "Surface area < 100cm2")
@@ -78,13 +78,13 @@ There's also the possibility of logging __INFO__-rmative messages for users, e.g
78
78
  M.log(M::INFO, "Envelope compliant to prescriptive code requirements")
79
79
  ```
80
80
 
81
- Finally, a number of sanity checks are likely warranted to ensure Ruby doesn't crash (e.g., invalid access to uninitialized variables), especially for lower-level functions. We suggest implementing safe fallbacks when this occurs, but __DEBUG__ errors could nonetheless be triggered to signal a bug.
81
+ Finally, a number of sanity checks are likely warranted to ensure Ruby doesn't crash (e.g., invalid access to uninitialized variables), especially for lower-level functions. We suggest implementing safe fallbacks when this occurs, but __DEBUG__ errors could nonetheless be logged to signal buggy code.
82
82
 
83
83
  ```
84
84
  M.log(M::DEBUG, "Hash? expecting Array (method)")
85
85
  ```
86
86
 
87
- All log entries are stored in a single Ruby _Array_, with each individual log entry as a Ruby _Hash_ with 2x _keys_ ```:level``` and ```:message```, e.g.:
87
+ All log entries are stored in a single Ruby _Array_, with each individual log entry as a Ruby _Hash_ with 2 _keys_ ```:level``` and ```:message```, e.g.:
88
88
 
89
89
  ```
90
90
  M.logs.each do |log|
@@ -96,7 +96,7 @@ These logs can be first _mapped_ to other structures (then edited), depending on
96
96
 
97
97
  ### Preset log templates
98
98
 
99
- Typically, developers would first catch bad input, log an error message and possibly exit by returning an object (e.g. __false__, __nil__), e.g.:
99
+ Typically, developers would first catch bad input, log an error message and possibly exit by returning an object (e.g. __false__, __nil__), such as:
100
100
 
101
101
  ```
102
102
  unless var.is_a?(Array)
@@ -109,19 +109,19 @@ The following are __oslg__ one-liner methods that _log & return_ in one go. Thes
109
109
 
110
110
  ---
111
111
 
112
- __invalid__: for logging e.g. uninitialized or nilled objects:
112
+ __invalid__: for logging e.g. nilled objects or out-of-scope variables:
113
113
 
114
114
  ```
115
- return M.invalid("area", "sum", 0, M::ERROR, false) unless area
115
+ return M.invalid("area", "sum", 0, M::FATAL, false) if area > 1000000
116
116
  ```
117
117
 
118
- This logs an ERROR message informing users that an invalid object, 'area', was caught while running method 'sum', and then exits by returning _false_. The logged message would be:
118
+ This logs a FATAL error message informing users that an out-of-scope argument, 'area', was caught while running method 'sum', and then exits by returning _false_. The logged message would be:
119
119
 
120
120
  ```
121
121
  "Invalid 'area' (sum)"
122
122
  ```
123
123
 
124
- The 3rd argument (e.g. _0_) is ignored unless `> 0` - a useful option when asserting method arguments:
124
+ The 3rd parameter (e.g. _0_) is ignored unless `> 0` - a useful option when asserting method arguments:
125
125
 
126
126
  ```
127
127
  def sum(areas, units)
@@ -131,93 +131,91 @@ def sum(areas, units)
131
131
  end
132
132
  ```
133
133
 
134
- ... would generate the following if both `areas` and `units` arguments were for instance _nilled_:
134
+ ... would generate the following if both `areas` and `units` arguments were, for instance, _nilled_:
135
135
  ```
136
136
  "Invalid 'areas' arg #1 (sum)"
137
137
  "Invalid 'units' arg #2 (sum)"
138
138
  ```
139
139
 
140
- The first 2x __invalid__ method arguments (faulty object ID, calling method ID) are required. The remaining 3x arguments are optional; in such cases, __invalid__ `level` defaults to DEBUG, and __invalid__ returns _nil_).
140
+ The first 2 __invalid__ method parameters (faulty object ID, calling method ID) are required. The remaining 3 parameters are optional; in such cases, __invalid__ `level` defaults to DEBUG, and __invalid__ returns _nil_.
141
141
 
142
142
  ---
143
143
 
144
144
  __mismatch__: for logging incompatible instances vs classes:
145
145
 
146
146
  ```
147
- return M.mismatch("areas", areas, Array, "sum") unless areas.is_a?(Array)
147
+ return M.mismatch("area", area, Float, "sum") unless area.is_a?(Numeric)
148
148
  ```
149
149
 
150
- If 'areas' were for example a _String_, __mismatch__ would generate the following DEBUG log message (before returning _nil_):
150
+ If 'area' were for example a _String_, __mismatch__ would generate the following DEBUG log message (before returning _nil_):
151
151
 
152
152
  ```
153
- "'areas' String? expecting Array (sum)"
153
+ "'area' String? expecting Float (sum)"
154
154
  ```
155
155
 
156
- These 4x __mismatch__ arguments are required (an object ID, a valid Ruby object, the mismatched Ruby class, and the calling method ID). As a safeguard, __oslg__ will NOT log a _mismatch_ if the object is an actual instance of the class. As with __invalid__, there are 2x optional _terminal_ arguments, e.g. `M::ERROR, false)`.
156
+ These 4 __mismatch__ parameters are required (an object ID, a valid Ruby object, the mismatched Ruby class, and the calling method ID). As a safeguard, __oslg__ will NOT log a _mismatch_ if the object is an actual instance of the class. As with __invalid__, there are 2 optional _terminal_ parameters (e.g. `M::FATAL`, `false`).
157
157
 
158
158
  ---
159
159
 
160
160
  __hashkey__: for logging missing _Hash_ keys:
161
161
 
162
162
  ```
163
- return M.hashkey("faces", faces, :area, "sum") unless faces.key?(:area)
163
+ return M.hashkey("floor area", floor, :area, "sum") unless floor.key?(:area)
164
164
  ```
165
165
 
166
- If the _Hash_ `faces` does not hold `:area` as one of its keys, then __hashkey__ would generate the following DEBUG log message (before returning _nil_):
166
+ If the _Hash_ `floor` does not hold `:area` as one of its keys, then __hashkey__ would generate the following DEBUG log message (before returning _nil_):
167
167
 
168
168
  ```
169
- "Missing 'area' key in 'faces' Hash (sum)"
169
+ "Missing 'area' key in 'floor' Hash (sum)"
170
170
  ```
171
171
 
172
- Similar to __mismatch__, the method __hashkey__ requires 4x arguments (a _Hash_ ID, a valid Ruby _Hash_, the missing _key_, and the calling method ID). There are also 2x optional _terminal_ arguments, e.g. `M::ERROR, false)`.
172
+ Similar to __mismatch__, the method __hashkey__ requires 4 parameters (a _Hash_ ID, a valid Ruby _Hash_, the missing _key_, and the calling method ID). There are also 2 optional _terminal_ parameters (e.g. `M::FATAL`, `false`).
173
173
 
174
174
  ---
175
175
 
176
- __empty__: for logging empty _Enumerable_ (e.g. _Array_, _Hash_) instances or uninitialized boost optionals (e.g. uninitialized _ThermalZone_ object of an _OpenStudio Space_):
176
+ __empty__: for logging empty _Enumerable_ (e.g. _Array_, _Hash_) instances or uninitialized _Boost_ optionals (e.g. an uninitialized _ThermalZone_ object of an _OpenStudio Space_):
177
177
 
178
178
  ```
179
- return M.empty("faces", "sum", M::ERROR, false) if faces.empty?
179
+ return M.empty("zone", "conditioned?", M::FATAL, false) if space.thermalZone.empty?
180
180
  ```
181
181
 
182
- An empty `faces` _Hash_ would generate the following ERROR log message (before returning _false_):
182
+ An empty (i.e. uninitialized) `thermalZone` would generate the following FATAL error log message (before returning _false_):
183
183
 
184
184
  ```
185
- "Empty 'faces' (sum)"
185
+ "Empty 'zone' (conditioned?)"
186
186
  ```
187
187
 
188
- Again, the first 2x arguments are required; the last 2x are optional.
188
+ Again, the first 2 parameters are required; the last 2 are optional.
189
189
 
190
190
  ---
191
191
 
192
192
  __zero__: for logging zero'ed (or nearly-zero'ed) values:
193
193
 
194
194
  ```
195
- M.zero("area", "sum", M::FATAL, false) if area.zero?
196
- M.zero("area", "sum", M::FATAL, false) if area.abs < TOL
195
+ M.zero("floor area", "sum", M::FATAL, false) if floor[:area].abs < TOL
197
196
  ```
198
- ... generating the following FATAL log message (before returning _false_):
197
+ ... generating the following FATAL error log message (before returning _false_):
199
198
 
200
199
  ```
201
- "Zero 'area' (sum)"
202
- "Zero 'area' (sum)"
200
+ "Zero 'floor area' (sum)"
203
201
  ```
204
202
 
205
- And again, the first 2x arguments are required; the last 2x are optional.
203
+ And again, the first 2 parameters are required; the last 2 are optional.
206
204
 
207
205
  ---
208
206
 
209
207
  __negative__: for logging negative (< 0) values:
210
208
 
211
209
  ```
212
- M.negative("area", "sum", M::FATAL, false) if area < 0
210
+ M.negative("floor area", "sum", M::FATAL, false) if floor[:area] < 0
213
211
  ```
214
212
  ... generating this FATAL log message (before returning _false_):
215
213
 
216
214
  ```
217
- "Negative 'area' (sum)"
215
+ "Negative 'floor area' (sum)"
218
216
  ```
219
217
 
220
- You guessed it: the first 2x arguments are required; the last 2x as optionals.
218
+ You guessed it: the first 2 parameters are required; the last 2 as optionals.
221
219
 
222
220
  ---
223
221
 
data/lib/oslg/oslog.rb CHANGED
@@ -29,42 +29,27 @@
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
+ @@level = INFO # initial log level
41
+ @@status = 0 # initial status
57
42
 
58
43
  ##
59
- # Return log entries.
44
+ # Returns log entries.
60
45
  #
61
- # @return [Array] current log entries
46
+ # @return [Array<Hash>] log entries (see @@logs)
62
47
  def logs
63
48
  @@logs
64
49
  end
65
50
 
66
51
  ##
67
- # Return current log level.
52
+ # Returns current log level.
68
53
  #
69
54
  # @return [Integer] DEBUG, INFO, WARN, ERROR or FATAL
70
55
  def level
@@ -72,7 +57,7 @@ module OSlg
72
57
  end
73
58
 
74
59
  ##
75
- # Return current log status.
60
+ # Returns current log status.
76
61
  #
77
62
  # @return [Integer] DEBUG, INFO, WARN, ERROR or FATAL
78
63
  def status
@@ -80,7 +65,7 @@ module OSlg
80
65
  end
81
66
 
82
67
  ##
83
- # Return whether current status is DEBUG
68
+ # Returns whether current status is DEBUG.
84
69
  #
85
70
  # @return [Bool] true if DEBUG
86
71
  def debug?
@@ -88,7 +73,7 @@ module OSlg
88
73
  end
89
74
 
90
75
  ##
91
- # Return whether current status is INFO
76
+ # Returns whether current status is INFO.
92
77
  #
93
78
  # @return [Bool] true if INFO
94
79
  def info?
@@ -96,7 +81,7 @@ module OSlg
96
81
  end
97
82
 
98
83
  ##
99
- # Return whether current status is WARN
84
+ # Returns whether current status is WARN.
100
85
  #
101
86
  # @return [Bool] true if WARN
102
87
  def warn?
@@ -104,7 +89,7 @@ module OSlg
104
89
  end
105
90
 
106
91
  ##
107
- # Return whether current status is ERROR
92
+ # Returns whether current status is ERROR.
108
93
  #
109
94
  # @return [Bool] true if ERROR
110
95
  def error?
@@ -112,7 +97,7 @@ module OSlg
112
97
  end
113
98
 
114
99
  ##
115
- # Return whether current status is FATAL
100
+ # Returns whether current status is FATAL.
116
101
  #
117
102
  # @return [Bool] true if FATAL
118
103
  def fatal?
@@ -120,66 +105,61 @@ module OSlg
120
105
  end
121
106
 
122
107
  ##
123
- # Return string equivalent of level
108
+ # Resets level, if lvl (input) is within accepted range.
124
109
  #
125
- # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
110
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
126
111
  #
127
- # @return [String] "DEBUG", "INFO", "WARN", "ERROR" or "FATAL"
128
- def tag(level)
129
- return @@tag[level] if level >= DEBUG && level <= FATAL
130
-
131
- ""
132
- end
112
+ # @return [Integer] updated/current level
113
+ def reset(lvl = DEBUG)
114
+ return @@level unless lvl.respond_to?(:to_i)
133
115
 
134
- ##
135
- # Return preset OSlg message linked to status.
136
- #
137
- # @param status [Integer] DEBUG, INFO, WARN, ERROR or FATAL
138
- #
139
- # @return [String] preset OSlg message
140
- def msg(status)
141
- return @@msg[status] if status >= DEBUG && status <= FATAL
116
+ lvl = lvl.to_i
117
+ return @@level if lvl < DEBUG
118
+ return @@level if lvl > FATAL
142
119
 
143
- ""
120
+ @@level = lvl
144
121
  end
145
122
 
146
123
  ##
147
- # Set level.
148
- #
149
- # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
124
+ # Logs a new entry, if provided arguments are valid.
150
125
  #
151
- # @return [Integer] current level
152
- def reset(level)
153
- @@level = level if level >= DEBUG && level <= FATAL
154
- end
155
-
156
- ##
157
- # Log new entry.
126
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
127
+ # @param message [#to_s] user-provided log message
158
128
  #
159
- # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
160
- # @param message [String] user-provided message
129
+ # @example A user warning
130
+ # log(WARN, "Surface area < 100cm2")
161
131
  #
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
132
+ # @return [Integer] updated/current status
133
+ def log(lvl = DEBUG, message = "")
134
+ return @@status unless lvl.respond_to?(:to_i)
135
+ return @@status unless message.respond_to?(:to_s)
168
136
 
169
- @@status
137
+ lvl = lvl.to_i
138
+ message = message.to_s.strip
139
+ return @@status if lvl < DEBUG
140
+ return @@status if lvl > FATAL
141
+ return @@status if lvl < @@level
142
+
143
+ @@logs << {level: lvl, message: message}
144
+ return @@status unless lvl > @@status
145
+
146
+ @@status = lvl
170
147
  end
171
148
 
172
149
  ##
173
- # Log template 'invalid object' message and return user-set object.
150
+ # Logs template 'invalid object' message, if provided arguments are valid.
174
151
  #
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)
152
+ # @param id [#to_s] 'invalid object' identifier
153
+ # @param mth [#to_s] calling method identifier
154
+ # @param ord [#to_i] calling method argument order number of obj (optional)
155
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
156
+ # @param res what to return (optional)
157
+ #
158
+ # @example An invalid argument, logging a FATAL error, returning FALSE
159
+ # return invalid("area", "sum", 0, FATAL, false) if area > 1000000
180
160
  #
181
- # @return [Object] return object if specified by user
182
- # @return [Nil] nil if return object undefined
161
+ # @return user-provided object
162
+ # @return [nil] if user hasn't provided an object to return
183
163
  def invalid(id = "", mth = "", ord = 0, lvl = DEBUG, res = nil)
184
164
  return res unless id.respond_to?(:to_s)
185
165
  return res unless mth.respond_to?(:to_s)
@@ -200,23 +180,31 @@ module OSlg
200
180
  msg = "Invalid '#{id}' "
201
181
  msg += "arg ##{ord} " if ord > 0
202
182
  msg += "(#{mth})"
203
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
183
+ return res if lvl < DEBUG
184
+ return res if lvl > FATAL
185
+
186
+ log(lvl, msg)
204
187
 
205
188
  res
206
189
  end
207
190
 
208
191
  ##
209
- # Log template 'instance/class mismatch' message and return user-set object.
192
+ # Logs template 'instance/class mismatch' message, if provided arguments are
193
+ # valid. The message is not logged if the provided object to evaluate is an
194
+ # actual instance of the target class.
210
195
  #
211
- # @param id [String] mismatched object identifier
212
- # @param obj [Object] object to validate
196
+ # @param id [#to_s] mismatched object identifier
197
+ # @param obj the object to validate
213
198
  # @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)
199
+ # @param mth [#to_s] calling method identifier (optional)
200
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
201
+ # @param res what to return (optional)
202
+ #
203
+ # @example A mismatched argument instance/class
204
+ # mismatch("area", area, Float, "sum") unless area.is_a?(Numeric)
217
205
  #
218
- # @return [Object] return object if specified by user
219
- # @return [Nil] nil if return object undefined
206
+ # @return user-provided object
207
+ # @return [nil] if user hasn't provided an object to return
220
208
  def mismatch(id = "", obj = nil, cl = nil, mth = "", lvl = DEBUG, res = nil)
221
209
  return res unless id.respond_to?(:to_s)
222
210
  return res unless cl.is_a?(Class)
@@ -224,8 +212,8 @@ module OSlg
224
212
  return res unless mth.respond_to?(:to_s)
225
213
  return res unless lvl.respond_to?(:to_i)
226
214
 
227
- mth = mth.to_s.strip
228
215
  id = id.to_s.strip
216
+ mth = mth.to_s.strip
229
217
  lvl = lvl.to_i
230
218
 
231
219
  id = id[0...60] + " ..." if id.length > 60
@@ -235,23 +223,30 @@ module OSlg
235
223
  return res if mth.empty?
236
224
 
237
225
  msg = "'#{id}' #{obj.class}? expecting #{cl} (#{mth})"
238
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
226
+ return res if lvl < DEBUG
227
+ return res if lvl > FATAL
228
+
229
+ log(lvl, msg)
239
230
 
240
231
  res
241
232
  end
242
233
 
243
234
  ##
244
- # Log template 'missing hash key' message and return user-set object.
235
+ # Logs template 'missing hash key' message, if provided arguments are valid.
236
+ # The message is not logged if the provided key exists.
245
237
  #
246
- # @param id [String] Hash identifier
238
+ # @param id [#to_s] Hash identifier
247
239
  # @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)
240
+ # @param key missing key
241
+ # @param mth [#to_s] calling method identifier
242
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
243
+ # @param res what to return (optional)
244
+ #
245
+ # @example A missing Hash key
246
+ # hashkey("floor area", floor, :area, "sum") unless floor.key?(:area)
252
247
  #
253
- # @return [Object] return object if specified by user
254
- # @return [Nil] nil if return object undefined
248
+ # @return user-provided object
249
+ # @return [nil] if user hasn't provided an object to return
255
250
  def hashkey(id = "", hsh = {}, key = "", mth = "", lvl = DEBUG, res = nil)
256
251
  return res unless id.respond_to?(:to_s)
257
252
  return res unless hsh.is_a?(Hash)
@@ -270,21 +265,27 @@ module OSlg
270
265
  return res if mth.empty?
271
266
 
272
267
  msg = "Missing '#{key}' key in '#{id}' Hash (#{mth})"
273
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
268
+ return res if lvl < DEBUG
269
+ return res if lvl > FATAL
270
+
271
+ log(lvl, msg)
274
272
 
275
273
  res
276
274
  end
277
275
 
278
276
  ##
279
- # Log template 'empty (uninitialized)' message and return user-set object.
277
+ # Logs template 'empty' message, if provided arguments are valid.
280
278
  #
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)
279
+ # @param id [#to_s] empty object identifier
280
+ # @param mth [#to_s] calling method identifier
281
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
282
+ # @param res what to return (optional)
283
+ #
284
+ # @example An uninitialized variable, logging an ERROR, returning FALSE
285
+ # empty("zone", "conditioned?", FATAL, false) if space.thermalZone.empty?
285
286
  #
286
- # @return [Object] return object if specified by user
287
- # @return [Nil] nil if return object undefined
287
+ # @return user-provided object
288
+ # @return [nil] if user hasn't provided an object to return
288
289
  def empty(id = "", mth = "", lvl = DEBUG, res = nil)
289
290
  return res unless id.respond_to?(:to_s)
290
291
  return res unless mth.respond_to?(:to_s)
@@ -301,21 +302,27 @@ module OSlg
301
302
  return res if mth.empty?
302
303
 
303
304
  msg = "Empty '#{id}' (#{mth})"
304
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
305
+ return res if lvl < DEBUG
306
+ return res if lvl > FATAL
307
+
308
+ log(lvl, msg)
305
309
 
306
310
  res
307
311
  end
308
312
 
309
313
  ##
310
- # Log template 'near zero' message and return user-set object.
314
+ # Logs template 'zero' value message, if provided arguments are valid.
311
315
  #
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)
316
+ # @param id [#to_s] zero object identifier
317
+ # @param mth [#to_s] calling method identifier
318
+ # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
319
+ # @param res what to return (optional)
320
+ #
321
+ # @example A near-zero variable
322
+ # zero("floor area", "sum") if floor[:area].abs < TOL
316
323
  #
317
- # @return [Object] return object if specified by user
318
- # @return [Nil] nil if return object undefined
324
+ # @return user-provided object
325
+ # @return [nil] if user hasn't provided an object to return
319
326
  def zero(id = "", mth = "", lvl = DEBUG, res = nil)
320
327
  return res unless id.respond_to?(:to_s)
321
328
  return res unless mth.respond_to?(:to_s)
@@ -333,21 +340,27 @@ module OSlg
333
340
  return res if mth.empty?
334
341
 
335
342
  msg = "Zero '#{id}' (#{mth})"
336
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
343
+ return res if lvl < DEBUG
344
+ return res if lvl > FATAL
345
+
346
+ log(lvl, msg)
337
347
 
338
348
  res
339
349
  end
340
350
 
341
351
  ##
342
- # Log template 'negative' message and return user-set object.
352
+ # Logs template 'negative' message, if provided arguments are valid.
343
353
  #
344
- # @param id [String] negative object identifier
354
+ # @param id [#to_s] negative object identifier
345
355
  # @param mth [String] calling method identifier
346
356
  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
347
357
  # @param res [Object] what to return (optional)
348
358
  #
349
- # @return [Object] return object if specified by user
350
- # @return [Nil] nil if return object undefined
359
+ # @example A negative variable
360
+ # negative("floor area", "sum") if floor[:area] < 0
361
+ #
362
+ # @return user-provided object
363
+ # @return [nil] if user hasn't provided an object to return
351
364
  def negative(id = "", mth = "", lvl = DEBUG, res = nil)
352
365
  return res unless id.respond_to?(:to_s)
353
366
  return res unless mth.respond_to?(:to_s)
@@ -365,13 +378,16 @@ module OSlg
365
378
  return res if mth.empty?
366
379
 
367
380
  msg = "Negative '#{id}' (#{mth})"
368
- log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
381
+ return res if lvl < DEBUG
382
+ return res if lvl > FATAL
383
+
384
+ log(lvl, msg)
369
385
 
370
386
  res
371
387
  end
372
388
 
373
389
  ##
374
- # Reset log status and entries.
390
+ # Resets log status and entries.
375
391
  #
376
392
  # @return [Integer] current level
377
393
  def clean!
data/lib/oslg/version.rb CHANGED
@@ -29,5 +29,5 @@
29
29
  # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
30
 
31
31
  module OSlg
32
- VERSION = "0.2.7".freeze
32
+ VERSION = "0.2.8".freeze # OSlg version
33
33
  end
data/oslg.gemspec CHANGED
@@ -15,8 +15,8 @@ Gem::Specification.new do |s|
15
15
  s.version = OSlg::VERSION
16
16
  s.license = "BSD-3-Clause"
17
17
  s.summary = "OpenStudio SDK logger"
18
- s.description = "For OpenStudio SDK users who wish to select " \
19
- "what gets logged to which target."
18
+ s.description = "For OpenStudio SDK users (or others) who wish "\
19
+ "to select what gets logged to which target."
20
20
  s.authors = ["Denis Bourgeois"]
21
21
  s.email = ["denis@rd2.ca"]
22
22
  s.platform = Gem::Platform::RUBY
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: oslg
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.7
4
+ version: 0.2.8
5
5
  platform: ruby
6
6
  authors:
7
7
  - Denis Bourgeois
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2023-06-07 00:00:00.000000000 Z
11
+ date: 2023-08-17 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -52,8 +52,8 @@ dependencies:
52
52
  - - "~>"
53
53
  - !ruby/object:Gem::Version
54
54
  version: '3.11'
55
- description: For OpenStudio SDK users who wish to select what gets logged to which
56
- target.
55
+ description: For OpenStudio SDK users (or others) who wish to select what gets logged
56
+ to which target.
57
57
  email:
58
58
  - denis@rd2.ca
59
59
  executables: []
@@ -76,7 +76,7 @@ licenses:
76
76
  - BSD-3-Clause
77
77
  metadata:
78
78
  homepage_uri: https://github.com/rd2/oslg
79
- source_code_uri: https://github.com/rd2/oslg/tree/v0.2.7
79
+ source_code_uri: https://github.com/rd2/oslg/tree/v0.2.8
80
80
  bug_tracker_uri: https://github.com/rd2/oslg/issues
81
81
  post_install_message:
82
82
  rdoc_options: []