gloo 7.1.2 → 7.2

data/lib/gloo/persist/source/obj_node.rb

@@ -3,10 +3,10 @@
 #
 # One object declaration in a source file, eg.
 #   name [type] : value
-# Carries the raw text needed to reproduce the declaration unchanged,
-# plus a back-reference to the heap object it created (or updated),
-# so a save can tell whether the live value still matches what's on
-# disk and, if so, leave the raw text alone.
+# Carries the declaration's exact source text, plus a back-reference
+# to the heap object it created (or named again), so a save can tell
+# whether the object is still there and its value unchanged and, if
+# so, write the text back exactly as it was read.
 #
 
 module Gloo
@@ -19,8 +19,23 @@ module Gloo
         #  :begin_end -- name [type] : BEGIN ... END
         #  :body      -- name [type] :, followed by an indented,
         #                unparsed body (script commands)
+        #
+        # raw is the declaration's own exact text: its line (with any
+        # continuation lines), and its BEGIN/END block or script body,
+        # line endings included -- not its leading_doc or children.
+        # head is the declaration line up to its value (indent, name and
+        # [type], as written), raw_tail what follows it.
+        #
+        # repaired_head is set when gloo had to guess at the head (a
+        # missing name or ']'): a save writes the head as understood.
+        #
+        # home is the object's parent and snapshot a copy of its value,
+        # both taken when the file finished loading: the object is still
+        # in its place if its parent is home, and unchanged if its value
+        # equals the snapshot.
         attr_accessor :name, :raw_type, :raw_indent, :raw_tail, :block_style,
-                      :raw_value, :raw_end_indent, :leading_doc, :trailing_comment, :obj
+                      :raw_value, :leading_doc, :obj, :raw, :head,
+                      :home, :snapshot, :repaired_head
         attr_reader :children
 
         #
@@ -35,15 +50,80 @@ module Gloo
           @raw_tail = ''
           @block_style = :inline
           @raw_value = nil
-          # a begin_end block's closing END is not necessarily indented
-          # to match its declaration -- kept separately, raw.
-          @raw_end_indent = ''
           @leading_doc = nil
-          @trailing_comment = nil
           @obj = nil
+          @raw = ''
+          @head = ''
+          @home = nil
+          @snapshot = nil
+          @repaired_head = nil
           @children = []
         end
 
+        #
+        # The exact source text of the declaration, its leading_doc and
+        # everything under it, as read.
+        #
+        def text
+          str = "#{@leading_doc}#{@raw}"
+          @children.each { |child| str << child.text }
+          return str
+        end
+
+        #
+        # A copy of this declaration with no children, and with the
+        # given text in place of its own (for a save's new document;
+        # this node is left as it is).
+        #
+        def detached( raw = @raw )
+          copy = dup
+          copy.raw = raw
+          copy.reset_children
+          return copy
+        end
+
+        #
+        # A copy with the head gloo understood in place of the one
+        # written (see repaired_head); this node if nothing was repaired.
+        #
+        def repaired
+          return self unless @repaired_head
+
+          copy = detached( @raw.sub( @head, @repaired_head ) )
+          copy.head = @repaired_head
+          copy.repaired_head = nil
+          return copy
+        end
+
+        #
+        # Record where the object is and what its value is, now that the
+        # file has finished loading.
+        #
+        def remember
+          return unless @obj
+
+          @home = @obj.parent
+          @snapshot = copy_of( @obj.value )
+        end
+
+        #
+        # Is the object still under the parent it was loaded under?
+        #
+        def in_place?
+          return false unless @obj && @home
+
+          return @obj.parent.equal?( @home ) && @home.children.any? { |c| c.equal?( @obj ) }
+        end
+
+        #
+        # Has the object's value changed since the file was loaded?
+        #
+        def changed?
+          return false unless @obj
+
+          return @obj.value != @snapshot
+        end
+
         #
         # The cleaned-up leading_doc: each line's leading whitespace and
         # its '#' marker (plus one following space, if any) stripped,
@@ -59,8 +139,93 @@ module Gloo
           return dedent( lines ).join( "\n" )
         end
 
+        #
+        # Give the declaration a new name as written (eg. a dotted path
+        # when it moves into a file of its own). Only the name on its
+        # first line changes.
+        #
+        def rename( new_name )
+          @raw = @raw.sub( /\A([ \t]*)#{Regexp.escape( @name )}/ ) { "#{$1}#{new_name}" }
+          @head = @head.sub( /\A([ \t]*)#{Regexp.escape( @name )}/ ) { "#{$1}#{new_name}" }
+          @name = new_name
+        end
+
+        #
+        # Move the declaration (and everything under it) to a new
+        # indentation. Its own lines and its script body shift by the
+        # same amount; a BEGIN/END block's content is the value, so it
+        # stays exactly as it is, and END lines up with the declaration.
+        # A leading_doc's lines are set to the new indentation.
+        #
+        def reindent( new_indent )
+          old = @raw_indent
+          @leading_doc = reindent_doc( @leading_doc, new_indent ) if @leading_doc
+          @raw = reindent_own( @raw, old, new_indent )
+          @head = shift( @head, old, new_indent )
+          @raw_indent = new_indent
+          @children.each do |child|
+            next unless child.is_a?( ObjNode )
+
+            child.reindent( shift( child.raw_indent, old, new_indent ) )
+          end
+        end
+
+        protected
+
+        #
+        # Start with no children (for a detached copy).
+        #
+        def reset_children
+          @children = []
+        end
+
         private
 
+        #
+        # A copy of a value that can't be changed through the original
+        # (a script's lines are an Array that grows in place).
+        #
+        def copy_of( value )
+          return Marshal.load( Marshal.dump( value ) )
+        rescue TypeError
+          return value.dup
+        end
+
+        #
+        # The declaration's own lines at a new indentation.
+        #
+        def reindent_own( text, old, new_indent )
+          lines = text.lines
+          return text if lines.empty?
+
+          if @block_style == :begin_end
+            ending = lines.last[ /\r?\n\z/ ].to_s
+            lines[ 0 ] = shift( lines[ 0 ], old, new_indent )
+            lines[ -1 ] = "#{new_indent}END#{ending}" if lines.size > 1
+            return lines.join
+          end
+
+          return lines.map { |l| l.strip.empty? ? l : shift( l, old, new_indent ) }.join
+        end
+
+        #
+        # Replace a line's old indentation prefix with the new one; a
+        # line that doesn't start with it gets the new one added.
+        #
+        def shift( line, old, new_indent )
+          return "#{new_indent}#{line.delete_prefix( old )}" if line.start_with?( old )
+
+          return "#{new_indent}#{line.lstrip}"
+        end
+
+        #
+        # Re-indent a leading_doc's lines to new_indent, replacing
+        # whatever leading whitespace each '#' line had.
+        #
+        def reindent_doc( raw, new_indent )
+          return raw.lines.map { |line| "#{new_indent}#{line.lstrip}" }.join
+        end
+
         #
         # One raw comment line -> its text past the '#': leading
         # whitespace dropped, then the '#' and at most one space after

data/lib/gloo/persist/source/source_doc.rb

@@ -19,11 +19,53 @@ module Gloo
 
         attr_reader :children
 
+        # A file whose last line has no line ending: every node's text
+        # ends with one anyway (so new text can follow any node), and
+        # the document leaves the last one off.
+        attr_accessor :no_final_newline
+
         #
         # Set up an empty source document.
         #
         def initialize
           @children = []
+          @no_final_newline = false
+        end
+
+        #
+        # The file's exact text: every node's text, in order. Right
+        # after a load this is the file, byte for byte.
+        #
+        def text
+          str = @children.map( &:text ).join
+          str = str.delete_suffix( "\n" ) if @no_final_newline
+          return str
+        end
+
+        #
+        # Note that the file's last line had no line ending, and give it
+        # one in the node that holds it (see no_final_newline).
+        #
+        def missing_final_newline!
+          leaf = last_text_node( @children )
+          return unless leaf
+
+          leaf.raw << "\n"
+          @no_final_newline = true
+        end
+
+        #
+        # Every object declaration in the document, at any depth, in
+        # file order.
+        #
+        def obj_nodes( nodes = @children, found = [] )
+          nodes.each do |node|
+            next unless node.is_a?( Source::ObjNode )
+
+            found << node
+            obj_nodes( node.children, found )
+          end
+          return found
         end
 
         #
@@ -51,6 +93,18 @@ module Gloo
 
         private
 
+        #
+        # The node whose text comes last in the file: the last node, or
+        # its last child (at any depth) if it has children.
+        #
+        def last_text_node( nodes )
+          last = nodes.last
+          return nil unless last
+          return last unless last.is_a?( Source::ObjNode ) && last.children.any?
+
+          return last_text_node( last.children )
+        end
+
         #
         # Depth-first search of nodes (and their children) for the one
         # linked to obj; removes it from whichever children array it's

data/lib/gloo/persist/subtree_extractor.rb

@@ -46,11 +46,13 @@ module Gloo
         return err( SPANS_MULTIPLE_FILES_ERR ) if owners.count > 1
 
         source_fs = owners.first
-        node = source_fs ? remove_node( obj, source_fs ) : fresh_node( obj )
+        return [ fresh_node( obj ), nil ] unless source_fs
+
+        node = remove_node( obj, source_fs )
         return err( NO_OWN_DECLARATION_ERR ) unless node
 
-        node.name = dotted_name( obj )
-        reindent( node, 0 )
+        node.rename( dotted_name( obj ) )
+        node.reindent( '' )
         return [ node, source_fs ]
       end
 
@@ -110,13 +112,12 @@ module Gloo
 
       #
       # obj has no file of its own (never loaded, or created at
-      # runtime since) -- build a plain node with no raw text of its
-      # own. FileSaver renders it fresh from the live object, the same
-      # way it already does for any brand-new child.
+      # runtime since) -- write it, and everything under it, from
+      # scratch, named by its dotted path.
       #
       def fresh_node( obj )
-        node = Source::ObjNode.new( :name => obj.name, :raw_type => obj.type_display )
-        node.obj = obj
+        node = FileSaver.new( @engine, nil, obj ).new_node( obj, dotted_name( obj ) )
+        Source::SourceDoc.new.obj_nodes( [ node ] ).each( &:remember )
         return node
       end
 
@@ -150,35 +151,6 @@ module Gloo
         return names.join( '.' )
       end
 
-      #
-      # Recompute raw_indent (and, for a BEGIN/END node, raw_end_indent
-      # to match) from scratch for the moved node and every descendant
-      # ObjNode. Their old indentation depth described nesting inside
-      # the file they came from; here obj itself is depth 0, in a
-      # brand-new file. Floating trivia (a blank line or comment not
-      # attached as some declaration's leading_doc) travels along
-      # unindented-adjusted -- purely cosmetic, since indentation never
-      # affects how a comment/blank line is recognized on reload.
-      #
-      def reindent( node, depth )
-        new_indent = "\t" * depth
-        node.raw_indent = new_indent
-        node.raw_end_indent = new_indent if node.block_style == :begin_end
-        node.leading_doc = reindent_doc( node.leading_doc, new_indent ) if node.leading_doc
-        node.children.each do |child|
-          reindent( child, depth + 1 ) if child.is_a?( Source::ObjNode )
-        end
-      end
-
-      #
-      # Re-indent a raw leading_doc's lines to new_indent, replacing
-      # whatever leading whitespace each '#'-prefixed line had in the
-      # file it came from.
-      #
-      def reindent_doc( raw, new_indent )
-        return raw.split( "\n" ).map { |line| "#{new_indent}#{line.lstrip}" }.join( "\n" )
-      end
-
     end
   end
 end

data/lib/gloo/persist/trivia_buffer.rb

@@ -29,16 +29,16 @@ module Gloo
       end
 
       #
-      # Buffer one comment line. raw is the full source line (minus
-      # its trailing newline); tabs is its indentation level.
+      # Buffer one comment line. raw is the full source line, with its
+      # line ending; tabs is its indentation level.
       #
       def push_comment( raw, tabs )
         @pending << { :kind => :comment, :raw => raw, :tabs => tabs }
       end
 
       #
-      # Buffer one blank line. raw is its exact source text (may be
-      # non-empty if it had trailing whitespace) -- a blank line always
+      # Buffer one blank line. raw is its exact source text, with its
+      # line ending and any trailing whitespace -- a blank line always
       # breaks a comment run's association with whatever declaration
       # follows, the same as it always has.
       #
@@ -61,8 +61,8 @@ module Gloo
       #
       # If the run since the last blank (or the whole run, if it has no
       # blank in it) is one or more comment lines all at the same
-      # indent as line_tabs, claim it as a leading_doc (raw,
-      # newline-joined). Anything before that -- an earlier blank, and
+      # indent as line_tabs, claim it as a leading_doc (the raw lines,
+      # line endings included). Anything before that -- an earlier blank, and
       # whatever preceded it -- floats into children first, in order,
       # since a blank always breaks the association. If the trailing
       # run doesn't qualify (wrong indent, or empty), it floats into
@@ -74,7 +74,7 @@ module Gloo
         flush_list( before, children )
 
         if after.any? && after.last[ :tabs ] == line_tabs
-          doc = after.map { |t| t[ :raw ] }.join( "\n" )
+          doc = after.map { |t| t[ :raw ] }.join
           @pending = []
           return doc
         end

data/lib/gloo/verbs/break.rb

@@ -10,14 +10,23 @@ module Gloo
 
       KEYWORD = 'break'.freeze
       KEYWORD_SHORT = 'stop'.freeze
+      LOOP = 'loop'.freeze
+      NOT_IN_A_LOOP = 'Could not break loop: not in a loop.'.freeze
 
       #
       # Run the verb.
-      # Stop the execution of the current script.
+      # Stop the execution of the current script. With loop (break
+      # loop), also end the loop whose do script this is.
       #
       def run
-        warn_extra_words
-        @engine.exec_env.running_script.break_out
+        words = extra_words.split( ' ' )
+        if words.first&.downcase == LOOP
+          warn_words_after_loop( words.drop( 1 ) )
+          break_loop
+        else
+          warn_unknown_words
+          @engine.exec_env.running_script.break_out
+        end
       end
 
       #
@@ -40,6 +49,54 @@ module Gloo
 
       private
 
+      #
+      # End the running script and its loop. Only valid directly in a
+      # loop's do script; anywhere else (a script the do runs, a group
+      # script, outside any loop) it's an error and nothing stops.
+      #
+      def break_loop
+        script = @engine.exec_env.running_script
+        unless loop_do?( script&.obj )
+          @engine.err NOT_IN_A_LOOP
+          return
+        end
+
+        script.break_out( loop: true )
+      end
+
+      #
+      # Is the object the do script of a loop (a repeat or an each)?
+      #
+      def loop_do?( obj )
+        parent = obj&.parent
+        return false unless parent.is_a?( Gloo::Objs::Repeat ) ||
+                            parent.is_a?( Gloo::Objs::Each )
+
+        return parent.find_child( Gloo::Objs::Each::DO ).equal?( obj )
+      end
+
+      #
+      # Warn about anything written after break other than loop.
+      # The break still happens.
+      #
+      def warn_unknown_words
+        extra = extra_words
+        return if extra.empty?
+
+        @engine.warn "#{written_verb} takes only '#{LOOP}'; ignoring '#{extra}'."
+      end
+
+      #
+      # Warn about anything written after break loop. The loop still
+      # ends.
+      #
+      def warn_words_after_loop( words )
+        return if words.empty?
+
+        @engine.warn "#{written_verb} #{LOOP} takes no object; " \
+                     "ignoring '#{words.join( ' ' )}'."
+      end
+
       # ---------------------------------------------------------------------
       #    Verb Documentation
       # ---------------------------------------------------------------------
@@ -52,15 +109,26 @@ module Gloo
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
           :description => 'Break out of the current script, stop running. ' \
-            'If that script is the do script of a loop (repeat, or any ' \
-            'kind of each), the whole loop ends.',
-          :syntax => [ 'break' ],
+            'In a loop\'s do script, break skips the rest of that pass ' \
+            'and the loop goes on; break loop ends the whole loop.',
+          :syntax => [ 'break', 'break loop' ],
+          :parameters => [
+            'loop — Optional. Also end the loop whose do script this is. ' \
+            'Only valid directly in a loop\'s do script (repeat, or any ' \
+            'kind of each).'
+          ],
           :result => 'No more commands are executed in the currently ' \
             'running script. If there are other scripts in the stack, ' \
-            'they will resume normally. In a loop\'s do script, the loop ' \
-            'ends too and runs no more passes; the script that ran the ' \
-            'loop carries on. A break in a script the do script runs ' \
-            '(eg. with run) ends only that script, not the loop.',
+            'they will resume normally. In a loop\'s do script, a plain ' \
+            'break ends that pass and the loop goes on with the next ' \
+            'item. With break loop, the loop ends too and the script ' \
+            'that ran it carries on.',
+          :errors => [
+            "#{NOT_IN_A_LOOP} — break loop in a script that isn't a " \
+            'loop\'s do script: one the do script runs (with run, or a ' \
+            'function), a loop\'s on_group_start or on_group_end, or a ' \
+            'script outside any loop. Nothing stops.'
+          ],
           :examples => <<~EXAMPLES.strip
             #
             # Break out of a script.
@@ -73,6 +141,27 @@ module Gloo
                 put true into ^.x
                 if ^.x then break
                 show 'should not see this'
+
+            #
+            # In a loop: break skips an item, break loop ends the loop.
+            # Shows 0, 1, 3, then 0, 1.
+            #
+            loops [can] :
+              on_load [script] :
+                tell loops.skip to run
+                tell loops.early to run
+              skip [repeat] :
+                times [int] : 4
+                index [int] :
+                do [script] :
+                  if loops.skip.index = 2 then break
+                  show loops.skip.index
+              early [repeat] :
+                times [int] : 4
+                index [int] :
+                do [script] :
+                  if loops.early.index = 2 then break loop
+                  show loops.early.index
           EXAMPLES
         }
       end

data/lib/gloo/verbs/load.rb

@@ -63,12 +63,15 @@ module Gloo
         return KEYWORD_SHORT
       end
 
-      # 
-      # Load a gloo file
-      # 
+      #
+      # Load a gloo file. A relative name is looked for in the
+      # persist manager's search folders (next to this file, the
+      # app or projects folder, the gloo home).
+      #
       def load_gloo_file( fn )
         @engine.log.debug "Getting ready to load gloo file: #{fn}"
-        @engine.persist_man.load fn
+        pm = @engine.persist_man
+        pm.load( fn, pm.search_folders )
       end
 
       # 
@@ -98,16 +101,17 @@ module Gloo
         {
           :name => KEYWORD,
           :shortcut => KEYWORD_SHORT,
-          :description => 'Load an object file. There are two ways to ' \
-            'specify the file. Give either the full path and file name ' \
-            'or use a relative path from the gloo project folder. For ' \
-            'the latter, the extension is not needed. For the former, ' \
-            'the file extension is necessary. Using * instead of a file ' \
-            'name will load all gloo files in the folder. When using the ' \
-            '--app option, the file is loaded from the application ' \
-            'folder, but if not found there, the loader will also look ' \
-            'in the gloo root folder. The load verb is also used to ' \
-            'import an extension or library at runtime.',
+          :description => 'Load an object file. Give a full path, one ' \
+            'starting with ~, or a relative name; the .gloo extension is ' \
+            'optional. A relative name is looked for in a few places, in ' \
+            'order. In App mode (--app): the app folder, then next to the ' \
+            'file the loading script came from, then the gloo home. ' \
+            'Otherwise: next to the loading file, then the projects ' \
+            'folder (the project_path setting), then the gloo home. A ' \
+            'command typed at the prompt has no file, so the working ' \
+            'folder stands in for it. Using * instead of a file name ' \
+            'loads all gloo files in the folder. The load verb is also ' \
+            'used to import an extension or library at runtime.',
           :syntax => [
             'load {file_name}',
             'load ext {my_ext}',
@@ -116,11 +120,12 @@ module Gloo
           ],
           :parameters => [
             '{file_name} — Name of the object file that is to be loaded: ' \
-              'relative to the project, a full path, or starting with ~. ' \
+              'a relative name (see the description for where it is ' \
+              'looked for), a full path, or starting with ~. ' \
               'The .gloo extension is optional. ' \
-              'End it with * to load every .gloo file in a folder (a ' \
-              'folder in the project, a full path, or one starting with ' \
-              '~); anything before the * is the start of the file names.',
+              'End it with * to load every .gloo file in a folder, found ' \
+              'the same way; the first place with matching files is ' \
+              'used. Anything before the * is the start of the file names.',
             'reference type — By default, the type is file. File can be ' \
               'specified, but does not need to be. Use ext to load a ' \
               'User Extension. Use lib to load a Core Library.',
@@ -136,8 +141,8 @@ module Gloo
             "#{UNKNOWN_OPT_ERR} — The reference type given isn't file, ext, or lib.",
             "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name).",
             'File not found: {name} — The file name given could not be ' \
-              'resolved to a gloo file (checked as a full path, and ' \
-              'relative to the project and gloo root folders).'
+              'resolved to a gloo file in any of the places it is ' \
+              'looked for.'
           ],
           :notes => 'Several files can contribute to one container: ' \
             'declare it in each file and add different children, and ' \
@@ -156,7 +161,8 @@ module Gloo
             'is declared in more than one loaded file, the first ' \
             'non-empty doc wins, same as the first value.',
           :examples => <<~EXAMPLES.strip
-            > load my/project/file
+            # Next to this file (or the app folder, in App mode)
+            > load parts/helpers
             > load my/app/*
             > load ~/.my_app/settings.gloo
             > load ~/.my_app/plugins/*