pantheios-ruby 0.20.2 → 0.22.0.2

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.
Files changed (34) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +31 -0
  3. data/README.md +5 -0
  4. data/examples/coloured_console_log_service.rb +37 -0
  5. data/examples/multiple_modules.md +204 -0
  6. data/examples/multiple_modules.rb +132 -0
  7. data/examples/simple_logging.md +65 -0
  8. data/examples/simple_logging.rb +37 -0
  9. data/examples/threshold_front_end.rb +48 -0
  10. data/lib/pantheios.rb +3 -2
  11. data/lib/pantheios/api.rb +23 -6
  12. data/lib/pantheios/application_layer.rb +2 -1
  13. data/lib/pantheios/application_layer/param_name_list.rb +9 -0
  14. data/lib/pantheios/application_layer/stock_severity_levels.rb +99 -31
  15. data/lib/pantheios/core.rb +55 -24
  16. data/lib/pantheios/front_ends/threshold_front_end.rb +148 -0
  17. data/lib/pantheios/globals.rb +20 -9
  18. data/lib/pantheios/services/coloured_console_log_service.rb +204 -0
  19. data/lib/pantheios/services/common/console.rb +92 -0
  20. data/lib/pantheios/services/multiplexing_log_service.rb +42 -3
  21. data/lib/pantheios/services/null_log_service.rb +3 -2
  22. data/lib/pantheios/services/simple_console_log_service.rb +4 -3
  23. data/lib/pantheios/services/simple_file_log_service.rb +3 -4
  24. data/lib/pantheios/services/standard_log_service_adapter.rb +3 -2
  25. data/lib/pantheios/util/process_util.rb +3 -3
  26. data/lib/pantheios/util/reflection_util.rb +3 -0
  27. data/lib/pantheios/util/thread_util.rb +2 -0
  28. data/lib/pantheios/util/version_util.rb +1 -0
  29. data/lib/pantheios/version.rb +3 -2
  30. data/test/unit/application_layer/tc_stock_severity_levels.rb +67 -0
  31. data/test/unit/front_ends/tc_threshold_front_end.rb +102 -0
  32. data/test/unit/front_ends/ts_all.rb +12 -0
  33. data/test/unit/services/tc_multiplexing_log_service.rb +4 -4
  34. metadata +21 -7
@@ -0,0 +1,148 @@
1
+
2
+ # ######################################################################## #
3
+ # File: lib/pantheios/front_ends/threshold_front_end.rb
4
+ #
5
+ # Purpose: Definition of the ::Pantheios::FrontEnds::ThresholdFrontEnd
6
+ # class
7
+ #
8
+ # Created: 3rd June 2020
9
+ # Updated: 4th June 2020
10
+ #
11
+ # Home: http://github.com/synesissoftware/Pantheios-Ruby
12
+ #
13
+ # Author: Matthew Wilson
14
+ #
15
+ # Copyright (c) 2020, Matthew Wilson and Synesis Information Systems
16
+ # All rights reserved.
17
+ #
18
+ # Redistribution and use in source and binary forms, with or without
19
+ # modification, are permitted provided that the following conditions are
20
+ # met:
21
+ #
22
+ # * Redistributions of source code must retain the above copyright
23
+ # notice, this list of conditions and the following disclaimer.
24
+ #
25
+ # * Redistributions in binary form must reproduce the above copyright
26
+ # notice, this list of conditions and the following disclaimer in the
27
+ # documentation and/or other materials provided with the distribution.
28
+ #
29
+ # * Neither the names of the copyright holder nor the names of its
30
+ # contributors may be used to endorse or promote products derived from
31
+ # this software without specific prior written permission.
32
+ #
33
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
34
+ # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
35
+ # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
36
+ # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
37
+ # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
38
+ # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
39
+ # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
40
+ # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
41
+ # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
42
+ # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
43
+ # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44
+ #
45
+ # ######################################################################## #
46
+
47
+
48
+ =begin
49
+ =end
50
+
51
+ require 'pantheios/application_layer/stock_severity_levels'
52
+
53
+ module Pantheios
54
+ module FrontEnds
55
+
56
+ # A class that fulfils the Pantheios *FrontEnd* protocol that implements
57
+ # +severity_logged?+ based on a threshold specified to the initialiser
58
+ #
59
+ # NOTE: The *FrontEnd* protocol is implemented by a class that provides
60
+ # the instance method +severity_logged?(severity : Object)+
61
+ class ThresholdFrontEnd
62
+
63
+ # Initialises the instance
64
+ #
65
+ # === Signature
66
+ #
67
+ # * *Parameters:*
68
+ # - +threshold_severity+ [ ::Symbol ] The threshold severity
69
+ #
70
+ # * *Options:*
71
+ # - +value_lookup_map+ [ ::Hash ] A map that is used to lookup
72
+ # +severity+ values (that are not +::Integer+) in
73
+ # +severity_logged?+. May be +nil+, in which case
74
+ # +::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES+
75
+ # is used
76
+ #
77
+ # * *Exceptions:*
78
+ # - +::TypeError+ raised if a value given for +:value_lookup_map+ is
79
+ # not a ::hash
80
+ def initialize(threshold_severity, **options)
81
+
82
+ m = options[:value_lookup_map]
83
+
84
+ raise TypeError, "value given for :value_lookup_map must be a #{::Hash}" if m && !m.respond_to?(:to_hash)
85
+
86
+ if m
87
+
88
+ @value_lookup_map = m
89
+ @relativity_lookup_map = ::Hash.new(:relative)
90
+ else
91
+
92
+ @value_lookup_map = ::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES
93
+ @relativity_lookup_map = ::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVELS_RELATIVE
94
+ end
95
+
96
+ self.threshold = threshold_severity
97
+ end
98
+
99
+ # Determines whether a given severity is logged
100
+ #
101
+ # === Signature
102
+ #
103
+ # * *Parameters:*
104
+ # - +severity+:: The severity level, which should be a known log
105
+ # severity symbol or an integral equivalent
106
+ #
107
+ # * *Returns:*
108
+ # a +truey+ value if the severity should be logged; a +falsey+ value
109
+ # otherwise
110
+ def severity_logged? severity
111
+
112
+ case severity
113
+ when ::Integer
114
+
115
+ v = severity
116
+ else
117
+
118
+ v = @value_lookup_map[severity] or warn "unknown severity level '#{severity}' (#{severity.class})"
119
+ end
120
+
121
+ return true if v.nil?
122
+
123
+ v <= @threshold_v
124
+ end
125
+
126
+ # assigns the threshold
127
+ #
128
+ # * *Parameters:*
129
+ # - +threshold_severity+ [ ::Symbol ] The threshold severity
130
+ def threshold=(threshold_severity)
131
+
132
+ raise TypeError, "threshold_severity must be a #{::Symbol}" unless ::Symbol === threshold_severity
133
+
134
+ @threshold_v = @value_lookup_map[threshold_severity] if @relativity_lookup_map[threshold_severity] or raise ArgumentError, "unknown threshold severity level '#{threshold_severity}' (#{threshold_severity.class})"
135
+ @threshold = threshold_severity
136
+
137
+ nil
138
+ end
139
+ attr_reader :threshold
140
+
141
+ end # class ThresholdFrontEnd
142
+
143
+ end # module FrontEnds
144
+ end # module Pantheios
145
+
146
+ # ############################## end of file ############################# #
147
+
148
+
@@ -5,12 +5,13 @@
5
5
  # Purpose: The Pantheios.Ruby "globals" (::Pantheios::Globals)
6
6
  #
7
7
  # Created: 24th December 2017
8
- # Updated: 4th February 2018
8
+ # Updated: 3rd June 2020
9
9
  #
10
10
  # Home: http://github.com/synesissoftware/Pantheios-Ruby
11
11
  #
12
12
  # Author: Matthew Wilson
13
13
  #
14
+ # Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
14
15
  # Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
15
16
  # All rights reserved.
16
17
  #
@@ -57,6 +58,18 @@ module Pantheios
57
58
  #
58
59
  # === Variables
59
60
  #
61
+ # * *HAS_CASCADED_INCLUDES* [boolean] Determines whether including
62
+ # +::Pantheios+ also includes all relevant parts of subordinate
63
+ # namespaces. See the documentation for the +::Pantheios+ namespace for
64
+ # further details
65
+ #
66
+ # * *INITIAL_SERVICE_CLASSES* [ svc-class, [ svc-class ] ] Specifies
67
+ # the service class(es) that will be used to create the initial service
68
+ # instance. Ignored if INITIAL_SERVICE_INSTANCES specifies an instance
69
+ #
70
+ # * *INITIAL_SERVICE_INSTANCES* [ svc-instance, [ svc-instance ] ] Specifies
71
+ # the initial service instance
72
+ #
60
73
  # * *MAIN_THREAD_NAME* A string specifying the main thread name, or an array
61
74
  # containing a thread instance and a string specifying the thread and its
62
75
  # name
@@ -65,11 +78,6 @@ module Pantheios
65
78
  # form is used then the first initialising thread of Pantheios.Ruby will
66
79
  # be the named thread
67
80
  #
68
- # * *HAS_CASCADED_INCLUDES* [boolean] Determines whether including
69
- # +::Pantheios+ also includes all relevant parts of subordinate
70
- # namespaces. See the documentation for the +::Pantheios+ namespace for
71
- # further details
72
- #
73
81
  # * *PROCESS_NAME* A string specifying the process name, or one of the
74
82
  # recognised symbols - :script, :script_basename, :script_dirname,
75
83
  # :script_realpath, :script_stem - that directs inference of the process
@@ -81,7 +89,8 @@ module Pantheios
81
89
  #
82
90
  module Globals
83
91
 
84
- module Internals_
92
+ # @!visibility private
93
+ module Internals_ # :nodoc: all
85
94
 
86
95
  BOOLEAN_CLASSES = [ ::FalseClass, ::TrueClass ]
87
96
  TRUTHY_CLASSES = BOOLEAN_CLASSES + [ ::NilClass ]
@@ -89,7 +98,8 @@ module Globals
89
98
  PROCESS_NAME_CLASSES = [ ::Symbol, ::String ]
90
99
  end
91
100
 
92
- module Helpers_
101
+ # @!visibility private
102
+ module Helpers_ # :nodoc: all
93
103
 
94
104
  def self.cattr receiver, name, types, initial_value, **options
95
105
 
@@ -138,7 +148,8 @@ module Globals
138
148
 
139
149
  Helpers_.cattr self, 'SYNCHRONISED_SEVERITY_LOGGED', nil, true, boolean: true
140
150
 
141
- def self.included receiver
151
+ # @!visibility private
152
+ def self.included receiver # :nodoc:
142
153
 
143
154
  abort "Attempt to include #{self} into #{receiver}. This is not allowed"
144
155
  end
@@ -0,0 +1,204 @@
1
+
2
+ # ######################################################################## #
3
+ # File: lib/pantheios/services/coloured_console_log_service.rb
4
+ #
5
+ # Purpose: Definition of the
6
+ # ::Pantheios::Services::ColouredConsoleLogService class
7
+ #
8
+ # Created: 19th June 2019
9
+ # Updated: 4th June 2020
10
+ #
11
+ # Home: http://github.com/synesissoftware/Pantheios-Ruby
12
+ #
13
+ # Author: Matthew Wilson
14
+ #
15
+ # Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
16
+ # Copyright (c) 2019, Matthew Wilson and Synesis Software
17
+ # All rights reserved.
18
+ #
19
+ # Redistribution and use in source and binary forms, with or without
20
+ # modification, are permitted provided that the following conditions are
21
+ # met:
22
+ #
23
+ # * Redistributions of source code must retain the above copyright
24
+ # notice, this list of conditions and the following disclaimer.
25
+ #
26
+ # * Redistributions in binary form must reproduce the above copyright
27
+ # notice, this list of conditions and the following disclaimer in the
28
+ # documentation and/or other materials provided with the distribution.
29
+ #
30
+ # * Neither the names of the copyright holder nor the names of its
31
+ # contributors may be used to endorse or promote products derived from
32
+ # this software without specific prior written permission.
33
+ #
34
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
35
+ # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
36
+ # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
37
+ # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
38
+ # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
39
+ # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
40
+ # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
41
+ # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
42
+ # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
43
+ # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
44
+ # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
45
+ #
46
+ # ######################################################################## #
47
+
48
+
49
+ require 'pantheios/services/common/console'
50
+
51
+ =begin
52
+ =end
53
+
54
+ module Pantheios
55
+ module Services
56
+
57
+ # A class that fulfils the Pantheios *LogService* protocol that allows all
58
+ # severities and logs to the console (via +$stdout+ and +$stderr+)
59
+ #
60
+ # NOTE: The *LogService* protocol is implemented by a class that provides
61
+ # the instance methods +severity_logged?(severity : Object) : boolean+ and
62
+ # +log(severity : Object, t : Time, prefix : String|Array, msg : String)+
63
+ class ColouredConsoleLogService
64
+
65
+ module Constants
66
+
67
+ include ::Pantheios::Services::Common::Console::AnsiEscapeSequences
68
+ end # module Constants
69
+
70
+ def self.requires_prefix?
71
+
72
+ return @requires_prefix unless @requires_prefix.nil?
73
+
74
+ @requires_prefix = ::Pantheios::Services::Common::Console::Internal_::SHOULD_COLOURIZE_ ? :parts : false
75
+ end
76
+
77
+ def requires_prefix?
78
+
79
+ self.class.requires_prefix?
80
+ end
81
+
82
+ def severity_logged? severity
83
+
84
+ true
85
+ end
86
+
87
+ def log sev, t, pref, msg
88
+
89
+ stm = infer_stream sev
90
+
91
+ if requires_prefix?
92
+
93
+ pref = pref.map do |part|
94
+
95
+ bg = Constants::Background
96
+ fg = Constants::Foreground
97
+
98
+ if part.respond_to?(:severity)
99
+
100
+ part = fg.bold part
101
+
102
+ case sev
103
+ when :violation
104
+
105
+ part = bg.red part
106
+ #part = fg.bright_magenta part
107
+ part = fg.bright_yellow part
108
+ part = fg.blinking part
109
+ when :alert
110
+
111
+ part = bg.red part
112
+ part = fg.bright_cyan part
113
+ part = fg.blinking part
114
+ when :critical
115
+
116
+ part = bg.red part
117
+ part = fg.white part
118
+ when :failure
119
+
120
+ part = bg.yellow part
121
+ part = fg.red part
122
+ when :warning
123
+
124
+ part = bg.yellow part
125
+ part = fg.blue part
126
+ when :notice
127
+
128
+ part = bg.dark_grey part
129
+ part = fg.white part
130
+ when :informational
131
+
132
+ part = bg.dark_grey part
133
+ part = fg.light_grey part
134
+ when :debug0
135
+
136
+ part = bg.blue part
137
+ part = fg.light_grey part
138
+ when :debug1
139
+
140
+ part = bg.blue part
141
+ part = fg.light_grey part
142
+ when :debug2
143
+
144
+ part = bg.blue part
145
+ part = fg.light_grey part
146
+ when :debug3
147
+
148
+ part = bg.blue part
149
+ part = fg.light_grey part
150
+ when :debug4
151
+
152
+ part = bg.blue part
153
+ part = fg.light_grey part
154
+ when :debug5
155
+
156
+ part = bg.blue part
157
+ part = fg.light_grey part
158
+ when :trace
159
+
160
+ part = bg.blue part
161
+ part = fg.light_grey part
162
+ when :benchmark
163
+
164
+ part = bg.black part
165
+ part = fg.light_grey part
166
+ else
167
+
168
+ ;
169
+ end
170
+ else
171
+
172
+ part = fg.dark_grey part
173
+ end
174
+
175
+ part
176
+ end.join(', ')
177
+
178
+ pref = '[' + pref + ']: '
179
+
180
+ #pref = pref.map { |pp| pp.severity? ? map_sev_(sev) : sev }.join(
181
+ end
182
+
183
+ stm.puts "#{pref}#{msg}"
184
+ end
185
+
186
+ # Overrideable method that determines which stream to write, based on a
187
+ # severity. This implementation always returns +$stderr+
188
+ #
189
+ # Overrides must return an object that supports the +puts(String)+
190
+ # method
191
+ def infer_stream sev
192
+
193
+ $stderr
194
+ end
195
+
196
+ private
197
+ end # class ColouredConsoleLogService
198
+
199
+ end # module Services
200
+ end # module Pantheios
201
+
202
+ # ############################## end of file ############################# #
203
+
204
+
@@ -0,0 +1,92 @@
1
+
2
+ module Pantheios
3
+ module Services
4
+ module Common
5
+
6
+ module Console
7
+
8
+ module Internal_
9
+
10
+ STDERR_ISATTY_ = $stderr.isatty
11
+ OS_IS_UNIX_ = %w{
12
+
13
+ darwin
14
+ freebsd
15
+ linux
16
+ mingw32
17
+ solaris
18
+ sunos
19
+ }.any? { |os| RUBY_PLATFORM =~ /#{os.downcase}/ }
20
+ SHOULD_COLOURIZE_ = STDERR_ISATTY_ && OS_IS_UNIX_
21
+
22
+ module ColourInitialiser
23
+
24
+ def self.extended other
25
+
26
+ other::COLOURS.each do |name, value|
27
+
28
+ other.const_set(name.to_s.upcase, value)
29
+
30
+ if SHOULD_COLOURIZE_
31
+
32
+ other.define_singleton_method(name) { |s| "\x1B[#{value}m#{s}\x1B[0m" }
33
+ else
34
+
35
+ other.define_singleton_method(name) { |s| s }
36
+ end
37
+ end
38
+ end
39
+ end # module ColourInitialiser
40
+ end # module Internal_
41
+
42
+ module AnsiEscapeSequences
43
+
44
+ module Foreground
45
+
46
+ COLOURS = {
47
+
48
+ blinking: 5,
49
+ bold: 1,
50
+ default: 39,
51
+
52
+ black: 30,
53
+ red: 31,
54
+ green: 32,
55
+ yellow: 33,
56
+ blue: 34,
57
+ magenta: 35,
58
+ cyan: 36,
59
+ light_grey: 37,
60
+
61
+ dark_grey: 90,
62
+ bright_red: 91,
63
+ bright_green: 92,
64
+ bright_yellow: 93,
65
+ bright_blue: 94,
66
+ bright_magenta: 95,
67
+ bright_cyan: 96,
68
+ white: 97,
69
+ }
70
+
71
+ extend Internal_::ColourInitialiser
72
+ end # module Foreground
73
+
74
+ module Background
75
+
76
+ COLOURS = Hash[Foreground::COLOURS.reject { |k, v| [ :blinking, :bold, :default ].include? k }.map { |k, v| [ k, 10 + v ] }]
77
+
78
+ extend Internal_::ColourInitialiser
79
+ end # module Background
80
+
81
+ module Special
82
+
83
+ # TODO
84
+
85
+ end # module Special
86
+ end # end AnsiEscapeSequences
87
+
88
+ end # module Console
89
+ end # module Common
90
+ end # module Services
91
+ end # module Pantheios
92
+