gloo 7.1.3 → 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 (109) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +23 -0
  3. data/docs/application.md +65 -4
  4. data/docs/development.md +10 -0
  5. data/docs/iterators.md +66 -1
  6. data/docs/language_objects.md +34 -22
  7. data/docs/language_scripting.md +23 -2
  8. data/docs/language_syntax.md +86 -3
  9. data/docs/objects.md +6 -6
  10. data/docs/operators.md +36 -2
  11. data/docs/plugins.md +26 -0
  12. data/docs/testing.md +35 -9
  13. data/docs/verbs.md +31 -3
  14. data/lib/VERSION +1 -1
  15. data/lib/VERSION_NOTES +23 -0
  16. data/lib/dependencies.rb +4 -1
  17. data/lib/gloo/app/engine.rb +151 -23
  18. data/lib/gloo/app/prompt.rb +8 -0
  19. data/lib/gloo/convert/string_to_decimal.rb +3 -6
  20. data/lib/gloo/convert/string_to_integer.rb +3 -2
  21. data/lib/gloo/core/dictionary.rb +23 -12
  22. data/lib/gloo/core/obj.rb +77 -23
  23. data/lib/gloo/core/op.rb +99 -0
  24. data/lib/gloo/core/parser.rb +15 -0
  25. data/lib/gloo/core/tokens.rb +18 -0
  26. data/lib/gloo/core/verb.rb +130 -1
  27. data/lib/gloo/exec/dispatch.rb +7 -3
  28. data/lib/gloo/exec/runaway_recursion.rb +34 -0
  29. data/lib/gloo/exec/runner.rb +46 -0
  30. data/lib/gloo/exec/script.rb +16 -2
  31. data/lib/gloo/expr/expression.rb +77 -6
  32. data/lib/gloo/expr/l_decimal.rb +18 -2
  33. data/lib/gloo/expr/l_integer.rb +5 -2
  34. data/lib/gloo/expr/op_div.rb +4 -0
  35. data/lib/gloo/expr/op_eq.rb +4 -0
  36. data/lib/gloo/expr/op_gt.rb +4 -0
  37. data/lib/gloo/expr/op_gteq.rb +4 -0
  38. data/lib/gloo/expr/op_ineq.rb +4 -0
  39. data/lib/gloo/expr/op_lt.rb +4 -0
  40. data/lib/gloo/expr/op_lteq.rb +4 -0
  41. data/lib/gloo/expr/op_minus.rb +4 -0
  42. data/lib/gloo/expr/op_mult.rb +3 -7
  43. data/lib/gloo/expr/op_plus.rb +8 -1
  44. data/lib/gloo/objs/basic/alias.rb +6 -1
  45. data/lib/gloo/objs/basic/boolean.rb +15 -6
  46. data/lib/gloo/objs/basic/decimal.rb +25 -3
  47. data/lib/gloo/objs/basic/script.rb +3 -24
  48. data/lib/gloo/objs/basic/string_msgs.rb +50 -68
  49. data/lib/gloo/objs/ctrl/until.rb +219 -0
  50. data/lib/gloo/persist/declaration_ledger.rb +9 -9
  51. data/lib/gloo/persist/declaration_writer.rb +208 -0
  52. data/lib/gloo/persist/disc_mech.rb +70 -39
  53. data/lib/gloo/persist/file_loader.rb +125 -66
  54. data/lib/gloo/persist/file_saver.rb +130 -198
  55. data/lib/gloo/persist/file_storage.rb +15 -4
  56. data/lib/gloo/persist/file_style.rb +89 -0
  57. data/lib/gloo/persist/line_splitter.rb +16 -1
  58. data/lib/gloo/persist/persist_man.rb +112 -30
  59. data/lib/gloo/persist/save_index.rb +211 -0
  60. data/lib/gloo/persist/script_body_collector.rb +16 -21
  61. data/lib/gloo/persist/source/blank_node.rb +10 -3
  62. data/lib/gloo/persist/source/comment_node.rb +10 -2
  63. data/lib/gloo/persist/source/directive_node.rb +10 -2
  64. data/lib/gloo/persist/source/obj_node.rb +174 -9
  65. data/lib/gloo/persist/source/source_doc.rb +54 -0
  66. data/lib/gloo/persist/subtree_extractor.rb +9 -37
  67. data/lib/gloo/persist/trivia_buffer.rb +7 -7
  68. data/lib/gloo/plugin/callback.rb +54 -10
  69. data/lib/gloo/plugin/ext_manager.rb +44 -0
  70. data/lib/gloo/plugin/lib_manager.rb +65 -1
  71. data/lib/gloo/shell/runner.rb +36 -9
  72. data/lib/gloo/verbs/break.rb +6 -4
  73. data/lib/gloo/verbs/check.rb +8 -2
  74. data/lib/gloo/verbs/create.rb +13 -4
  75. data/lib/gloo/verbs/if.rb +33 -10
  76. data/lib/gloo/verbs/invoke.rb +6 -1
  77. data/lib/gloo/verbs/list.rb +9 -2
  78. data/lib/gloo/verbs/load.rb +31 -22
  79. data/lib/gloo/verbs/move.rb +50 -5
  80. data/lib/gloo/verbs/put.rb +9 -2
  81. data/lib/gloo/verbs/reload.rb +2 -1
  82. data/lib/gloo/verbs/run.rb +8 -1
  83. data/lib/gloo/verbs/save.rb +30 -4
  84. data/lib/gloo/verbs/tell.rb +9 -2
  85. data/lib/gloo/verbs/unless.rb +34 -10
  86. data/lib/gloo/verbs/unload.rb +81 -16
  87. data/test.gloo/app/exit_status.test.gloo +34 -0
  88. data/test.gloo/app/fixtures/exit_after_error.gloo +9 -0
  89. data/test.gloo/ctrl/until.test.gloo +100 -0
  90. data/test.gloo/lang/computed_paths.test.gloo +98 -0
  91. data/test.gloo/lang/declaration.test.gloo +36 -0
  92. data/test.gloo/lang/fixtures/mixed_indent.gloo +5 -0
  93. data/test.gloo/lang/literal.test.gloo +43 -0
  94. data/test.gloo/lang/naming.test.gloo +44 -6
  95. data/test.gloo/lang/ops.test.gloo +193 -0
  96. data/test.gloo/lang/runaway_recursion.test.gloo +44 -0
  97. data/test.gloo/objs/decimal.test.gloo +23 -0
  98. data/test.gloo/objs/string.test.gloo +30 -0
  99. data/test.gloo/verbs/create.test.gloo +6 -21
  100. data/test.gloo/verbs/fixtures/load_beside.gloo +6 -0
  101. data/test.gloo/verbs/fixtures/lossless_text.gloo +7 -0
  102. data/test.gloo/verbs/fixtures/lossless_text_saved.gloo +9 -0
  103. data/test.gloo/verbs/if.test.gloo +41 -0
  104. data/test.gloo/verbs/load.test.gloo +22 -3
  105. data/test.gloo/verbs/move.test.gloo +39 -0
  106. data/test.gloo/verbs/save.test.gloo +239 -0
  107. data/test.gloo/verbs/unless.test.gloo +40 -0
  108. data/test.gloo/verbs/unload.test.gloo +61 -3
  109. metadata +15 -1
@@ -31,6 +31,7 @@ module Gloo
31
31
  QUIT_NAME = 'quit'.freeze
32
32
  QUIT_DESCRIPTION = 'Quit the application'.freeze
33
33
  QUIT_METHOD = 'cmd_quit'.freeze
34
+ QUIT_HINT = "Use 'quit' to leave.".freeze
34
35
 
35
36
  #
36
37
  # Initialize the shell runner.
@@ -296,22 +297,48 @@ module Gloo
296
297
  def repl
297
298
  setup_completion
298
299
 
299
- while !@context.done && ( line = Readline.readline( prompt, true ) )
300
+ until @context.done
301
+ line = read_line
302
+ next if line == :interrupted
303
+ break unless line
304
+
300
305
  tokens = line.strip.split( ' ' )
301
306
  if tokens.empty?
302
307
  handle_empty_command
303
308
  next
304
309
  end
305
310
 
306
- result = traverse( @root, tokens )
311
+ # Ctrl-C stops the command and comes back to this prompt.
312
+ @engine.run_interruptible { run_tokens( tokens ) }
313
+ end
314
+ end
307
315
 
308
- if result[ :node ]
309
- run_before_action
310
- execute_command( result[ :node ], tokens, result[ :parent ] )
311
- run_after_action
312
- else
313
- handle_unknown_command
314
- end
316
+ #
317
+ # Read a line at the prompt: nil at the end of input, or
318
+ # :interrupted if Ctrl-C dropped the line (with the hint, if
319
+ # nothing had been typed).
320
+ #
321
+ def read_line
322
+ return Readline.readline( prompt, true )
323
+ rescue Interrupt
324
+ typed = Readline.respond_to?( :line_buffer ) ? Readline.line_buffer.to_s : ''
325
+ @engine.interrupted_at_prompt( typed, @include_quit ? QUIT_HINT : nil )
326
+ return :interrupted
327
+ end
328
+
329
+ #
330
+ # Find and run the command for the given tokens, with the before
331
+ # and after actions.
332
+ #
333
+ def run_tokens( tokens )
334
+ result = traverse( @root, tokens )
335
+
336
+ if result[ :node ]
337
+ run_before_action
338
+ execute_command( result[ :node ], tokens, result[ :parent ] )
339
+ run_after_action
340
+ else
341
+ handle_unknown_command
315
342
  end
316
343
  end
317
344
 
@@ -65,12 +65,14 @@ module Gloo
65
65
  end
66
66
 
67
67
  #
68
- # Is the object the do script of a loop (a repeat or an each)?
68
+ # Is the object the do script of a loop (a repeat, an each or an
69
+ # until)?
69
70
  #
70
71
  def loop_do?( obj )
71
72
  parent = obj&.parent
72
73
  return false unless parent.is_a?( Gloo::Objs::Repeat ) ||
73
- parent.is_a?( Gloo::Objs::Each )
74
+ parent.is_a?( Gloo::Objs::Each ) ||
75
+ parent.is_a?( Gloo::Objs::Until )
74
76
 
75
77
  return parent.find_child( Gloo::Objs::Each::DO ).equal?( obj )
76
78
  end
@@ -114,8 +116,8 @@ module Gloo
114
116
  :syntax => [ 'break', 'break loop' ],
115
117
  :parameters => [
116
118
  'loop — Optional. Also end the loop whose do script this is. ' \
117
- 'Only valid directly in a loop\'s do script (repeat, or any ' \
118
- 'kind of each).'
119
+ 'Only valid directly in a loop\'s do script (repeat, until, ' \
120
+ 'or any kind of each).'
119
121
  ],
120
122
  :result => 'No more commands are executed in the currently ' \
121
123
  'running script. If there are other scripts in the stack, ' \
@@ -18,6 +18,8 @@ module Gloo
18
18
  # Run the verb.
19
19
  #
20
20
  def run
21
+ return unless take_path_arg( 1 )
22
+
21
23
  msg = @tokens.after_token( FOR )
22
24
 
23
25
  unless msg
@@ -67,10 +69,14 @@ module Gloo
67
69
  'state while tell is used to trigger an action. Using the ' \
68
70
  'verb that matches intent makes the code read like ' \
69
71
  'natural communication.',
70
- :syntax => [ 'check {path.to.object} for {condition_message}' ],
72
+ :syntax => [
73
+ 'check {path.to.object} for {condition_message}',
74
+ 'check ( {expression} ) for {condition_message}'
75
+ ],
71
76
  :parameters => [
72
77
  '{path.to.object} — The object that we want to send a condition_message to.',
73
- '{message} — The condition_message to send.'
78
+ '{message} — The condition_message to send.',
79
+ Gloo::Core::Verb::COMPUTED_PATH_DOC
74
80
  ],
75
81
  :result => 'The result depends on the message that is sent, but ' \
76
82
  'by convention the result of the check will be in it.',
@@ -15,13 +15,15 @@ module Gloo
15
15
  NO_NAME_ERR = 'Object name is missing!'.freeze
16
16
  BAD_NAME_CHARS = /[()"']/.freeze
17
17
  BAD_NAME_ERR = "'%s' isn't a name! To create an object at a " \
18
- 'computed path, put the path into an alias, then create ' \
19
- 'the alias: create slot* as string.'.freeze
18
+ 'computed path, put the whole path in parentheses: ' \
19
+ "create ( 'list.' n ) as string.".freeze
20
20
 
21
21
  #
22
22
  # Run the verb.
23
23
  #
24
24
  def run
25
+ return @engine.heap.it.set_to( false ) unless take_path_arg( 1 )
26
+
25
27
  name = @tokens.second
26
28
  type = @tokens.after_token( AS )
27
29
  value = @tokens.after_token( VAL )
@@ -109,12 +111,16 @@ module Gloo
109
111
  :shortcut => KEYWORD_SHORT,
110
112
  :description => 'Create a new object of given type with given ' \
111
113
  'value. Both type and value are optional when creating an object.',
112
- :syntax => [ 'create {new.object.path} as {type} : {value}' ],
114
+ :syntax => [
115
+ 'create {new.object.path} as {type} : {value}',
116
+ 'create ( {expression} ) as {type} : {value}'
117
+ ],
113
118
  :parameters => [
114
119
  '{new.object.path} — The path and name of the new object. ' \
115
120
  'Like any path, it can start from the root, from here in ' \
116
121
  'a script (^.box.new, ^^.new), or from the context (@.new).',
117
122
  '{type} — The type of the new object. Optional; if not provided the object will be untyped.',
123
+ Gloo::Core::Verb::COMPUTED_PATH_DOC,
118
124
  "{value} — The initial value for the new object. Optional; if not provided the object will have the default value for the type."
119
125
  ],
120
126
  :result => "If nothing exists at the path, a new object is " \
@@ -126,7 +132,7 @@ module Gloo
126
132
  :errors => [
127
133
  "#{NO_NAME_ERR} — The name of the object was not specified and the object cannot be created.",
128
134
  "Could not create '{path}': Object '{parent.path}' was not found. — The parent container named in the path does not exist. Every container above the new object must already exist. Nothing is created, and it is false.",
129
- "#{format( BAD_NAME_ERR, '{name}' )} — The name has parentheses or quotes, or there are extra words between the name and as / : — create takes a name as written. Nothing is created, and it is false."
135
+ "#{format( BAD_NAME_ERR, '{name}' )} — The name has quotes or a stray parenthesis, or there are extra words between the name and as / : — a name is taken as written; to compute one, put the whole path in parentheses. Nothing is created, and it is false."
130
136
  ],
131
137
  :examples => <<~EXAMPLES.strip
132
138
  # Basic examples of creating an object from the gloo shell:
@@ -134,6 +140,9 @@ module Gloo
134
140
  > create s : "abc"
135
141
  > create t
136
142
 
143
+ # Create at a path worked out at runtime:
144
+ > create ( 'list.' n ) as string
145
+
137
146
  # Example of creating an object with an alias:
138
147
  a [can] :
139
148
  ln [alias] : x
data/lib/gloo/verbs/if.rb CHANGED
@@ -27,8 +27,13 @@ module Gloo
27
27
 
28
28
  @then = @tokens.expr_after( SEPARATORS, ELSE )
29
29
  @else = @tokens.expr_after( ELSE )
30
+ give_params_to_last_part
30
31
 
31
- if evals_true( value )
32
+ truth = evals_true( value )
33
+ # A condition that reported an error abandons the line.
34
+ return if truth.nil?
35
+
36
+ if truth
32
37
  run_then
33
38
  else
34
39
  run_else unless @else.blank?
@@ -55,6 +60,23 @@ module Gloo
55
60
 
56
61
  private
57
62
 
63
+ #
64
+ # A trailing ( ... ) the parser split off the line belongs to the
65
+ # command at the end of it (eg. show's colour in
66
+ # if x then show 'a' (red)): give it back to the else part if
67
+ # there is one, otherwise to the then part.
68
+ #
69
+ def give_params_to_last_part
70
+ return unless @params.respond_to?( :cmd )
71
+
72
+ group = " ( #{@params.cmd} )"
73
+ if !@else.blank?
74
+ @else += group
75
+ elsif !@then.blank?
76
+ @then += group
77
+ end
78
+ end
79
+
58
80
  #
59
81
  # Get the list of tokens that represent the parameters
60
82
  # of the if command.
@@ -72,18 +94,14 @@ module Gloo
72
94
  end
73
95
 
74
96
  #
75
- # Does the given value evalute to true?
97
+ # Does the given value evalute to true? The [bool] rule decides
98
+ # (see Boolean.to_bool). Nil if working it out reported an error.
76
99
  #
77
100
  def evals_true( value )
78
- eval_result = false
79
- if value.count.positive?
80
- expr = Gloo::Expr::Expression.new( @engine, value )
81
- result = expr.evaluate
82
- eval_result = true if result == true
83
- eval_result = true if result.is_a?( Numeric ) && result != 0
84
- end
101
+ result, ok = evaluate_expr( value )
102
+ return nil unless ok
85
103
 
86
- return eval_result
104
+ return Gloo::Objs::Boolean.to_bool( @engine, result )
87
105
  end
88
106
 
89
107
  #
@@ -137,6 +155,11 @@ module Gloo
137
155
  "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
138
156
  'Other errors depend on the command that is run.'
139
157
  ],
158
+ :notes => 'What counts as true follows the [bool] rule: true, a ' \
159
+ 'number other than 0, and the text true or t are true; anything ' \
160
+ 'else is false (blank quietly, other text with a warning). See ' \
161
+ 'doc language_syntax, What Counts as True. A condition that ' \
162
+ 'reports an error abandons the line: neither command runs.',
140
163
  :examples => <<~EXAMPLES.strip
141
164
  #
142
165
  # If statement example
@@ -19,6 +19,8 @@ module Gloo
19
19
  # Run the verb.
20
20
  #
21
21
  def run
22
+ return unless take_path_arg( 1 )
23
+
22
24
  target = @tokens.token_count > 1 ? @tokens.second : nil
23
25
  arg_tokens = @tokens.token_count > 1 ? @tokens.params[ 1..-1 ] : []
24
26
 
@@ -53,12 +55,15 @@ module Gloo
53
55
  :description => 'Invoke a function. Set it to the result of the function.',
54
56
  :syntax => [
55
57
  'invoke {path.to.function} {params}',
58
+ 'invoke ( {expression} ) {params}',
56
59
  'invoke( {path.to.function} {params} ) — inline, usable inside any expression',
57
60
  '~>( {path.to.function} {params} ) — inline, shortcut spelling'
58
61
  ],
59
62
  :parameters => [
60
63
  '{path.to.function} — The function we want to invoke.',
61
- '{params} — The list of parameters to the function.'
64
+ '{params} — The list of parameters to the function.',
65
+ Gloo::Core::Verb::COMPUTED_PATH_DOC + ' Leave a space after invoke: invoke( … ) with no ' \
66
+ 'space is the inline call form.'
62
67
  ],
63
68
  :result => 'The result of the function is put into it; if ' \
64
69
  'anything goes wrong, it is false. The ' \
@@ -15,6 +15,8 @@ module Gloo
15
15
  # Run the verb.
16
16
  #
17
17
  def run
18
+ return unless take_path_arg( 1 )
19
+
18
20
  levels = determine_levels
19
21
  target = self.determine_target
20
22
  indent = self.determine_indent
@@ -185,9 +187,13 @@ module Gloo
185
187
  'setting is on, any listed object that has a doc (the ' \
186
188
  'comment block declared immediately above it in its source ' \
187
189
  'file) shows it too.',
188
- :syntax => [ 'list {path.to.object}' ],
190
+ :syntax => [
191
+ 'list {path.to.object}',
192
+ 'list ( {expression} )'
193
+ ],
189
194
  :parameters => [
190
- '{path.to.object} — Optional path to object that will be listed. When no path is provided, the current context is used.'
195
+ '{path.to.object} — Optional path to object that will be listed. When no path is provided, the current context is used.',
196
+ Gloo::Core::Verb::COMPUTED_PATH_DOC
191
197
  ],
192
198
  :result => 'Object and children are listed out in the CLI. ' \
193
199
  'Doc lines are included when the list_docs setting is on.',
@@ -198,6 +204,7 @@ module Gloo
198
204
  > list
199
205
  > list my.container
200
206
  > list root
207
+ > list ( 'app.' section )
201
208
  EXAMPLES
202
209
  }
203
210
  end
@@ -63,12 +63,15 @@ module Gloo
63
63
  return KEYWORD_SHORT
64
64
  end
65
65
 
66
- #
67
- # Load a gloo file
68
- #
66
+ #
67
+ # Load a gloo file. A relative name is looked for in the
68
+ # persist manager's search folders (next to this file, the
69
+ # app or projects folder, the gloo home).
70
+ #
69
71
  def load_gloo_file( fn )
70
72
  @engine.log.debug "Getting ready to load gloo file: #{fn}"
71
- @engine.persist_man.load fn
73
+ pm = @engine.persist_man
74
+ pm.load( fn, pm.search_folders )
72
75
  end
73
76
 
74
77
  #
@@ -98,16 +101,17 @@ module Gloo
98
101
  {
99
102
  :name => KEYWORD,
100
103
  :shortcut => KEYWORD_SHORT,
101
- :description => 'Load an object file. There are two ways to ' \
102
- 'specify the file. Give either the full path and file name ' \
103
- 'or use a relative path from the gloo project folder. For ' \
104
- 'the latter, the extension is not needed. For the former, ' \
105
- 'the file extension is necessary. Using * instead of a file ' \
106
- 'name will load all gloo files in the folder. When using the ' \
107
- '--app option, the file is loaded from the application ' \
108
- 'folder, but if not found there, the loader will also look ' \
109
- 'in the gloo root folder. The load verb is also used to ' \
110
- 'import an extension or library at runtime.',
104
+ :description => 'Load an object file. Give a full path, one ' \
105
+ 'starting with ~, or a relative name; the .gloo extension is ' \
106
+ 'optional. A relative name is looked for in a few places, in ' \
107
+ 'order. In App mode (--app): the app folder, then next to the ' \
108
+ 'file the loading script came from, then the gloo home. ' \
109
+ 'Otherwise: next to the loading file, then the projects ' \
110
+ 'folder (the project_path setting), then the gloo home. A ' \
111
+ 'command typed at the prompt has no file, so the working ' \
112
+ 'folder stands in for it. Using * instead of a file name ' \
113
+ 'loads all gloo files in the folder. The load verb is also ' \
114
+ 'used to import an extension or library at runtime.',
111
115
  :syntax => [
112
116
  'load {file_name}',
113
117
  'load ext {my_ext}',
@@ -116,11 +120,12 @@ module Gloo
116
120
  ],
117
121
  :parameters => [
118
122
  '{file_name} — Name of the object file that is to be loaded: ' \
119
- 'relative to the project, a full path, or starting with ~. ' \
123
+ 'a relative name (see the description for where it is ' \
124
+ 'looked for), a full path, or starting with ~. ' \
120
125
  'The .gloo extension is optional. ' \
121
- 'End it with * to load every .gloo file in a folder (a ' \
122
- 'folder in the project, a full path, or one starting with ' \
123
- '~); anything before the * is the start of the file names.',
126
+ 'End it with * to load every .gloo file in a folder, found ' \
127
+ 'the same way; the first place with matching files is ' \
128
+ 'used. Anything before the * is the start of the file names.',
124
129
  'reference type — By default, the type is file. File can be ' \
125
130
  'specified, but does not need to be. Use ext to load a ' \
126
131
  'User Extension. Use lib to load a Core Library.',
@@ -136,8 +141,8 @@ module Gloo
136
141
  "#{UNKNOWN_OPT_ERR} — The reference type given isn't file, ext, or lib.",
137
142
  "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name).",
138
143
  'File not found: {name} — The file name given could not be ' \
139
- 'resolved to a gloo file (checked as a full path, and ' \
140
- 'relative to the project and gloo root folders).'
144
+ 'resolved to a gloo file in any of the places it is ' \
145
+ 'looked for.'
141
146
  ],
142
147
  :notes => 'Several files can contribute to one container: ' \
143
148
  'declare it in each file and add different children, and ' \
@@ -154,9 +159,13 @@ module Gloo
154
159
  'check {obj} for doc, or see it inline in the object tree ' \
155
160
  'with list when the list_docs setting is on. When a name ' \
156
161
  'is declared in more than one loaded file, the first ' \
157
- 'non-empty doc wins, same as the first value.',
162
+ "non-empty doc wins, same as the first value.\n\n" \
163
+ 'A library or extension stays loaded until it is unloaded ' \
164
+ '(unload lib, unload ext); loading one that is already ' \
165
+ 'loaded does nothing.',
158
166
  :examples => <<~EXAMPLES.strip
159
- > load my/project/file
167
+ # Next to this file (or the app folder, in App mode)
168
+ > load parts/helpers
160
169
  > load my/app/*
161
170
  > load ~/.my_app/settings.gloo
162
171
  > load ~/.my_app/plugins/*
@@ -13,16 +13,27 @@ module Gloo
13
13
  TO = 'to'.freeze
14
14
  MISSING_SRC_ERR = 'Object to move was not specified!'.freeze
15
15
  MISSING_DST_ERR = "'Move' must include 'to' parent object!".freeze
16
+ NAME_TAKEN_ERR = "Could not move '%s': '%s' already has a child named '%s'.".freeze
17
+ INSIDE_ITSELF_ERR = "Could not move '%s': it can't go inside itself.".freeze
16
18
 
17
19
  #
18
20
  # Run the verb.
21
+ # A name is unique in its container, so an object can't move into
22
+ # one that already has a child with its name; nor can it move
23
+ # inside itself. Moving it to the parent it's already in does
24
+ # nothing.
19
25
  #
20
26
  def run
27
+ return unless take_path_arg( 1 ) && take_path_arg( TO )
28
+
21
29
  dst = lookup_dst
22
30
  return if dst.nil?
23
31
 
24
32
  o = lookup_obj
25
33
  return unless o
34
+ return if dst.equal?( o.parent )
35
+ return refuse( format( INSIDE_ITSELF_ERR, o.pn ) ) if inside?( dst, o )
36
+ return refuse( format( NAME_TAKEN_ERR, o.pn, dst.pn, o.name ) ) if dst.contains_child?( o.name )
26
37
 
27
38
  o.parent.remove_child o
28
39
  dst.add_child o
@@ -48,6 +59,28 @@ module Gloo
48
59
 
49
60
  private
50
61
 
62
+ #
63
+ # Report why the object can't be moved; nothing moves, and it is
64
+ # false.
65
+ #
66
+ def refuse( msg )
67
+ @engine.err msg
68
+ @engine.heap.it.set_to false
69
+ end
70
+
71
+ #
72
+ # Is dst the object itself, or somewhere under it?
73
+ #
74
+ def inside?( dst, obj )
75
+ o = dst
76
+ while o
77
+ return true if o.equal?( obj )
78
+
79
+ o = o.parent
80
+ end
81
+ return false
82
+ end
83
+
51
84
  #
52
85
  # Lookup the object that we're moving.
53
86
  #
@@ -97,18 +130,30 @@ module Gloo
97
130
  {
98
131
  :name => KEYWORD,
99
132
  :shortcut => KEYWORD_SHORT,
100
- :description => 'Move an object to a new parent.',
101
- :syntax => [ 'move {path.to.object} to {new.parent}' ],
133
+ :description => 'Move an object to a new parent. A name is unique ' \
134
+ 'in its container, so the new parent must not already have a ' \
135
+ 'child with the same name.',
136
+ :syntax => [
137
+ 'move {path.to.object} to {new.parent}',
138
+ 'move ( {expression} ) to ( {expression} )'
139
+ ],
102
140
  :parameters => [
103
141
  '{path.to.object} — The object that we want to move.',
104
- '{new.parent} — The new location for the object.'
142
+ '{new.parent} — The new location for the object.',
143
+ "#{Gloo::Core::Verb::COMPUTED_PATH_DOC} Either or both can be computed."
105
144
  ],
106
- :result => 'The object will now be in the new location.',
145
+ :result => 'The object will now be in the new location. Moving it ' \
146
+ 'to the parent it is already in does nothing. A pure action: it ' \
147
+ 'is left alone, unless the move is refused.',
107
148
  :errors => [
108
149
  "#{MISSING_SRC_ERR} The {path.to.object} is not specified.",
109
150
  "Object '{path.to.object}' was not found. — The {path.to.object} cannot be resolved.",
110
151
  "#{MISSING_DST_ERR} The {new.parent} is not specified.",
111
- "Object '{new.parent}' was not found. — The {new.parent} cannot be resolved."
152
+ "Object '{new.parent}' was not found. — The {new.parent} cannot be resolved.",
153
+ "#{format( NAME_TAKEN_ERR, '{path.to.object}', '{new.parent}', '{name}' )} — " \
154
+ 'The new parent already has a child with that name. Nothing moves, and it is false.',
155
+ "#{format( INSIDE_ITSELF_ERR, '{path.to.object}' )} — The new parent is the " \
156
+ 'object itself or something under it. Nothing moves, and it is false.'
112
157
  ],
113
158
  :examples => <<~EXAMPLES.strip
114
159
  can [can] :
@@ -18,6 +18,8 @@ module Gloo
18
18
  # Run the verb.
19
19
  #
20
20
  def run
21
+ return @engine.heap.it.set_to( false ) unless take_path_arg( INTO )
22
+
21
23
  value = fetch_value_tokens
22
24
  return @engine.heap.it.set_to( false ) if value.nil?
23
25
 
@@ -111,10 +113,14 @@ module Gloo
111
113
  :shortcut => KEYWORD_SHORT,
112
114
  :description => 'Put a value into an object. ' \
113
115
  'The value is the result of an expression.',
114
- :syntax => [ 'put {expression} into {dst.path}' ],
116
+ :syntax => [
117
+ 'put {expression} into {dst.path}',
118
+ 'put {expression} into ( {expression} )'
119
+ ],
115
120
  :parameters => [
116
121
  '{expression} — The expression that is evaluated.',
117
- '{dst.path} — The path to the destination object.'
122
+ '{dst.path} — The path to the destination object.',
123
+ Gloo::Core::Verb::COMPUTED_PATH_DOC
118
124
  ],
119
125
  :result => 'The destination object has the result of the ' \
120
126
  'evaluated expression. It will also be set into it. If ' \
@@ -132,6 +138,7 @@ module Gloo
132
138
  > put 123 into x
133
139
  > put 3 + 5 into x
134
140
  > put TRUE into flag
141
+ > put 5 into ( 'counts.' fruit )
135
142
  EXAMPLES
136
143
  }
137
144
  end
@@ -71,7 +71,8 @@ module Gloo
71
71
  :notes => 'If a file has changes that have not been saved, ' \
72
72
  'reloading discards them (a warning is logged, but the ' \
73
73
  'reload still proceeds). reload takes no object; to reload ' \
74
- 'just one object\'s file, send it the reload message.',
74
+ 'just one object\'s file, send it the reload message. ' \
75
+ 'Loaded libraries and extensions stay loaded.',
75
76
  :examples => <<~EXAMPLES.strip
76
77
  > reload
77
78
  EXAMPLES
@@ -18,6 +18,8 @@ module Gloo
18
18
  # Run the verb.
19
19
  #
20
20
  def run
21
+ return unless take_path_arg( 1 )
22
+
21
23
  if @tokens.token_count < 2
22
24
  @engine.syntax_err MISSING_EXPR_ERR
23
25
  return
@@ -85,12 +87,14 @@ module Gloo
85
87
  'same as sending a run message to the object.',
86
88
  :syntax => [
87
89
  'run {path.to.object}',
90
+ 'run ( {expression} )',
88
91
  'run ~> {expression}'
89
92
  ],
90
93
  :parameters => [
91
94
  '{path.to.object} — Reference to the object which will be ' \
92
95
  'run. The object must be a runnable object such as a script.',
93
- '{expression} — Evaluate the expression and run it.'
96
+ '{expression} — Evaluate the expression and run it.',
97
+ Gloo::Core::Verb::COMPUTED_PATH_DOC
94
98
  ],
95
99
  :result => 'The result depends on the object that is run.',
96
100
  :errors => [
@@ -102,6 +106,9 @@ module Gloo
102
106
  > create s as script : "show 3 + 4"
103
107
  > run s
104
108
 
109
+ # Run the script at a path worked out at runtime:
110
+ > run ( 'jobs.' name )
111
+
105
112
  # Run a script in an evaluated expression:
106
113
  > create s as string : "show 3 + 4"
107
114
  > run ~> s
@@ -17,6 +17,8 @@ module Gloo
17
17
  # Run the verb.
18
18
  #
19
19
  def run
20
+ return unless take_path_arg( 1 )
21
+
20
22
  name = @tokens.second
21
23
  return if name && Gloo::Core::Pn.new( @engine, name ).it_target_err?( 'saved' )
22
24
  return @engine.persist_man.save name unless @tokens.index_of( TO )
@@ -86,13 +88,20 @@ module Gloo
86
88
  :syntax => [
87
89
  'save',
88
90
  'save {path.to.object}',
91
+ 'save ( {expression} )',
89
92
  'save {path.to.object} to {path}',
90
93
  'save {path.to.object} to ( {expression} )'
91
94
  ],
92
95
  :parameters => [
93
96
  '{path.to.object} — Name of the object to save.',
94
- '{path} — Where to save it, relative to the project root ' \
95
- '(.gloo appended if omitted). Registers the mapping, so ' \
97
+ "save ( {expression} ) — The object to save, worked out: #{Gloo::Core::Verb::COMPUTED_PATH_DOC.sub( '( {expression} ) — ', '' )}",
98
+ '{path} — Where to save it: a full path, one starting ' \
99
+ 'with ~, or a relative name (.gloo appended if omitted). ' \
100
+ 'A relative name goes in the first place a relative load ' \
101
+ 'looks: the app folder in App mode; otherwise next to the ' \
102
+ "saving script's file (the projects folder for a script " \
103
+ 'that did not come from a file), or the working folder for ' \
104
+ 'a command typed at the prompt. Registers the mapping, so ' \
96
105
  'a later bare save includes it.',
97
106
  '( {expression} ) — Instead of a literal path, an expression ' \
98
107
  'in parentheses: it is worked out and its value is used as ' \
@@ -105,7 +114,14 @@ module Gloo
105
114
  'A declaration you never touched comes back byte-for-byte. ' \
106
115
  'An object counts as changed only when its value is set or ' \
107
116
  'it is created, moved, or deleted (its doc comment goes with ' \
108
- 'it); changes to its children do not change it. ' \
117
+ 'it); changes to its children do not change it. A changed ' \
118
+ 'declaration keeps its name, type and spacing; only its ' \
119
+ 'value is written again. A new object goes after the last ' \
120
+ "child of its parent's first declaration, in the file's " \
121
+ 'indentation and type spellings. An object declared on more ' \
122
+ 'than one line has its value on the first: a change rewrites ' \
123
+ 'only that line, and deleting or moving it takes all its ' \
124
+ 'lines. ' \
109
125
  'With a path, the object also stops being declared in its ' \
110
126
  'old file (if it had one) -- both files are rewritten ' \
111
127
  'together.',
@@ -122,7 +138,17 @@ module Gloo
122
138
  'container from nested-container shorthand; extract a ' \
123
139
  'child that does, or a shallower ancestor that does.'
124
140
  ],
125
- :notes => 'An object can also be told to save itself: ' \
141
+ :notes => 'A value that cannot be written exactly (a block ' \
142
+ 'value with no final line break, a line that is just END, ' \
143
+ 'bytes that are not UTF-8) is written as closely as possible, ' \
144
+ "with a warning: Could not save '{path}' exactly: {why}. A " \
145
+ 'changed script body loses the comments and blank lines ' \
146
+ 'inside it. A new top-level object has no file yet: a bare ' \
147
+ 'save leaves it out and warns (Not saved (no file yet): ' \
148
+ '{name}.); save {name} gives it a file of its own, named ' \
149
+ 'after it and placed the same way as a relative path. ' \
150
+ 'See doc verbs, Load & Save. ' \
151
+ 'An object can also be told to save itself: ' \
126
152
  '`tell my_obj to save`. When several files contribute to ' \
127
153
  'one container (the namespace pattern), each file save only ' \
128
154
  "rewrites that file's own declarations. Extraction (save " \