oslg 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0535a05d35fee722c018380a21e3253ce9764058b7092a80ac4904426c9fa243
+  data.tar.gz: 5919cb3f5ecb420a53c54b5740bf72177077cacb0a3a2cce65647ba12a8b4094
+SHA512:
+  metadata.gz: 432dfef35fa88b722c2dff388ebe8f999e4a9bad0aaa987b495006c968572dac98773f5a7659866c3955620622b5b89a3c5544bdad1f577d3feba5bf51796fa5
+  data.tar.gz: 2696ecd29f72652774d0b6cf5db41a3e4b81af54c4d9a2cd8b64669500085c5d06914744ac061b42e878e3f27c6ac89387b094aeaf08f87b477fd9e2a2e8bef3

data/.github/workflows/pull_request.yml

@@ -0,0 +1,72 @@
+name: Pull Request CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test_300x:
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v2
+    - name: Run Tests
+      run: |
+        echo $(pwd)
+        echo $(ls)
+        docker pull nrel/openstudio:3.0.0
+        docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.0.0
+        docker exec -t test pwd
+        docker exec -t test ls
+        docker exec -t test bundle update
+        docker exec -t test bundle exec rake
+        docker kill test
+  test_321x:
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v2
+    - name: Run Tests
+      run: |
+        echo $(pwd)
+        echo $(ls)
+        docker pull nrel/openstudio:3.2.1
+        docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.2.1
+        docker exec -t test pwd
+        docker exec -t test ls
+        docker exec -t test bundle update
+        docker exec -t test bundle exec rake
+        docker kill test
+  test_330x:
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v2
+    - name: Run Tests
+      run: |
+        echo $(pwd)
+        echo $(ls)
+        docker pull nrel/openstudio:3.3.0
+        docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.3.0
+        docker exec -t test pwd
+        docker exec -t test ls
+        docker exec -t test bundle update
+        docker exec -t test bundle exec rake
+        docker kill test
+  test_340x:
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v2
+    - name: Run Tests
+      run: |
+        echo $(pwd)
+        echo $(ls)
+        docker pull nrel/openstudio:3.4.0
+        docker run --name test --rm -d -t -v $(pwd):/work -w /work nrel/openstudio:3.4.0
+        docker exec -t test pwd
+        docker exec -t test ls
+        docker exec -t test bundle update
+        docker exec -t test bundle exec rake
+        docker kill test

data/.gitignore

@@ -0,0 +1,11 @@
+Gemfile.lock
+.rspec_status
+.bundle
+pkg
+
+.yardoc
+_yardoc
+doc/
+rdoc
+
+.DS_Store

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Denis Bourgeois
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,220 @@
+# oslg
+
+A logger module for _picky_ [OpenStudio](https://openstudio-sdk-documentation.s3.amazonaws.com/index.html) [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:
+
+```
+gem "oslg", git: "https://github.com/rd2/oslg", branch: "main"
+```
+
+... in a measure's development environment "Gemfile", and then run:
+
+```
+bundle install
+```
+
+### OpenStudio & EnergyPlus
+
+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.
+
+### Recommended use
+
+As a Ruby module, one can access __oslg__ by _extending_ a measure module or class:
+
+```
+module Modu
+  extend OSlg
+  ...
+end
+```
+
+Ordered __oslg__ levels (or CONSTANTS), from benign to severe:
+
+```
+DEBUG
+INFO
+WARN
+ERROR
+FATAL
+```
+
+DEBUG messages aren't benign at all, but are certainly less informative for the typical Measure user.
+
+Initially, __oslg__ sets 2x internal variable states: `level` (INFO) and `status` (< DEBUG). The variable `level` 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. `Modu.reset(Modu::DEBUG)`), then all DEBUG messages would also be logged. The variable `status` is reset with each new log entry if the latter's log level is more severe than its predecessor (e.g. `status == Modu::FATAL` if there is a single log entry registered as FATAL). To check the curent __oslg__ `status` (true or false):  
+
+```
+Modu.debug?
+Modu.warn?
+Modu.error?
+Modu.fatal?
+```
+
+It's sometimes not a bad idea to rely on a _clean_ slate (e.g. within RSpecs). This flushes out all previous logs and resets `level` (INFO) and `status` (< DEBUG) - use with caution in production code!
+
+```
+Modu.clean!
+```
+
+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.
+
+```
+Modu.log(Modu::FATAL, "Missing input JSON file")
+```
+
+Consider logging non-fatal __ERROR__ messages when encountering invalid OpenStudio file entries, i.e. well-defined, yet invalid vis-à-vis EnergyPlus limitations. The invalid object could be simply ignored, while the measure pursues its (otherwise valid) calculations ... with OpenStudio ultimately launching an EnergyPlus simulation. If a simulation indeed ran (ultimately a go/no-go decision made by the EnergyPlus simulation engine), it would be up to users to decide if simulation results were valid or useful, given the context - maybe based on __oslg__ logged messages. In short, non-fatal ERROR logs should ideally point to bad input users can fix.
+
+```
+Modu.log(Modu::ERROR, "Measure won't process MASSLESS materials")
+```
+
+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.
+
+```
+Modu.log(Modu::WARN, "Surface area < 100cm2")
+```
+
+There's also the possibility of logging __INFO__-rmative messages for users, e.g. the final state of a measure variable before exiting.
+
+```
+Modu.log(Modu::INFO, "Envelope compliant to prescriptive code requirements")
+```
+
+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.
+
+```
+Modu.log(Modu::DEBUG, "Hash? expecting Array (method)")
+```
+
+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.:
+
+```
+Modu.logs.each do |log|
+  puts "Uh-oh: #{log[:message]}" if log[:level] > Modu::INFO
+end
+```
+
+These logs can be first _mapped_ to other structures (then edited), depending on output targets.
+
+### Preset log templates
+
+Typically, developers would first catch bad input, log an error message and possibly exit by returning a variable (e.g. __false__, __nil__), e.g.:  
+
+```
+unless var.is_a?(Array)
+  Modu.log(Modu::DEBUG, "#{var.class}? expecting Array (method)")
+  return false
+end
+```
+
+The following are __oslg__ one-liner methods that _log & return_ in one go. These are for some of the most common checks OpenStudio SDK Ruby developers are likely to need. These methods require _valid_ arguments for __oslg__ to actually log. Although often expecting strings as arguments, the methods will try to convert other types to strings (e.g. classes, numbers, even entire arrays) if possible.
+
+---
+
+__invalid__: for logging e.g. uninitialized or nilled objects:
+
+```
+return Modu.invalid("area", "sum", 0, Modu::ERROR, false) unless area
+```
+
+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:
+
+```
+"Invalid 'area' (sum)"
+```
+
+The 3rd argument (e.g. _0_) is ignored unless `> 0` - a useful option when asserting method arguments:
+
+```
+def sum(areas, units)
+  return Modu.invalid("areas", "sum", 1) unless areas
+  return Modu.invalid("units", "sum", 2) unless units
+  ...
+end
+```
+
+... would generate the following if both `areas` and `units` arguments were nilled:
+```
+"Invalid 'areas' arg #1 (sum)"
+"Invalid 'units' arg #2 (sum)"
+```
+
+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_).
+
+---
+
+__mismatch__: for logging incompatible instances vs classes:
+
+```
+return Modu.mismatch("areas", areas, Array, "sum") unless areas.is_a?(Array)
+```
+
+If 'areas' were a _String_, __mismatch__ would generate the following DEBUG log message (before returning _nil_):
+
+```
+"'areas' String? expecting Array (sum)"
+```
+
+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. `Modu::ERROR, false)`.
+
+---
+
+__hashkey__: for logging missing _Hash_ keys:
+
+```
+return Modu.hashkey("faces", faces, :area, "sum") unless faces.key?(:area)
+```
+
+If the _Hash_ `faces` does not hold `:area` as one of its keys, then __mismatch__ would generate the following DEBUG log message (before returning _nil_):
+
+```
+"'faces' Hash: no key 'area' (sum)"
+```
+
+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. `Modu::ERROR, false)`.
+
+---
+
+__empty__: for logging empty _Enumerable_ (e.g. _Array_, _Hash_) instances or uninitialized boost optionals (e.g. uninitialized _ThermalZone_ object of an _OpenStudio Space_):
+
+```
+return Modu.empty("faces", "sum", Modu::ERROR, false) if faces.empty?
+```
+
+An empty `faces` _Hash_ would generate the following ERROR log message (before returning _false_):
+
+```
+"Empty 'faces' (sum)"
+```
+
+Again, the first 2x arguments are required; the last 2x are optional.
+
+---
+
+__zero__: for logging zero'ed (or nearly-zero'ed) values:
+
+```
+Modu.zero("area", "sum", Modu::FATAL, false) if area.zero?
+Modu.zero("area", "sum", Modu::FATAL, false) if area.abs < TOL
+```
+... generating the following FATAL log message (before returning _false_):
+
+```
+"'area' ~zero (sum)"
+"'area' ~zero (sum)"
+```
+
+And again, the first 2x arguments are required; the last 2x are optional.
+
+---
+
+__negative__: for logging negative (< 0) values:
+
+```
+Modu.negative("area", "sum", Modu::FATAL, false) if area < 0
+```
+... generating this FATAL log message (before returning _false_):
+
+```
+"'area' negative (sum)"
+```
+
+You guessed it: the first 2x arguments are required; the last 2x as optionals.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "yard"
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/oslg/oslog.rb"]
+end
+
+task default: :spec

data/lib/oslg/oslog.rb

@@ -0,0 +1,364 @@
+# BSD 3-Clause License
+#
+# Copyright (c) 2022, Denis Bourgeois
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+#    list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module OSlg
+  DEBUG        = 1
+  INFO         = 2
+  WARN         = 3
+  ERROR        = 4
+  FATAL        = 5
+
+  @@logs       = []
+  @@level      = INFO
+  @@status     = 0
+
+  @@tag        = []
+  @@tag[0    ] = ""
+  @@tag[DEBUG] = "DEBUG"
+  @@tag[INFO ] = "INFO"
+  @@tag[WARN ] = "WARNING"
+  @@tag[ERROR] = "ERROR"
+  @@tag[FATAL] = "FATAL"
+
+  @@msg        = []
+  @@msg[0    ] = ""
+  @@msg[DEBUG] = "Debugging ..."
+  @@msg[INFO ] = "Success! No errors, no warnings"
+  @@msg[WARN ] = "Partial success, raised non-fatal warnings"
+  @@msg[ERROR] = "Partial success, encountered non-fatal errors"
+  @@msg[FATAL] = "Failure, triggered fatal errors"
+
+  ##
+  # Return log entries.
+  #
+  # @return [Array] current log entries
+  def logs
+    @@logs
+  end
+
+  ##
+  # Return current log level.
+  #
+  # @return [Integer] DEBUG, INFO, WARN, ERROR or FATAL
+  def level
+    @@level
+  end
+
+  ##
+  # Return current log status.
+  #
+  # @return [Integer] DEBUG, INFO, WARN, ERROR or FATAL
+  def status
+    @@status
+  end
+
+  ##
+  # Return whether current status is DEBUG
+  #
+  # @return [Bool] true if DEBUG
+  def debug?
+    @@status == DEBUG
+  end
+
+  ##
+  # Return whether current status is INFO
+  #
+  # @return [Bool] true if INFO
+  def info?
+    @@status == INFO
+  end
+
+  ##
+  # Return whether current status is WARN
+  #
+  # @return [Bool] true if WARN
+  def warn?
+    @@status == WARN
+  end
+
+  ##
+  # Return whether current status is ERROR
+  #
+  # @return [Bool] true if ERROR
+  def error?
+    @@status == ERROR
+  end
+
+  ##
+  # Return whether current status is FATAL
+  #
+  # @return [Bool] true if FATAL
+  def fatal?
+    @@status == FATAL
+  end
+
+  ##
+  # Return string equivalent of level
+  #
+  # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
+  #
+  # @return [String] "DEBUG", "INFO", "WARN", "ERROR" or "FATAL"
+  def tag(level)
+    return @@tag[level] if level >= DEBUG && level <= FATAL
+    ""
+  end
+
+  ##
+  # Return preset OSlg message linked to status.
+  #
+  # @param status [Integer] DEBUG, INFO, WARN, ERROR or FATAL
+  #
+  # @return [String] preset OSlg message
+  def msg(status)
+    return @@msg[status] if status >= DEBUG && status <= FATAL
+    ""
+  end
+
+  ##
+  # Set level.
+  #
+  # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
+  #
+  # @return [Integer] current level
+  def reset(level)
+    @@level = level if level >= DEBUG && level <= FATAL
+  end
+
+  ##
+  # Log new entry.
+  #
+  # @param level [Integer] DEBUG, INFO, WARN, ERROR or FATAL
+  # @param message [String] user-provided message
+  #
+  # @return [Integer] current status
+  def log(level = DEBUG, message = "")
+    if level >= DEBUG && level <= FATAL && level >= @@level
+      @@logs << {level: level, message: message}
+      @@status = level if level > @@status
+    end
+    @@status
+  end
+
+  ##
+  # Log template 'invalid object' message and return user-set object.
+  #
+  # @param id [String] empty object identifier
+  # @param mth [String] calling method identifier
+  # @param ord [String] calling method argument order number of obj (optional)
+  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
+  # @param res [Object] what to return (optional)
+  #
+  # @return [Object] res if specified by user
+  # @return [Nil] nil if return object is invalid
+  def invalid(id = "", mth = "", ord = 0, lvl = DEBUG, res = nil)
+    return nil unless defined?(res)
+    return res unless defined?(id ) && id
+    return res unless defined?(mth) && mth
+    return res unless defined?(ord) && ord
+    return res unless defined?(lvl) && lvl
+    mth = mth.to_s.strip
+    mth = mth[0...60] + " ..." if mth.length > 60
+    return res if mth.empty?
+    id = id.to_s.strip
+    id = id[0...60] + " ..." if id.length > 60
+    return res if id.empty?
+    msg  = "Invalid '#{id}' "
+    msg += "arg ##{ord} " if ord.is_a?(Integer) && ord > 0
+    msg += "(#{mth})"
+    lvl = lvl.to_i unless lvl.is_a?(Integer)
+    log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
+    res
+  end
+
+  ##
+  # Log template 'instance/class mismatch' message and return user-set object.
+  #
+  # @param id [String] empty object identifier
+  # @param obj [Object] object to validate
+  # @param cl [Class] target class
+  # @param mth [String] calling method identifier
+  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
+  # @param res [Object] what to return (optional)
+  #
+  # @return [Object] res if specified by user
+  # @return [Nil] nil if return object is invalid
+  def mismatch(id = "", obj = nil, cl = nil, mth = "", lvl = DEBUG, res = nil)
+    return nil unless defined?(res)
+    return res unless defined?(id ) && id
+    return res unless defined?(obj) && obj
+    return res unless defined?(cl ) && cl
+    return res unless defined?(mth) && mth
+    return res unless defined?(lvl) && lvl
+    mth = mth.to_s.strip
+    mth = mth[0...60] + " ..." if mth.length > 60
+    return res if mth.empty?
+    id = id.to_s.strip
+    id = id[0...60] + " ..." if id.length > 60
+    return res if id.empty?
+    return res unless cl.is_a?(Class)
+    return res if obj.is_a?(cl)
+    msg = "'#{id}' #{obj.class}? expecting #{cl} (#{mth})"
+    lvl = lvl.to_i unless lvl.is_a?(Integer)
+    log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
+    res
+  end
+
+  ##
+  # Log template 'missing hash key' message and return user-set object.
+  #
+  # @param id [String] empty object identifier
+  # @param hsh [Hash] hash to validate
+  # @param key [Object] target key
+  # @param mth [String] calling method identifier
+  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
+  # @param res [Object] what to return (optional)
+  #
+  # @return [Object] res if specified by user
+  # @return [Nil] nil if not specified by user (or invalid)
+  def hashkey(id = "", hsh = {}, key = "", mth = "", lvl = DEBUG, res = nil)
+    return nil unless defined?(res)
+    return res unless defined?(id ) && id
+    return res unless defined?(hsh) && hsh
+    return res unless defined?(key) && key
+    return res unless defined?(mth) && mth
+    return res unless defined?(lvl) && lvl
+    mth = mth.to_s.strip
+    mth = mth[0...60] + " ..." if mth.length > 60
+    return res if mth.empty?
+    id = id.to_s.strip
+    id = id[0...60] + " ..." if id.length > 60
+    return res if id.empty?
+    return mismatch(id, hsh, Hash, mth, lvl, res) unless hsh.is_a?(Hash)
+    return res if hsh.key?(key)
+    msg  = "'#{id}' Hash: no key '#{key}' (#{mth})"
+    lvl = lvl.to_i unless lvl.is_a?(Integer)
+    log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
+    res
+  end
+
+  ##
+  # Log template 'empty (uninitialized)' message and return user-set object.
+  #
+  # @param id [String] empty object identifier
+  # @param mth [String] calling method identifier
+  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
+  # @param res [Object] what to return (optional)
+  #
+  # @return [Object] res if specified by user
+  # @return [Nil] nil if return object is invalid
+  def empty(id = "", mth = "", lvl = DEBUG, res = nil)
+    return nil unless defined?(res)
+    return res unless defined?(id ) && id
+    return res unless defined?(mth) && mth
+    return res unless defined?(lvl) && lvl
+    mth = mth.to_s.strip
+    mth = mth[0...60] + " ..." if mth.length > 60
+    return res if mth.empty?
+    id = id.to_s.strip
+    id = id[0...60] + " ..." if id.length > 60
+    return res if id.empty?
+    msg  = "Empty '#{id}' (#{mth})"
+    lvl = lvl.to_i unless lvl.is_a?(Integer)
+    log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
+    res
+  end
+
+  ##
+  # Log template 'near zero' message and return user-set object.
+  #
+  # @param id [String] empty object identifier
+  # @param mth [String] calling method identifier
+  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
+  # @param res [Object] what to return (optional)
+  #
+  # @return [Object] res if specified by user
+  # @return [Nil] nil if return object is invalid
+  def zero(id = "", mth = "", lvl = DEBUG, res = nil)
+    return nil unless defined?(res)
+    return res unless defined?(id ) && id
+    return res unless defined?(mth) && mth
+    return res unless defined?(lvl) && lvl
+    mth = mth.to_s.strip
+    mth = mth[0...60] + " ..." if mth.length > 60
+    return res if mth.empty?
+    id = id.to_s.strip
+    id = id[0...60] + " ..." if id.length > 60
+    return res if id.empty?
+    msg  = "'#{id}' ~zero (#{mth})"
+    lvl = lvl.to_i unless lvl.is_a?(Integer)
+    log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
+    res
+  end
+
+  ##
+  # Log template 'negative' message and return user-set object.
+  #
+  # @param id [String] empty object identifier
+  # @param mth [String] calling method identifier
+  # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
+  # @param res [Object] what to return (optional)
+  #
+  # @return [Object] res if specified by user
+  # @return [Nil] nil if return object is invalid
+  def negative(id = "", mth = "", lvl = DEBUG, res = nil)
+    return nil unless defined?(res)
+    return res unless defined?(id ) && id
+    return res unless defined?(mth) && mth
+    return res unless defined?(lvl) && lvl
+    mth = mth.to_s.strip
+    mth = mth[0...60] + " ..." if mth.length > 60
+    return res if mth.empty?
+    id = id.to_s.strip
+    id = id[0...60] + " ..." if id.length > 60
+    return res if id.empty?
+    msg  = "'#{id}' negative (#{mth})"
+    lvl = lvl.to_i unless lvl.is_a?(Integer)
+    log(lvl, msg) if lvl >= DEBUG && lvl <= FATAL
+    res
+  end
+
+  ##
+  # Reset log status and entries.
+  #
+  # @return [Integer] current level
+  def clean!
+    @@status = 0
+    @@logs   = []
+    @@level
+  end
+
+  ##
+  # Callback when other modules extend OSlg
+  #
+  # @param base [Object] instance or class object
+  def self.extended(base)
+    base.send(:include, self)
+  end
+end

data/lib/oslg/version.rb

@@ -0,0 +1,33 @@
+# BSD 3-Clause License
+#
+# Copyright (c) 2022, Denis Bourgeois
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+#    list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module OSlg
+  VERSION = "0.2.2".freeze
+end

data/lib/oslg.rb

@@ -0,0 +1,37 @@
+# BSD 3-Clause License
+#
+# Copyright (c) 2022, Denis Bourgeois
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+#    list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+begin # try to load from the gem
+  require "oslg/oslog"
+  require "oslg/version"
+rescue LoadError
+  require_relative "oslg/oslog"
+  require_relative "oslg/version"
+end

data/oslg.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "oslg/version"
+
+Gem::Specification.new do |s|
+  # Specify which files should be added to the gem when it is released.
+  # "git ls-files -z" loads files in the RubyGem that have been added into git.
+  s.files                 = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  s.name                  = "oslg"
+  s.version               = OSlg::VERSION
+  s.license               = "BSD-3-Clause"
+  s.summary               = "OpenStudio SDK logger"
+  s.description           = "For SDK users who select what's logged where."
+  s.authors               = ["Denis Bourgeois"]
+  s.email                 = ["denis@rd2.ca"]
+  s.platform              = Gem::Platform::RUBY
+  s.homepage              = "https://github.com/rd2/oslg"
+  s.bindir                = "exe"
+  s.require_paths         = ["lib"]
+  s.executables           = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  s.required_ruby_version = [">= 2.5.0", "< 2.7.3"]
+  s.metadata              = {}
+
+  s.add_development_dependency "bundler", "~> 2.1"
+  s.add_development_dependency "rake",    "~> 13.0"
+  s.add_development_dependency "rspec",   "~> 3.11"
+  s.add_development_dependency "yard",    "~> 0.9"
+
+  s.metadata["homepage_uri"]    = s.homepage
+  s.metadata["source_code_uri"] = "#{s.homepage}/tree/v#{s.version}"
+  s.metadata["bug_tracker_uri"] = "#{s.homepage}/issues"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: oslg
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- Denis Bourgeois
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: For SDK users who select what's logged where.
+email:
+- denis@rd2.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/pull_request.yml"
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/oslg.rb
+- lib/oslg/oslog.rb
+- lib/oslg/version.rb
+- oslg.gemspec
+homepage: https://github.com/rd2/oslg
+licenses:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://github.com/rd2/oslg
+  source_code_uri: https://github.com/rd2/oslg/tree/v0.2.2
+  bug_tracker_uri: https://github.com/rd2/oslg/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 2.7.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.15
+signing_key:
+specification_version: 4
+summary: OpenStudio SDK logger
+test_files: []