gloo 7.2 → 7.3

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 (78) hide show
  1. checksums.yaml +4 -4
  2. data/docs/application.md +19 -3
  3. data/docs/iterators.md +66 -1
  4. data/docs/language_objects.md +14 -7
  5. data/docs/language_scripting.md +17 -0
  6. data/docs/language_syntax.md +86 -3
  7. data/docs/objects.md +6 -6
  8. data/docs/operators.md +36 -2
  9. data/docs/plugins.md +26 -0
  10. data/docs/testing.md +31 -2
  11. data/docs/verbs.md +8 -0
  12. data/lib/VERSION +1 -1
  13. data/lib/VERSION_NOTES +15 -0
  14. data/lib/gloo/app/engine.rb +133 -17
  15. data/lib/gloo/app/prompt.rb +8 -0
  16. data/lib/gloo/convert/string_to_decimal.rb +3 -6
  17. data/lib/gloo/convert/string_to_integer.rb +3 -2
  18. data/lib/gloo/core/dictionary.rb +23 -12
  19. data/lib/gloo/core/obj.rb +77 -0
  20. data/lib/gloo/core/op.rb +99 -0
  21. data/lib/gloo/core/parser.rb +15 -0
  22. data/lib/gloo/core/tokens.rb +18 -0
  23. data/lib/gloo/core/verb.rb +130 -1
  24. data/lib/gloo/exec/dispatch.rb +7 -3
  25. data/lib/gloo/exec/runaway_recursion.rb +34 -0
  26. data/lib/gloo/exec/runner.rb +46 -0
  27. data/lib/gloo/exec/script.rb +16 -2
  28. data/lib/gloo/expr/expression.rb +77 -6
  29. data/lib/gloo/expr/l_decimal.rb +18 -2
  30. data/lib/gloo/expr/l_integer.rb +5 -2
  31. data/lib/gloo/expr/op_div.rb +4 -0
  32. data/lib/gloo/expr/op_eq.rb +4 -0
  33. data/lib/gloo/expr/op_gt.rb +4 -0
  34. data/lib/gloo/expr/op_gteq.rb +4 -0
  35. data/lib/gloo/expr/op_ineq.rb +4 -0
  36. data/lib/gloo/expr/op_lt.rb +4 -0
  37. data/lib/gloo/expr/op_lteq.rb +4 -0
  38. data/lib/gloo/expr/op_minus.rb +4 -0
  39. data/lib/gloo/expr/op_mult.rb +3 -7
  40. data/lib/gloo/expr/op_plus.rb +8 -1
  41. data/lib/gloo/objs/basic/alias.rb +6 -1
  42. data/lib/gloo/objs/basic/boolean.rb +15 -6
  43. data/lib/gloo/objs/basic/decimal.rb +25 -3
  44. data/lib/gloo/objs/basic/script.rb +3 -1
  45. data/lib/gloo/objs/basic/string_msgs.rb +50 -68
  46. data/lib/gloo/objs/ctrl/until.rb +219 -0
  47. data/lib/gloo/plugin/callback.rb +54 -10
  48. data/lib/gloo/plugin/ext_manager.rb +44 -0
  49. data/lib/gloo/plugin/lib_manager.rb +65 -1
  50. data/lib/gloo/shell/runner.rb +36 -9
  51. data/lib/gloo/verbs/break.rb +6 -4
  52. data/lib/gloo/verbs/check.rb +8 -2
  53. data/lib/gloo/verbs/create.rb +13 -4
  54. data/lib/gloo/verbs/if.rb +33 -10
  55. data/lib/gloo/verbs/invoke.rb +6 -1
  56. data/lib/gloo/verbs/list.rb +9 -2
  57. data/lib/gloo/verbs/load.rb +4 -1
  58. data/lib/gloo/verbs/move.rb +8 -2
  59. data/lib/gloo/verbs/put.rb +9 -2
  60. data/lib/gloo/verbs/reload.rb +2 -1
  61. data/lib/gloo/verbs/run.rb +8 -1
  62. data/lib/gloo/verbs/save.rb +4 -0
  63. data/lib/gloo/verbs/tell.rb +9 -2
  64. data/lib/gloo/verbs/unless.rb +34 -10
  65. data/lib/gloo/verbs/unload.rb +81 -16
  66. data/test.gloo/ctrl/until.test.gloo +100 -0
  67. data/test.gloo/lang/computed_paths.test.gloo +98 -0
  68. data/test.gloo/lang/literal.test.gloo +43 -0
  69. data/test.gloo/lang/ops.test.gloo +193 -0
  70. data/test.gloo/lang/runaway_recursion.test.gloo +44 -0
  71. data/test.gloo/objs/decimal.test.gloo +23 -0
  72. data/test.gloo/objs/string.test.gloo +30 -0
  73. data/test.gloo/verbs/create.test.gloo +6 -21
  74. data/test.gloo/verbs/if.test.gloo +41 -0
  75. data/test.gloo/verbs/load.test.gloo +4 -3
  76. data/test.gloo/verbs/unless.test.gloo +40 -0
  77. data/test.gloo/verbs/unload.test.gloo +61 -3
  78. metadata +6 -1
@@ -11,6 +11,12 @@ module Gloo
11
11
  KEYWORD = 'decimal'.freeze
12
12
  KEYWORD_SHORT = 'num'.freeze
13
13
 
14
+ # A fixed-point spec in a format string, eg. %.2f or %8.2f; the
15
+ # precision (digits after the point) is captured, if given.
16
+ FIXED_SPEC = /%[-+ 0#]*\d*(?:\.(\d+))?[fF]/
17
+ # sprintf's precision for %f when none is given.
18
+ DEFAULT_PRECISION = 6
19
+
14
20
  #
15
21
  # The name of the object type.
16
22
  #
@@ -83,7 +89,7 @@ module Gloo
83
89
  if @params&.token_count&.positive?
84
90
  expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
85
91
  fmt = expr.evaluate
86
- formatted = format( fmt, value )
92
+ formatted = format( fmt, rounded_for( fmt ) )
87
93
  else
88
94
  whole, frac = value.to_s.split( '.' )
89
95
  grouped = whole.reverse.scan( /.{1,3}/ ).join( ',' ).reverse
@@ -92,6 +98,21 @@ module Gloo
92
98
  @engine.heap.it.set_to formatted
93
99
  end
94
100
 
101
+ #
102
+ # The value to format: for a fixed-point spec (%.2f), rounded to
103
+ # its precision first, the way round does (halves away from zero),
104
+ # so format and round always agree. sprintf alone works on the
105
+ # binary value, and gives '%.2f' of 1.005 as 1.00. Other specs
106
+ # (%e, %d, ...) get the value as it is.
107
+ #
108
+ def rounded_for( fmt )
109
+ spec = FIXED_SPEC.match( fmt.to_s )
110
+ return value unless spec
111
+
112
+ precision = spec[ 1 ] ? spec[ 1 ].to_i : DEFAULT_PRECISION
113
+ return value.round( precision )
114
+ end
115
+
95
116
  # ---------------------------------------------------------------------
96
117
  # Object Documentation
97
118
  # ---------------------------------------------------------------------
@@ -106,8 +127,9 @@ module Gloo
106
127
  :description => 'A decimal (numeric) value.',
107
128
  :messages => [
108
129
  'round ({precision}) — Round to the nearest whole value. If ' \
109
- 'an optional parameter is included, round to the precision specified.',
110
- 'format ({fmt}) — With no parameter, adds comma separators to the whole part (e.g. 1000.5 -> 1,000.5). With a parameter, uses it as a sprintf-style format string (e.g. \'%.2f\'). It will have the formatted string.'
130
+ 'an optional parameter is included, round to the precision specified. ' \
131
+ 'A half rounds away from zero: 2.5 -> 3, -2.5 -> -3, and 2.675 to 2 places -> 2.68.',
132
+ 'format ({fmt}) — With no parameter, adds comma separators to the whole part (e.g. 1000.5 -> 1,000.5). With a parameter, uses it as a sprintf-style format string (e.g. \'%.2f\'); for a fixed-point spec like %.2f the value is rounded first, as round does, so the two always agree (1.005 -> 1.01). It will have the formatted string.'
111
133
  ],
112
134
  :notes => 'A value that isn\'t a number (eg. \'x\' or \'1,5\') is used as a best guess, with a warning: "\'1,5\' is not a decimal number; using 1.0." A blank value is 0.0.',
113
135
  :examples => <<~EXAMPLES.strip
@@ -115,7 +115,9 @@ module Gloo
115
115
  :name => KEYWORD,
116
116
  :shortcut => KEYWORD_SHORT,
117
117
  :description => 'An executable script — a set of commands to ' \
118
- 'be run. A command line may end with an inline `# ...` ' \
118
+ 'be run. A single command can go on the same line, after the ' \
119
+ ':, as in done [script] : eval x > 100; more go on the lines ' \
120
+ 'below. A command line may end with an inline `# ...` ' \
119
121
  'comment; it is ignored when the line runs but kept when ' \
120
122
  'the file is saved.',
121
123
  :messages => [
@@ -41,7 +41,7 @@ module Gloo
41
41
  'starts_with? ({str}) — Check if the string starts with the given string. A parameter is required: the string to look for at the beginning of this string. It will have a boolean.',
42
42
  'ends_with? ({str}) — Check if the string ends with the given string. A parameter is required: the string to look for at the end of this string. It will have a boolean.',
43
43
  'substring? ({str}) — Check if the string includes the given sub-string. A parameter is required: the string to look for in this string. It will have a boolean.',
44
- 'index_of ({needle} {from}) — Find the 0-based position of the first occurrence of {needle} at or after position {from}. The {needle} parameter is required; {from} is optional and defaults to 0. Does not change the value of the string. It will have the position, or -1 if {needle} is not found; an out-of-range {from} (negative, or past the end of the string) is an error, and it will have false.',
44
+ 'index_of ({needle} {from}) — Find the 0-based position of the first occurrence of {needle} at or after position {from}. The {needle} parameter is required; {from} is optional and defaults to 0. Either can be a group: index_of ( \'o\' ( n + 1 ) ). Does not change the value of the string. It will have the position, or -1 if {needle} is not found; an out-of-range {from} (negative, or past the end of the string) is an error, and it will have false.',
45
45
  'format_for_html — Format this string for HTML output. Tabs, spaces and returns are converted to HTML elements. The value of the string is changed. It will have the formatted string.',
46
46
  'encode64 — Base64 encode the string. This message changes the value of the string. It will have the encoded string.',
47
47
  'decode64 — Decode the string from Base64. This message changes the value of the string. It will have the decoded string.',
@@ -52,12 +52,12 @@ module Gloo
52
52
  'gen_hex ({len}) — Set the value of the string to a newly generated, random hex string. The {len} parameter is optional; the length is 10 if not specified. This message changes the value of the string.',
53
53
  'gen_base64 ({len}) — Set the value of the string to a newly generated, random base64 string. The {len} parameter is optional; the length is 12 if not specified. This message changes the value of the string.',
54
54
  'trim — Strip whitespace from the beginning and end of the string. This message changes the value of the string. It will have the trimmed string.',
55
- 'sub ({from} {to}) — Substitute the first occurrence of {from} with {to}. Both parameters are required. This message changes the value of the string. It will have the result.',
56
- 'gsub ({from} {to}) — Substitute all occurrences of {from} with {to}. Both parameters are required. This message changes the value of the string. It will have the result.',
57
- 'split ({from} {to}) — Get the substring from index {from} up to (not including) index {to}. Indexes are 0-based; out-of-range indexes are clamped to the start or end of the string. Both parameters are required. Does not change the value of the string. It will have the substring.',
55
+ 'sub ({from} {to}) — Substitute the first occurrence of {from} with {to}. Both parameters are required. Either can be a group: sub ( ( \'a\' + \'b\' ) \'x\' ). This message changes the value of the string. It will have the result.',
56
+ 'gsub ({from} {to}) — Substitute all occurrences of {from} with {to}. Both parameters are required. Either can be a group: gsub ( \' \' ( \'_\' + \'_\' ) ). This message changes the value of the string. It will have the result.',
57
+ 'split ({from} {to}) — Get the substring from index {from} up to (not including) index {to}. Indexes are 0-based; out-of-range indexes are clamped to the start or end of the string. Both parameters are required. Either can be a group: split ( n ( n + 3 ) ). Does not change the value of the string. It will have the substring.',
58
58
  'splitl ({index}) — Get the substring to the left of index {index} (same as split (0, {index})). A parameter is required. Does not change the value of the string. It will have the substring.',
59
59
  'splitr ({index}) — Get the substring from index {index} to the end of the string (same as split ({index}, size)). A parameter is required. Does not change the value of the string. It will have the substring.',
60
- 'split_list ({delim} {dst.path}) — Split the string by {delim} and put the parts into children of the container at {dst.path} (or an alias that points to one), one part per child, in order. Existing children are matched by position and have their values set; extra parts get new (untyped) children, numbered from 1; extra existing children are left alone. Both parameters are required. Does not change the value of the string. It will be true (also when the string is empty), or false if a parameter or the target is bad.',
60
+ 'split_list ({delim} {dst.path}) — Split the string by {delim} and put the parts into children of the container at {dst.path} (or an alias that points to one), one part per child, in order. Existing children are matched by position and have their values set; extra parts get new (untyped) children, numbered from 1; extra existing children are left alone. Both parameters are required. {delim} can be a group; {dst.path} in parentheses is a computed path: split_list ( \',\' ( \'parts.\' n ) ). Does not change the value of the string. It will be true (also when the string is empty), or false if a parameter or the target is bad.',
61
61
  'word_wrap ({width}) — Word-wrap the string to {width} columns, breaking on whitespace (never mid-word; an overlong word is left on its own line rather than broken). The {width} parameter is optional; it defaults to the terminal\'s current width. This message changes the value of the string. It will have the wrapped string.',
62
62
  'page — Show the value in a pager (less), for viewing long content a screen at a time.'
63
63
  ]
@@ -119,22 +119,18 @@ module Gloo
119
119
  #
120
120
  def msg_sub
121
121
  return @engine.heap.it.set_to( '' ) unless value
122
- if @params&.token_count&.positive?
123
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
124
- from = expr.evaluate
125
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.last ] )
126
- to = expr.evaluate
122
+ return false unless params_given?( 2 )
127
123
 
128
- result = value.sub(from, to)
129
- @engine.heap.it.set_to result
130
- set_value(result)
131
- return result
132
- else
133
- # Error
134
- @engine.syntax_err MISSING_PARAM_MSG
135
- @engine.heap.it.set_to false
136
- return false
137
- end
124
+ from, ok = param_value( 0 )
125
+ return false unless ok
126
+
127
+ to, ok = param_value( 1 )
128
+ return false unless ok
129
+
130
+ result = value.sub( from.to_s, to.to_s )
131
+ @engine.heap.it.set_to result
132
+ set_value( result )
133
+ return result
138
134
  end
139
135
 
140
136
  #
@@ -143,23 +139,18 @@ module Gloo
143
139
  #
144
140
  def msg_gsub
145
141
  return @engine.heap.it.set_to( '' ) unless value
142
+ return false unless params_given?( 2 )
146
143
 
147
- if @params&.token_count&.positive?
148
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
149
- from = expr.evaluate
150
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.last ] )
151
- to = expr.evaluate
144
+ from, ok = param_value( 0 )
145
+ return false unless ok
152
146
 
153
- result = value.gsub(from, to)
154
- @engine.heap.it.set_to result
155
- set_value(result)
156
- return result
157
- else
158
- # Error
159
- @engine.syntax_err MISSING_PARAM_MSG
160
- @engine.heap.it.set_to false
161
- return false
162
- end
147
+ to, ok = param_value( 1 )
148
+ return false unless ok
149
+
150
+ result = value.gsub( from.to_s, to.to_s )
151
+ @engine.heap.it.set_to result
152
+ set_value( result )
153
+ return result
163
154
  end
164
155
 
165
156
  #
@@ -169,22 +160,17 @@ module Gloo
169
160
  #
170
161
  def msg_split
171
162
  return @engine.heap.it.set_to( '' ) unless value
163
+ return false unless params_given?( 2 )
172
164
 
173
- if @params&.token_count&.positive?
174
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
175
- from = expr.evaluate.to_i
176
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.last ] )
177
- to = expr.evaluate.to_i
165
+ from, ok = param_value( 0 )
166
+ return false unless ok
178
167
 
179
- result = clamped_substring( from, to )
180
- @engine.heap.it.set_to result
181
- return result
182
- else
183
- # Error
184
- @engine.syntax_err MISSING_PARAM_MSG
185
- @engine.heap.it.set_to false
186
- return false
187
- end
168
+ to, ok = param_value( 1 )
169
+ return false unless ok
170
+
171
+ result = clamped_substring( from.to_i, to.to_i )
172
+ @engine.heap.it.set_to result
173
+ return result
188
174
  end
189
175
 
190
176
  #
@@ -245,17 +231,16 @@ module Gloo
245
231
  #
246
232
  def msg_split_list
247
233
  return @engine.heap.it.set_to( true ) unless value
234
+ return false unless params_given?( 2 )
248
235
 
249
- if @params&.token_count.to_i < 2
250
- @engine.syntax_err MISSING_PARAM_MSG
251
- @engine.heap.it.set_to false
252
- return false
253
- end
236
+ delim, ok = param_value( 0 )
237
+ return false unless ok
254
238
 
255
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
256
- delim = expr.evaluate
239
+ # The target is a path; a group works out to a computed path.
240
+ path = param_path( 1 )
241
+ return false unless path
257
242
 
258
- target = split_list_target( @params.tokens.last )
243
+ target = split_list_target( path )
259
244
  return false unless target
260
245
 
261
246
  parts = value.split( delim )
@@ -298,20 +283,17 @@ module Gloo
298
283
  # into 'it'. Does not change the string's value.
299
284
  #
300
285
  def msg_index_of
301
- unless @params&.token_count&.positive?
302
- @engine.syntax_err MISSING_PARAM_MSG
303
- @engine.heap.it.set_to false
304
- return false
305
- end
286
+ return false unless params_given?( 1 )
306
287
 
307
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
308
- needle = expr.evaluate.to_s
288
+ needle, ok = param_value( 0 )
289
+ return false unless ok
309
290
 
310
291
  from = 0
311
- if @params.token_count > 1
312
- expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.last ] )
313
- from = expr.evaluate.to_i
292
+ if param_groups.length > 1
293
+ from, ok = param_value( 1 )
294
+ return false unless ok
314
295
  end
296
+ from = from.to_i
315
297
 
316
298
  str = value.to_s
317
299
  if from.negative? || from > str.length
@@ -320,7 +302,7 @@ module Gloo
320
302
  return false
321
303
  end
322
304
 
323
- result = str.index( needle, from ) || -1
305
+ result = str.index( needle.to_s, from ) || -1
324
306
  @engine.heap.it.set_to result
325
307
  return result
326
308
  end
@@ -0,0 +1,219 @@
1
+ # Author:: Eric Crane (mailto:eric.crane@mac.com)
2
+ # Copyright:: Copyright (c) 2026 Eric Crane. All rights reserved.
3
+ #
4
+ # A looping construct...do something until a condition is true.
5
+ #
6
+
7
+ module Gloo
8
+ module Objs
9
+ class Until < Gloo::Core::Obj
10
+
11
+ KEYWORD = 'until'.freeze
12
+ KEYWORD_SHORT = 'until'.freeze
13
+ DO = 'do'.freeze
14
+ DONE = 'done'.freeze
15
+ INDEX = 'index'.freeze
16
+ MAX = 'max'.freeze
17
+ NO_DONE_ERR = 'Could not run until loop %s: it has no done script.'.freeze
18
+ MAX_ERR = "Could not finish until loop %s: done wasn't true after %s passes.".freeze
19
+
20
+ #
21
+ # The name of the object type.
22
+ #
23
+ def self.typename
24
+ return KEYWORD
25
+ end
26
+
27
+ #
28
+ # The short name of the object type.
29
+ #
30
+ def self.short_typename
31
+ return KEYWORD_SHORT
32
+ end
33
+
34
+ #
35
+ # The most passes to run, or nil for no limit. A missing max, or
36
+ # one that isn't a positive number, is no limit.
37
+ #
38
+ def max
39
+ value = find_child_value( MAX )
40
+ return nil unless value.is_a?( ::Integer ) && value.positive?
41
+
42
+ return value
43
+ end
44
+
45
+ #
46
+ # Set the index of the current pass, if there is an index child.
47
+ #
48
+ def set_index( index )
49
+ o = find_child INDEX
50
+ return unless o
51
+
52
+ o.set_value index
53
+ end
54
+
55
+ #
56
+ # Run the do script once. Returns true if a break loop in it
57
+ # ended the run, so the loop should stop. A plain break ends only
58
+ # the do script, and the loop goes on.
59
+ #
60
+ def run_do
61
+ o = find_child DO
62
+ return false unless o
63
+
64
+ Gloo::Exec::Dispatch.message( @engine, 'run', o )
65
+ return o.respond_to?( :broke_loop? ) && o.broke_loop?
66
+ end
67
+
68
+ #
69
+ # Run the done script, and say whether the loop is done: its
70
+ # result (in it) by the [bool] rule. Nil if anything in it
71
+ # reported an error: the answer can't be known, so the loop stops.
72
+ #
73
+ def run_done( done )
74
+ errors_before = @engine.run_error_count
75
+ Gloo::Exec::Dispatch.message( @engine, 'run', done )
76
+ return nil if @engine.run_error_count > errors_before
77
+
78
+ return Gloo::Objs::Boolean.to_bool( @engine, @engine.heap.it.value )
79
+ end
80
+
81
+ # ---------------------------------------------------------------------
82
+ # Children
83
+ # ---------------------------------------------------------------------
84
+
85
+ #
86
+ # Does this object have children to add when an object
87
+ # is created in interactive mode?
88
+ # This does not apply during obj load, etc.
89
+ #
90
+ def add_children_on_create?
91
+ return true
92
+ end
93
+
94
+ #
95
+ # Add children to this object: just the do and done scripts.
96
+ # index and max are optional.
97
+ #
98
+ def add_default_children
99
+ fac = @engine.factory
100
+ fac.create_script DO, '', self
101
+ fac.create_script DONE, '', self
102
+ end
103
+
104
+ # ---------------------------------------------------------------------
105
+ # Messages
106
+ # ---------------------------------------------------------------------
107
+
108
+ #
109
+ # Get a list of message names that this object receives.
110
+ #
111
+ def self.messages
112
+ return super + [ 'run' ]
113
+ end
114
+
115
+ #
116
+ # Run the loop: do, then done, until done is true. Stops early on
117
+ # break loop in do, or an error in done; with a max, reaching it
118
+ # is an error.
119
+ #
120
+ def msg_run
121
+ done = find_child DONE
122
+ return fail_with( format( NO_DONE_ERR, pn ) ) if blank_script?( done )
123
+
124
+ limit = max
125
+ pass = 0
126
+ loop do
127
+ set_index pass
128
+ return if run_do
129
+
130
+ finished = run_done( done )
131
+ # nil: done reported an error, already reported.
132
+ return @engine.heap.it.set_to( false ) if finished.nil?
133
+ return if finished
134
+
135
+ pass += 1
136
+ return fail_with( format( MAX_ERR, pn, limit ) ) if limit && pass >= limit
137
+ end
138
+ end
139
+
140
+ # ---------------------------------------------------------------------
141
+ # Private functions
142
+ # ---------------------------------------------------------------------
143
+
144
+ private
145
+
146
+ #
147
+ # Is the script missing, or without a line to run?
148
+ #
149
+ def blank_script?( script )
150
+ return true if script.nil?
151
+
152
+ lines = Array( script.value )
153
+ return lines.all? { |line| line.to_s.strip.empty? }
154
+ end
155
+
156
+ #
157
+ # Report that the loop couldn't run or finish; it is false.
158
+ #
159
+ def fail_with( msg )
160
+ @engine.err msg
161
+ @engine.heap.it.set_to false
162
+ end
163
+
164
+ # ---------------------------------------------------------------------
165
+ # Object Documentation
166
+ # ---------------------------------------------------------------------
167
+
168
+ #
169
+ # Get the object's documentation data.
170
+ #
171
+ def self.doc_data
172
+ {
173
+ :name => KEYWORD,
174
+ :shortcut => KEYWORD_SHORT,
175
+ :description => 'Run a script again and again until a condition ' \
176
+ 'is true. Each pass runs do, then done; the loop ends when ' \
177
+ "done's result is true. do always runs at least once.",
178
+ :children => [
179
+ 'do (script) — The action to perform on each pass.',
180
+ "done (script) — Required. Run after each pass; the loop ends when its result (it) is true. Usually one line: done [script] : eval ^^.x > 100. True and false follow the [bool] rule (see doc language_syntax, What Counts as True).",
181
+ 'index (integer) — Optional. The current pass, counting from 0.',
182
+ 'max (integer) — Optional. The most passes to run. Without it (or with 0) there is no limit, and a loop whose done never comes true runs until stopped.'
183
+ ],
184
+ :messages => [
185
+ 'run — Run the loop until done is true.'
186
+ ],
187
+ :errors => [
188
+ "#{format( NO_DONE_ERR, '{path}' )} — There is no done script, or it is blank. Nothing runs, and it is false.",
189
+ "#{format( MAX_ERR, '{path}', '{max}' )} — max passes ran and done never came true. it is false.",
190
+ 'Any error in done ends the loop: whether it is done can\'t be known. it is false. An error in do doesn\'t; the next pass may work.'
191
+ ],
192
+ :notes => 'break in do skips the rest of the pass; break loop ends the loop (see doc iterators, Skipping an Item or Ending a Loop). done is checked after each pass, so do always runs at least once.',
193
+ :examples => <<~EXAMPLES.strip
194
+ count [can] :
195
+ x [int] : 0
196
+ up [until] :
197
+ do [script] : tell count.x to inc
198
+ done [script] : eval count.x > 100
199
+ on_load [script] :
200
+ tell count.up to run
201
+ show count.x
202
+
203
+ retry [can] :
204
+ tries [int] : 0
205
+ pick [until] :
206
+ max [int] : 5
207
+ index [int] :
208
+ do [script] : tell retry.tries to inc
209
+ done [script] : eval retry.tries = 3
210
+ on_load [script] :
211
+ tell retry.pick to run
212
+ show retry.pick.index
213
+ EXAMPLES
214
+ }
215
+ end
216
+
217
+ end
218
+ end
219
+ end
@@ -1,33 +1,77 @@
1
- #
1
+ #
2
2
  # A mechanism for registering extension components.
3
- #
3
+ #
4
+ # Each library or extension registers through its own callback, which
5
+ # remembers what it registered, so the library can be unloaded later:
6
+ # its verbs and object types taken out of the dictionary again.
7
+ #
4
8
  module Gloo
5
9
  module Plugin
6
10
  class Callback
7
11
 
8
- #
12
+ attr_reader :verbs, :objs
13
+
14
+ #
9
15
  # Initialize the callback.
10
- #
16
+ #
11
17
  def initialize( engine )
12
18
  @engine = engine
19
+ @verbs = []
20
+ @objs = []
13
21
  end
14
22
 
15
- #
23
+ #
16
24
  # Register a verb.
17
- #
25
+ #
18
26
  def register_verb( verb_class )
19
27
  @engine.log.debug "Registering verb: #{verb_class} from callback helper"
28
+ @verbs << verb_class
20
29
  @engine.dictionary.register_verb_post_start( verb_class, @engine )
21
30
  end
22
31
 
23
- #
32
+ #
24
33
  # Register an object.
25
- #
34
+ #
26
35
  def register_obj( object_class )
27
36
  @engine.log.debug "Registering object: #{object_class} from callback helper"
37
+ @objs << object_class
28
38
  @engine.dictionary.register_obj_post_start( object_class, @engine )
29
39
  end
30
-
40
+
41
+ #
42
+ # Take everything this callback registered out of the dictionary.
43
+ # The Ruby classes stay loaded (Ruby can't un-require), but gloo
44
+ # decides what exists from the dictionary, so they're gone.
45
+ #
46
+ def unregister
47
+ @verbs.each { |v| @engine.dictionary.unregister_verb( v ) }
48
+ @objs.each { |o| @engine.dictionary.unregister_obj( o ) }
49
+ end
50
+
51
+ #
52
+ # The objects on the heap whose type is one this callback
53
+ # registered (or a subclass of one), in the order they're found.
54
+ #
55
+ def objects_in_use
56
+ found = []
57
+ each_obj( @engine.heap.root ) do |obj|
58
+ found << obj if @objs.any? { |klass| obj.is_a?( klass ) }
59
+ end
60
+ return found
61
+ end
62
+
63
+ private
64
+
65
+ #
66
+ # Call the block with every object below the given one.
67
+ #
68
+ def each_obj( parent, &block )
69
+ parent.children.each do |child|
70
+ block.call( child )
71
+ each_obj( child, &block )
72
+ end
73
+ end
74
+
31
75
  end
32
76
  end
33
- end
77
+ end
@@ -12,12 +12,16 @@ module Gloo
12
12
  # Constants for extension management
13
13
  EXT_FILE = '_ext.rb'
14
14
 
15
+ IN_USE_ERR = "Could not unload extension '%s': objects of its types are on the heap (%s).".freeze
16
+
15
17
  #
16
18
  # Set up the extension manager.
17
19
  #
18
20
  def initialize( engine )
19
21
  @engine = engine
20
22
  @extensions = {}
23
+ # What each extension registered (its Callback), for unloading.
24
+ @registrations = {}
21
25
  @engine.log.debug 'extension manager initialized...'
22
26
  end
23
27
 
@@ -82,12 +86,52 @@ module Gloo
82
86
  plugin_class = Object.const_get( class_name )
83
87
  inst = plugin_class.new
84
88
  ext_cb = Callback.new( @engine )
89
+ @registrations[ name ] = ext_cb
85
90
  inst.register( ext_cb )
86
91
  rescue NameError
87
92
  @engine.err "Could not find class '#{class_name}' in extension file '#{full_path}'."
88
93
  end
89
94
  end
90
95
 
96
+
97
+ #
98
+ # Unload the extension of the given name: take its verbs and
99
+ # object types out of the dictionary, and forget it's loaded. The
100
+ # Ruby code stays loaded, so load_ext registers it again. Not
101
+ # done, and an error, while objects of its types are on the heap.
102
+ # Unloading an extension that isn't loaded does nothing.
103
+ # Returns false if it couldn't be unloaded, true otherwise.
104
+ #
105
+ def unload_ext( name )
106
+ unless @extensions.key?( name )
107
+ @engine.log.info "Extension #{name} isn't loaded."
108
+ return true
109
+ end
110
+
111
+ cb = @registrations[ name ]
112
+ in_use = cb ? cb.objects_in_use : []
113
+ unless in_use.empty?
114
+ @engine.err format( IN_USE_ERR, name, in_use.map( &:pn ).join( ', ' ) )
115
+ return false
116
+ end
117
+
118
+ cb&.unregister
119
+ @registrations.delete( name )
120
+ @extensions.delete( name )
121
+ @engine.log.debug "Extension unloaded: #{name}"
122
+ return true
123
+ end
124
+
125
+
126
+ #
127
+ # Unload every extension, as for a session reset. Called with the
128
+ # heap already emptied, so no object of an extension's types can
129
+ # stop it.
130
+ #
131
+ def unload_all
132
+ @extensions.keys.each { |name| unload_ext( name ) }
133
+ end
134
+
91
135
  end
92
136
  end
93
137
  end