gloo 7.1.3 → 7.2

data/lib/gloo/persist/declaration_writer.rb

@@ -0,0 +1,208 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Writes the text a save generates: a changed declaration (its head
+# kept as written, only the value written again) or a declaration for
+# a new object, in the file's style (see FileStyle).
+#
+# A value is written so it loads back the same: on the line, as a
+# BEGIN/END block (exactly as it is -- a block's lines are the value),
+# or as a script body. A value with no exact spelling is written as
+# the closest one, with a warning.
+#
+
+module Gloo
+  module Persist
+    class DeclarationWriter
+
+      BEGIN_BLOCK = 'BEGIN'.freeze
+      END_BLOCK = 'END'.freeze
+      SEP = ' : '.freeze
+      NOT_EXACT = "Could not save '%s' exactly: %s.".freeze
+      NO_FINAL_NEWLINE = 'a block value always ends with a newline'.freeze
+      END_LINE = 'a line that is just END ends the block early'.freeze
+      NOT_UTF8 = 'it is not valid UTF-8'.freeze
+
+      #
+      # Set up a writer for a file with the given style.
+      #
+      def initialize( engine, style )
+        @engine = engine
+        @style = style
+      end
+
+      #
+      # The new text of a declaration whose object's value changed: its
+      # head as written, then the value.
+      #
+      def changed_text( node )
+        obj = node.obj
+        return body_text( node.head, node.raw_tail, obj, body_indent( node ), trailing_blanks( node ) ) if body?( obj, node.block_style == :body )
+
+        return value_text( node.head, separator( node ), obj, node.raw_indent, node.block_style == :begin_end )
+      end
+
+      #
+      # A source node for a new object (without its children), at the
+      # given indentation, written with the given name (its own, or a
+      # dotted path for a shorthand line).
+      #
+      def new_node( obj, indent, name = obj.name )
+        spelled = @style.type_for( obj )
+        head = spelled ? "#{indent}#{name} [#{spelled}]" : "#{indent}#{name}"
+        node = Source::ObjNode.new( :name => name, :raw_type => spelled || obj.type_display )
+        node.raw_indent = indent
+        node.head = head
+        node.obj = obj
+        node.raw = if body?( obj, false )
+                     body_text( head, ' :', obj, "#{indent}#{@style.unit}", '' )
+                   else
+                     value_text( head, SEP, obj, indent, false )
+                   end
+        node.block_style = block_style_of( node.raw )
+        node.raw_tail = node.raw.scrub.lines.first.chomp.delete_prefix( head )
+        return node
+      end
+
+      private
+
+      # ---------------------------------------------------------------------
+      #    Script bodies
+      # ---------------------------------------------------------------------
+
+      #
+      # Is the value written as a script body: a multi-line value (a
+      # script) whose value is a list of lines, or that was a body?
+      #
+      def body?( obj, was_body )
+        return false unless obj.multiline_value?
+
+        return was_body || obj.value_is_array?
+      end
+
+      #
+      # A script body: the head and tail (eg. ' :'), then each command
+      # on its own line at the body's indentation, then any blank lines
+      # that followed the body as written.
+      #
+      def body_text( head, tail, obj, indent, trailing )
+        lines = script_lines( obj )
+        str = "#{head}#{tail.rstrip}\n"
+        lines.each { |line| str << "#{indent}#{line}\n" }
+        return "#{str}#{trailing}"
+      end
+
+      #
+      # A script's command lines, whatever form its value is in.
+      #
+      def script_lines( obj )
+        return obj.value if obj.value_is_array?
+        return [] if obj.value.to_s.strip.empty?
+
+        return [ obj.value.to_s.strip ]
+      end
+
+      #
+      # The indentation of a body as written: its first non-blank line's,
+      # or one step in from the declaration.
+      #
+      def body_indent( node )
+        line = node.raw.lines.drop( 1 ).find { |l| !l.strip.empty? }
+        return line[ /\A[ \t]*/ ] if line
+
+        return "#{node.raw_indent}#{@style.unit}"
+      end
+
+      #
+      # The blank lines at the end of a body as written, kept when the
+      # body is written again.
+      #
+      def trailing_blanks( node )
+        lines = node.raw.lines.drop( 1 )
+        blanks = []
+        blanks.unshift( lines.pop ) while lines.any? && lines.last.strip.empty?
+        return blanks.join
+      end
+
+      # ---------------------------------------------------------------------
+      #    Values on the line or in a BEGIN/END block
+      # ---------------------------------------------------------------------
+
+      #
+      # The declaration with its value: on the line if it can be written
+      # there, otherwise as a BEGIN/END block. A value that was a block
+      # stays one if it still ends with a newline.
+      #
+      def value_text( head, sep, obj, indent, was_block )
+        value = obj.value_display.to_s
+        warn_not_exact( obj, NOT_UTF8 ) unless value.valid_encoding?
+        return block_text( head, sep, obj, value, indent ) if block?( value, was_block )
+        return "#{head}#{sep.rstrip}\n" if value.empty?
+
+        return "#{head}#{sep}#{value}\n"
+      end
+
+      #
+      # Does the value need (or keep) a BEGIN/END block? A line break
+      # can't go on the line, and a value ending in a backslash or in
+      # BEGIN would be read as a continuation or a block start.
+      #
+      def block?( value, was_block )
+        return true if was_block && value.end_with?( "\n" )
+
+        clean = value.scrub
+        return clean.include?( "\n" ) || clean.end_with?( '\\' ) || clean.strip.end_with?( BEGIN_BLOCK )
+      end
+
+      #
+      # A BEGIN/END block: the value's lines exactly as they are, and END
+      # lined up with the declaration.
+      #
+      def block_text( head, sep, obj, value, indent )
+        content = value
+        unless content.end_with?( "\n" )
+          warn_not_exact( obj, NO_FINAL_NEWLINE )
+          content = "#{content}\n"
+        end
+        warn_not_exact( obj, END_LINE ) if content.scrub.lines.any? { |l| l.strip == END_BLOCK }
+
+        return "#{head}#{sep}#{BEGIN_BLOCK}\n#{content}#{indent}#{END_BLOCK}\n"
+      end
+
+      #
+      # What goes between a declaration's head and its value, as written:
+      # usually ' : '.
+      #
+      def separator( node )
+        tail = node.raw_tail.to_s
+        return tail.sub( /#{BEGIN_BLOCK}\s*\z/o, '' ) if node.block_style == :begin_end
+
+        value = node.raw_value.to_s
+        return tail[ 0, tail.length - value.length ] if !value.empty? && tail.end_with?( value )
+
+        trimmed = tail.rstrip
+        return trimmed.end_with?( ':' ) ? "#{trimmed} " : SEP
+      end
+
+      #
+      # The block style of a declaration written from scratch.
+      #
+      def block_style_of( text )
+        text = text.scrub
+        first = text.lines.first.to_s
+        return :begin_end if first.rstrip.end_with?( BEGIN_BLOCK ) && text.lines.size > 1
+        return :body if text.lines.size > 1
+
+        return :inline
+      end
+
+      #
+      # Warn that a value is saved as the closest thing gloo can write.
+      #
+      def warn_not_exact( obj, why )
+        @engine.warn format( NOT_EXACT, obj.pn, why )
+      end
+
+    end
+  end
+end

data/lib/gloo/persist/disc_mech.rb

@@ -30,28 +30,42 @@ module Gloo
       #
       # Get all the gloo files in the folder (partial path). The folder
       # can end with the start of a file name, as a prefix (folder/a).
+      # A relative folder is looked for in each of the given folders in
+      # turn (see default_folders); the first that has matching files
+      # wins.
       #
-      def get_all_files_in( folder )
-        dir = folder_for_files( folder )
-        return Dir.glob( "#{dir}*.gloo" )
+      def get_all_files_in( folder, folders = nil )
+        return Dir.glob( "#{absolute_folder( folder )}*.gloo" ) if absolute?( folder )
+
+        ( folders || default_folders ).each do |base|
+          files = Dir.glob( "#{File.join( base, folder )}*.gloo" )
+          return files.map { |f| File.expand_path( f ) } unless files.empty?
+        end
+        return []
       end
 
       #
-      # Where to look for a folder of files: an absolute or ~ folder as
-      # given (~ expanded), anything else in the project folder, or if it
-      # isn't there, in the gloo home.
+      # An absolute or ~ folder, with ~ expanded.
       #
-      def folder_for_files( folder )
+      def absolute_folder( folder )
         return folder.sub( '~', Dir.home ) if folder.start_with?( '~' )
-        return folder if File.absolute_path?( folder )
 
-        dir = File.join( @engine.settings.project_path, folder )
-        return dir if Dir.exist?( dir )
+        return folder
+      end
+
+      #
+      # Is the name a full path, or one starting with ~?
+      #
+      def absolute?( name )
+        return name.start_with?( '~' ) || File.absolute_path?( name )
+      end
 
-        @log.debug "Folder does not exist in project: #{folder}"
-        dir = File.join( @engine.settings.user_root, folder )
-        @log.debug "Looking in gloo home? found == #{Dir.exist?( dir )}"
-        return dir
+      #
+      # Where a relative name is looked for when no folders are given:
+      # the project folder, then the gloo home.
+      #
+      def default_folders
+        return [ @engine.settings.project_path, @engine.settings.user_root ]
       end
 
       # 
@@ -75,59 +89,76 @@ module Gloo
 
       #
       # Expand a single file path. The .gloo extension is optional: it's
-      # added when the name doesn't end with it, for a full or ~ path
-      # and for a name in the project or gloo home.
+      # added when the name doesn't end with it.
       #
-      def expand( name )
+      # A full or ~ path is used as given. A relative name is looked for
+      # in each of the given folders in turn (the load verb's order, see
+      # PersistMan#search_folders). With no folders given (a file named
+      # on the command line), it's tried as given, relative to the
+      # working folder, and then in the project folder and gloo home.
+      #
+      def expand( name, folders = nil )
+        full_name = name.end_with?( file_ext ) ? name : "#{name}#{file_ext}"
+        return expand_in( full_name, folders ) if folders && !absolute?( name )
+
         # Try the name as given: a full path, or relative to the working
         # folder (eg. gloo hello_world.gloo).
         ext_path = File.expand_path( name )
         return [ ext_path ] if self.valid?( ext_path )
 
-        full_name = name.end_with?( file_ext ) ? name : "#{name}#{file_ext}"
-
         # A full or ~ path without the extension.
-        if name.start_with?( '~' ) || File.absolute_path?( name )
+        if absolute?( name )
           ext_path = File.expand_path( full_name )
           return [ ext_path ] if self.valid?( ext_path )
         end
 
-        # Try in projects
-        pn = File.join( @engine.settings.project_path, full_name )
-        return [ pn ] if self.valid?( pn )
-
-        # Try in user root
-        pn = File.join( @engine.settings.user_root, full_name )
-        return [ pn ] if self.valid?( pn )
+        return expand_in( full_name, default_folders )
+      end
 
+      #
+      # The file in the first of the folders that has it, as a one-item
+      # list; nil if none does.
+      #
+      def expand_in( full_name, folders )
+        folders.each do |base|
+          pn = File.expand_path( File.join( base, full_name ) )
+          return [ pn ] if self.valid?( pn )
+        end
         return nil
       end
 
       #
-      # Read in the contents of a single file.
+      # Read in the contents of a single file, as UTF-8 whatever the
+      # locale: a .gloo file is UTF-8 (under LANG=C, a plain read would
+      # take every non-ASCII character as an invalid byte). Bytes that
+      # aren't valid UTF-8 are kept as they are; the loader warns about
+      # them.
       #
       def read( file )
-        return File.read( file )
+        return File.binread( file ).force_encoding( Encoding::UTF_8 )
       end
 
       #
       # Resolve a path to save a new (not-yet-existing) file to, given
-      # a name or relative path -- same convention as expand (relative
-      # to the project root, .gloo appended if missing), but without
-      # requiring the file to already exist.
+      # a name or relative path, with .gloo appended if missing. Unlike
+      # expand, the file doesn't have to exist. A full path is used as
+      # given and a ~ path is expanded. A relative name goes in the
+      # given folder (the first place a load would look, see
+      # PersistMan#save_folder), or the project folder if none is given.
       #
-      def resolve_save_path( name )
+      def resolve_save_path( name, folder = nil )
         full_name = name.end_with?( file_ext ) ? name : "#{name}#{file_ext}"
-        return full_name if full_name.start_with?( '/' )
+        return File.expand_path( absolute_folder( full_name ) ) if absolute?( full_name )
 
-        return File.join( @engine.settings.project_path, full_name )
+        return File.expand_path( File.join( folder || @engine.settings.project_path, full_name ) )
       end
 
-      # 
-      # Write data to the file.
-      # 
+      #
+      # Write data to the file, byte for byte (no conversion for the
+      # locale).
+      #
       def write( pn, data )
-        File.write( pn, data )
+        File.binwrite( pn, data )
       end
 
     end