pantheios-ruby 0.20.2 → 0.22.0.2

Sign up to get free protection for your applications and to get access to all the features.
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
+