gloo 7.1.3 → 7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 153d674b150e06c999a0756c90c41f872a410205f516eaa8b560335f93ec0e2b
-  data.tar.gz: 1b11115e161f139b44dc6750713e0e883f638ae58048c8b3007441cbf681f319
+  metadata.gz: b5cc04330edd79c2663408d7afbedc9195dbd994c31ce0a7cd6a591ce9276c56
+  data.tar.gz: d4f004bccdc1dbae382b2d3106154557b90e6b236447b04c8c5b5fcf05ebeffc
 SHA512:
-  metadata.gz: 3e92b508048653b4e1e4e283a7e90de32605b4a239f56b7b24123c600e5b38a6af582a50a6d2a7130da8ed73d8ded9f0e6aab2a75798a9709939749cf72119dd
-  data.tar.gz: 19cd40e0d35cfed856aa7eb6ffe4fe648adde3c706656d81211d01f0c940a4c38dd63b0bffe2a4b50b3b57d9e76afba997050c7fca99066f2fe6529825d05591
+  metadata.gz: 8a0ecc8a6e085ce93a55ec93de2a629c3fa023cfd4982fd0cc1005cc954c737ae81c4dd2d2299924623692546360df79a15b856d138201671a5c1181cccfb7c0
+  data.tar.gz: 603536ee8defb9805546bd785b51afcea41809e67a76118a0d750ea8862e5929c5aca2e68cadd22c4488c12f52618864f1727bc2feb2e6f8e504e95035c63b19

data/Rakefile

@@ -9,3 +9,26 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task :default => :test
+
+#
+# Load and save a copy of every .gloo file under the given folders, and
+# list the files that come back different. The originals are never
+# written. For example:
+#   rake "round_trip[~/gloo/app,~/dev/gloo_apps]"
+#
+desc 'Round-trip copies of .gloo files and list the ones that change'
+task :round_trip do |_task, args|
+  $LOAD_PATH.unshift File.expand_path( 'lib', __dir__ ), File.expand_path( 'test', __dir__ )
+  require 'gloo'
+  require 'round_trip_check'
+
+  check = RoundTripCheck.new do
+    engine = Gloo::App::Engine.new( Gloo::App::EngineContext.new( [ '--quiet' ] ) )
+    engine.log.quiet = true
+    engine.start
+    engine
+  end
+  changed, count = check.check_folders( args.extras )
+  changed.each { |path, diff| puts "#{path}\n  #{diff}" }
+  puts "#{changed.size} of #{count} files changed."
+end

data/docs/application.md

@@ -5,6 +5,7 @@
 - The Gloo Home Directory
 - Running Gloo
 - Modes
+- Script Mode and App Mode
 - Configuration
 - Logging
 - Help
@@ -35,6 +36,8 @@ Gloo can also be started from another Ruby program; see Development, Running Glo
 
 If a file named on the command line can't be found (a typo, the wrong folder, a missing `.gloo` extension on a full path), gloo prints `File '{name}' was not found.` to stderr and exits with a non-zero status. Any other load or run error also exits non-zero — including syntax errors in a file that otherwise loaded (gloo keeps loading past them, reporting each with its file and line) — so a shell script calling gloo can tell a failed run from a clean one.
 
+The exit status covers the whole run, not just its last line: gloo exits with status 1 if any error, or any Ruby exception, happened at any point while the files were loading or running, and 0 otherwise. An error still counts when an `on_error` or `on_exception` handler ran for it, because a handler reports the problem, it doesn't undo it. Warnings don't count. This applies when gloo runs files (Script mode); App and CLI modes don't set an exit status, and Test mode has its own (see the `--test` option below).
+
 When specifying a file there are a couple ways to reference the gloo file to open:
 
 - By Path
@@ -46,11 +49,11 @@ When specifying a file there are a couple ways to reference the gloo file to ope
         ```
 - By Project
     - Use the path within the project folder.
-    - Do not include the `.gloo` or other file extension.
+    - The `.gloo` extension can be left off.
     - The location of the project folder is part of the configuration.
     - For example:
         ```
-        gloo my_project/file.gloo
+        gloo my_project/file
         ```
 
 ## Modes
@@ -87,6 +90,48 @@ When specifying a file there are a couple ways to reference the gloo file to ope
 --help       - Show the help screen
 ```
 
+## Script Mode and App Mode
+
+Gloo runs a file in one of two ways, and they're meant for different things.
+
+**Script mode** (`gloo path/to/file.gloo`) is a transaction: gloo loads the file, runs its `on_load`, and quits. Use it for a job that does something and finishes.
+
+**App mode** (`gloo --app path/to/folder`) is a process: gloo loads the folder's `start.gloo`, and the app stays up — a shell taking commands, a web server, a connection — until it's told to stop. The folder is the app's root: `gloo.app` is that folder, and words after it on the command line are a command for the app, not files to load.
+
+An app only runs in App mode. If an app's `start.gloo` is run as a script by mistake, starting a shell (gloo-cli) or a web server (gloo-web) is an error that says how to run it, for example `Could not start the shell: an app runs in App mode. Run it with 'gloo --app ~/gloo/app/notes'.`, and gloo exits with status 1.
+
+The two also differ in what the **project folder** is. In App mode it's the app's folder. Otherwise it's where you keep your projects: the `project_path` setting (see Configuration), `~/gloo/projects` unless you change it, and `gloo.gloo_projects`.
+
+### Where a Relative Load Looks
+
+A `load` with a full path, or one starting with `~`, loads that file. A relative name is looked for in a few places, in order, and the first place that has it wins:
+
+| Mode | Looks in, in order |
+|---|---|
+| App mode | the app folder → next to the loading file → the gloo home |
+| Script and Test modes | next to the loading file → the projects folder → the gloo home |
+| A command typed at the prompt | the working folder → the projects folder → the gloo home (in App mode: the app folder → the working folder → the gloo home) |
+
+"Next to the loading file" is the folder of the file the running script was declared in — the folder `check {obj} for source_dir` gives for it. A script declared in one file and run from another still looks next to its own file. A script that didn't come from a file (one created while gloo runs) skips this step. A command typed at the prompt has no file, so the working folder stands in for it; a load inside a file never depends on where gloo was started.
+
+A folder load (`load parts/*`) is looked for the same way, and the first place with matching `.gloo` files is used. The gloo home comes last in every mode, so files kept there (such as a `common` folder shared by several apps) can be loaded from anywhere.
+
+For example, a small project:
+
+```
+report/
+  start.gloo      # on_load: load parts/*
+  parts/
+    totals.gloo
+    format.gloo
+```
+
+Run as a script (`gloo report/start.gloo`), `load parts/*` finds `report/parts` next to `start.gloo`, whatever folder gloo was started from. Run as an app (`gloo --app report`), it finds the same folder as part of the app. Inside an app, a name means the same thing in every file: `load parts/format` gets `report/parts/format.gloo` whichever of the app's files says it.
+
+Files named on the command line are found differently: as given (from the working folder), then in the projects folder, then in the gloo home (see Running Gloo, above).
+
+A new file saved with a relative name (`save notes to lists/notes`, or `save notes` for a top-level object that has no file yet) goes in the first place a load would look: the app folder in App mode, otherwise next to the saving script's file, or the working folder for a command typed at the prompt. A script that didn't come from a file saves into the projects folder. So a script that saves `lists/notes` can load it back with `load lists/notes`.
+
 ## Configuration
 
 When gloo runs, it looks for a configuration file which it expects to find in `~/gloo/config/`. If there is no `gloo.yml` file in that directory, one will be created and default values added.

data/docs/development.md

@@ -78,6 +78,16 @@ Use plain `ruby`, not `bundle exec`. The Gemfile doesn't include `gloo-test` or
 
 The same command runs the gloo tests of core libraries and extensions; add their `test/` folders to the list of paths.
 
+### Round-trip check
+
+Saving a file that was loaded and not changed must give back the same bytes. `test/persist/round_trip_test.rb` checks that for every `.gloo` file in `test.gloo/` and `test/gloo/projects/` (add a fixture to `test/gloo/projects/round_trip/` for a new construct). To check other folders, such as apps:
+
+```
+rake "round_trip[~/gloo/app,~/dev/gloo_apps]"
+```
+
+It copies each file to a scratch folder, loads it without running any scripts or `load lib` lines, saves it, and lists the files that came back different with their first changed line. The originals are never written.
+
 ## Documentation
 
 The narrative documentation is the set of flat pages in `docs/`, linked from the README. Two conventions keep them readable both on GitHub and in a terminal:

data/docs/language_objects.md

@@ -15,18 +15,19 @@
 Object names are single words (no spaces) and conform to the following:
 
 - Spaces in names are not allowed.
-- Names should be unique within their context.
-    - Note that there is no technical restriction. Multiple objects with the same name in the same context can exist, but there's no way to reference objects past the first one with the given name.
+- A name is unique within its container.
+    - Declaring a name again, in the same file or another one, names the same object: its children are added to the first one's, and its value is ignored (with a warning when it's different). `create` with a name that's already there leaves the object as it is, and `move` won't move an object into a container that already has its name.
 - Names can be capitalized or lower case.
-    - But names with different cases are not treated as unique.
+    - But names with different cases are not different names: `a` and `A` are the same object.
 - Names can contain numbers and special characters.
 
 ```gloo
 #
 # Example of object naming.
 #
-# NOTE that the second 'a' and the 'A' objects are not reachable.
-# 'naming.a' will always reach the 'First A' string.
+# NOTE that the second 'a' and the 'A' lines name the same object as
+# the first: 'naming.a' is 'First A', and loading warns that the other
+# two values are ignored.
 #
 naming [container] :
   on_load [script] :
@@ -35,8 +36,8 @@ naming [container] :
     show naming.1
   msg!$% [string] : Naming stuff
   a [string] : First A
-  a [string] : Second A is not reachable
-  A [string] : Capital A is not reachable
+  a [string] : Second A
+  A [string] : Capital A
   1 [string] : One
 ```
 
@@ -121,20 +122,24 @@ Every object can say which file it was loaded from: `check {obj} for
 source_file` puts the file's full path in `it`, and `check {obj} for
 source_dir` puts that file's folder (with no trailing slash). This lets a
 script reach files stored next to it without a hard-coded path. For
-example, a test can load a fixture that sits beside its own file:
+example, a script can read a data file that sits beside its own file:
 
 ```gloo
-tests.my_area [can] :
+report [can] :
   where [string] :
-  fixture [string] : /fixtures/sample.gloo
+  data [file] :
+  rows [string] :
 
-  loads_its_fixture [test] :
-    on_test [script] :
-      check ^^ for source_dir
-      put it into ^^.where
-      load ( ^^.where ^^.fixture )
+  on_load [script] :
+    check ^ for source_dir
+    put it into ^.where
+    put ^.where '/data/rows.txt' into ^.data
+    tell ^.data to read ( ^.rows )
 ```
 
+(A `load` doesn't need this: a relative name already looks next to the
+loading file first. See Application, Script Mode and App Mode.)
+
 The answer comes from the nearest object, going up from the one asked,
 that a loaded file declares. So a nested object answers with its file,
 even when its root container (like `tests` above) is declared in many

data/docs/language_scripting.md

@@ -9,7 +9,11 @@
 
 ## Gloo Script Files
 
-Gloo scripts are stored in regular text files with the `.gloo` extension.
+Gloo scripts are stored in regular text files with the `.gloo` extension. A file is UTF-8, whatever the locale gloo runs in (cron and launchd, for example, give a process a plain ASCII locale). A line with bytes that aren't UTF-8 still loads, with a warning: those bytes read as `�` (U+FFFD), and the file keeps them, so saving it doesn't change them.
+
+Indentation is what puts an object under another: one level deeper is a tab or two spaces. They can be mixed, from line to line or on one line (a tab and two spaces is two levels).
+
+An object is declared as `name [type] : value`. Spaces just inside the brackets don't matter: `[ int ]` and `[int ]` are `[int]`.
 
 Conventions:
 
@@ -85,7 +89,7 @@ constants [can] :
 
 ## Line Continuation
 
-In gloo scripting, a line continuation is done by ending a line with a backslash (`\`). Logical lines can be split across multiple physical lines of text in scripts. A line break is otherwise an indication of a new statement.
+In gloo scripting, a line continuation is done by ending a line with a backslash (`\`). Logical lines can be split across multiple physical lines of text in scripts. A line break is otherwise an indication of a new statement. Inside a `BEGIN` … `END` block a backslash is just a character: the block's lines are its value, exactly as written.
 
 ```gloo
 #

data/docs/testing.md

@@ -166,25 +166,22 @@ A test that's meant to fail, such as one that shows an assertion really does fai
       tell ^^.scratch to delete
 ```
 
-**Fixtures.** A file the tests read but never change can be kept next to the test file, for example in a `fixtures` folder. Name it something other than `*.test.gloo`, so it isn't run as a test. `check ^^ for source_dir` gives the folder of the test file (see Language, Objects, Where an Object Came From):
+**Fixtures.** A file the tests read but never change can be kept next to the test file, for example in a `fixtures` folder. Name it something other than `*.test.gloo`, so it isn't run as a test. A relative `load` looks next to the test file first (see Application, Script Mode and App Mode), so the fixture loads by its plain name:
 
 ```gloo
 tests.files [can] :
 
-  where [string] :
-  fixture [string] : /fixtures/sample.gloo
-
   loads_its_fixture [test] :
     description [string] : A fixture next to this file can be loaded.
     on_test [script] :
-      check ^^ for source_dir
-      put it into ^^.where
-      load ( ^^.where ^^.fixture )
+      load fixtures/sample
       eval sample.name = 'from the fixture'
       assert "expected the fixture to load"
       tell sample to unload
 ```
 
+For anything else that needs the test file's folder, such as the path of a data file to read or a program to run, `check ^^ for source_dir` gives it (see Language, Objects, Where an Object Came From).
+
 **Broken source on purpose.** To test how gloo handles a mistake in a file, such as a missing `]` or a declaration with no name, don't put the mistake in the test file itself. It would be reported while the file loads, outside any test. Instead, keep the broken source in a `[text]` object, write it to a scratch file inside the test, and load it there. The problem then belongs to that test, which sets `expect_errors`:
 
 ```gloo

data/docs/verbs.md

@@ -86,10 +86,10 @@ If the destination doesn't exist, or the expression can't be worked out (eg. it
 
 ## Load & Save
 
-`load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a path relative to the project folder, a full path, or one starting with `~` for your home folder; the `.gloo` extension is optional. `*` in place of a file name loads every `.gloo` file in a folder, wherever the folder is. Anything before the `*` is the start of the file names, so `my/app/a*` loads just the files whose names start with `a`.
+`load` reads a `.gloo` file into the heap and runs its `on_load` script. Give a relative name, a full path, or one starting with `~` for your home folder; the `.gloo` extension is optional. A relative name is looked for next to the file the loading script came from, in the projects folder, and in the gloo home; in App mode the app folder comes first (see Application, Script Mode and App Mode, for the order in each mode). `*` in place of a file name loads every `.gloo` file in a folder, found the same way. Anything before the `*` is the start of the file names, so `my/app/a*` loads just the files whose names start with `a`.
 
 ```gloo
-> load my/project/config
+> load parts/config
 > load my/app/*
 > load ~/.my_app/settings.gloo
 > load ~/.my_app/plugins/*
@@ -99,6 +99,8 @@ If the name can't be resolved to a file, `load` reports `File '{name}' was not f
 
 `save` writes loaded objects back to their files. With no argument it saves every open file; with an object it saves the file (or files) that object's tree came from; with `to {path}` it **extracts** — moves the object (and its descendants) out of whichever file currently owns them, into a new file, under their full dotted path.
 
+A new file — `save {obj} to {path}`, or `save {obj}` for a top-level object with no file yet (named after the object) — goes where a relative `load` would look first: in App mode the app folder; otherwise next to the file the saving script came from, or the working folder for a command typed at the prompt (see Application, Script Mode and App Mode). A script that didn't come from a file saves into the projects folder. A full path, or one starting with `~`, is used as given. An object that's already loaded always saves back to its own file.
+
 ```gloo
 > save                        # every open file
 > save config                 # just config's file
@@ -113,11 +115,29 @@ An object's doc comment goes wherever the object goes: it moves with a moved or
 
 A save never loses or alters data: loading the saved files again gives back the same objects, with the same values and docs, under the same parents. The interpreter decides how a changed or new declaration is laid out; only what it says has to come back the same.
 
+How a change is written:
+
+- A changed declaration keeps its name, type and spacing as written (an untyped `plain : old` stays untyped); only its value is written again.
+- A new object goes after the last child of its parent's first declaration, indented like its neighbours, with its type spelled the way the file spells it (`[int]` in a file of `[int]`s), so it looks like the rest of the file. A new child of a container that only exists through a dotted name (`page.core.users [can] :` makes `page` and `core`) is written as a dotted line too: `page.core.x [string] : v`.
+- A moved object takes its first declaration and its doc comment with it, at its new depth. Moving it into another file's container saves that file too.
+- An object deleted and then created again is a new object: it's written where new objects go, without the old doc comment.
+- A new top-level object isn't added to an existing file, so a bare `save` leaves it out and warns, naming it (`Not saved (no file yet): notes. Use save notes.`). `save {obj}` writes it to a file of its own, which later saves include.
+- A file that doesn't end with a line break still doesn't after a save.
+
+An object can be declared on more than one line — the same name twice in one container, or in more than one file (see Language, Objects, Object Naming). It's one object: its first declaration holds its value, so a change rewrites only that line, and the later lines stay exactly as written. Deleting or moving the object takes all of its lines with it, in every file, so a reload doesn't bring it back.
+
+A few things can't be written back exactly; save writes the closest thing and, for a value, warns `Could not save '{path}' exactly: {why}.`:
+
+- A multi-line value is written as a `BEGIN` … `END` block, its lines exactly as they are (a block's lines are its value, so they're not indented to match). A block value always ends with a line break, so a value without one gains it; a line that is just `END` would end the block early; and bytes that aren't UTF-8 are written as they are.
+- A value ending in `\` or `BEGIN` is written as a block, since on the line it would be read as a continuation or a block start.
+- A changed script body is written from its commands, at its original indentation; the comments and blank lines inside it are lost. (An untouched one is kept exactly.)
+- A declaration gloo had to guess at when loading — no name (`[int] : 3` loads as `unnamed_1`) or a missing `]` (`b [int : 3`) — is written as gloo understood it.
+
 `save {obj} to {path}` doesn't just write a copy — `obj` stops being declared in its old file, wherever that was. Given `app.core.settings` declared inside `app.gloo`, `save app.core.settings to config/settings` leaves `app.gloo` without a `settings` subtree and writes `config/settings.gloo` with `app.core.settings [can] : ...` at the top level (the `app`/`core` prefix is implied via nested-container shorthand, not repeated as nested declarations) plus everything `settings` owns underneath, comments included. An object with no file of its own yet (brand new, or nested under an object that's never been saved) is simply written fresh — nothing to move.
 
 If `obj`'s own subtree already has declarations spread across more than one file (the namespace-merge pattern below, applied *inside* the subtree being extracted, not just above it), extraction refuses rather than guessing which file's slice is authoritative — save each contributing file on its own first.
 
-Several files can contribute to one container — declare `app [container] :` in each and add different children. They merge in the heap, and each file's save only rewrites its own declarations. If two files declare the *same* object with different values, the first one loaded wins and `load` logs a warning.
+Several files can contribute to one container — declare `app [container] :` in each and add different children. They merge in the heap, and each file's save only rewrites its own declarations; a new child of `app` goes into the file with `app`'s first declaration (the first loaded). If two files declare the *same* object with different values, the first one loaded wins and `load` logs a warning — the same as two declarations in one file.
 
 An object can also save itself: `tell config to save`.
 

data/lib/VERSION

@@ -1 +1 @@
-7.1.3
+7.2

data/lib/VERSION_NOTES

@@ -1,3 +1,11 @@
+7.2 - 2026.11.04
+ - Update for lossless load and save: fixes a number of bugs.
+ - Allow spaces inside type brackets.
+ - Improves gloo startup time.
+ - A script run now exits 1 if an error or Ruby exception happened anywhere in the run.
+ - Improves how load and save verbs use relatives paths.
+
+
 7.1.3 - 2026.10.29
  - break in a loop's do skips to the next item again, as it did before 7.1.1.
  - New: break loop ends the whole loop. It's only valid directly in a loop's do script.

data/lib/dependencies.rb

@@ -23,7 +23,10 @@ end
 #
 # Now that we have the first with some key dependencies
 # at the top, we'll require them.
+# require_relative skips RubyGems' require hook, which
+# would otherwise search the installed gems for each file
+# (about 0.4 s of startup).
 #
 files.each do |ruby_file|
-  require ruby_file
+  require_relative ruby_file
 end

data/lib/gloo/app/engine.rb

@@ -17,7 +17,7 @@ module Gloo
       # 
       TEST_LIB_NAME = 'test'
 
-      attr_reader :settings, :log, :running_app
+      attr_reader :settings, :log, :running_app, :run_error_count
       attr_reader :args, :mode, :running, :platform,
                   :dictionary, :parser, :heap, :factory,
                   :ext_manager, :lib_manager
@@ -43,6 +43,7 @@ module Gloo
 
         @handling_exception = false
         @handling_error = false
+        @run_error_count = 0
         @log.debug 'engine intialized...'
       end
 
@@ -136,15 +137,14 @@ module Gloo
 
       #
       # Run files specified on the CLI.
-      # Then quit, with a non-zero exit code if any file failed to
-      # load (missing, unresolvable, or errored on load) so that a
-      # calling shell script can tell a bad run from a good one.
+      # Then quit, with exit status 1 if anything went wrong at any
+      # point in the run (see run_failed?), so that a calling shell
+      # script can tell a bad run from a good one.
       #
       def run_files
         load_files
-        failed = error?
         quit
-        exit( 1 ) if failed
+        exit( 1 ) if run_failed?
       end
 
       # 
@@ -337,6 +337,16 @@ module Gloo
         return !@heap.error.value.nil?
       end
 
+      #
+      # Did anything go wrong since the engine started: an error or
+      # a Ruby exception, whether or not on_error or on_exception
+      # handled it? A handler reports, it doesn't undo the failure.
+      # Warnings don't count.
+      #
+      def run_failed?
+        return @run_error_count.positive?
+      end
+
       #
       # Report an error.
       # Write it to the log and set the heap error value. Always logged;
@@ -356,6 +366,7 @@ module Gloo
         @log.error( location ? "#{location}: #{msg}" : msg )
         return unless @heap
 
+        @run_error_count += 1
         @heap.error.set_to msg, kind, location
 
         return if @handling_error
@@ -433,6 +444,7 @@ module Gloo
         backtrace = format_backtrace( ex )
         @log.error ex.message
         @log.backtrace backtrace
+        @run_error_count += 1
 
         return if @handling_exception
 

data/lib/gloo/core/obj.rb

@@ -127,29 +127,6 @@ module Gloo
         return false
       end
 
-      #
-      # Serialize this object's value for saving to a file.
-      # Returns the text that follows "name [type]" on the declaration
-      # line -- including the leading ' :' and, for a multi-line string
-      # value, the additional indented lines and the closing END marker.
-      # indent is the indentation level of the declaration line itself.
-      #
-      def serialize_value( indent )
-        return " : #{value_display}" unless value_string? && value.include?( "\n" )
-
-        return serialize_block_value( indent )
-      end
-
-      #
-      # Serialize a multi-line string value as a BEGIN/END block.
-      #
-      def serialize_block_value( indent )
-        t = "\t" * indent
-        inner = "\t" * ( indent + 1 )
-        body = value.split( "\n" ).map { |line| "#{inner}#{line}" }.join( "\n" )
-        return " : BEGIN\n#{body}\n#{t}END"
-      end
-
       #
       # Is the value a String?
       #

data/lib/gloo/objs/basic/script.rb

@@ -62,29 +62,6 @@ module Gloo
         return true
       end
 
-      #
-      # Serialize this object's value for saving to a file.
-      # A script's value is an Array of command lines (once add_line
-      # has been called) or a single-line String. Render as indented
-      # body lines below the declaration, gloo's convention for
-      # scripts -- not a BEGIN/END block, which is reserved for a
-      # literal multi-line string value.
-      #
-      def serialize_value( indent )
-        lines = if value_is_array?
-                  value
-                elsif value_string? && !value.strip.empty?
-                  [ value ]
-                else
-                  []
-                end
-        return ' :' if lines.empty?
-
-        t = "\t" * ( indent + 1 )
-        body = lines.map { |line| "#{t}#{line}" }.join( "\n" )
-        return " :\n#{body}"
-      end
-
       #
       # Get the number of lines in this script.
       #

data/lib/gloo/persist/declaration_ledger.rb

@@ -3,8 +3,8 @@
 #
 # Tracks what a single file declares as it loads: its top-level
 # objects (for save resolution), and every object it created -- so a
-# re-declaration of a name an earlier file already used can be
-# flagged, since in that case the second value is silently dropped.
+# re-declaration of a name already used, in an earlier file or earlier
+# in this one, can be flagged when its value is ignored.
 #
 
 module Gloo
@@ -39,19 +39,19 @@ module Gloo
 
       #
       # `prior` already existed when this file declared `name` with
-      # `value`. If another file created it and the values differ, the
-      # new value is being ignored -- warn so it isn't a surprise. A
-      # duplicate name inside one file is left alone (a documented
-      # "first one wins"). The warning's location (this file and line)
-      # comes from the load.
+      # `value`: the line names the same object, and its value is
+      # ignored (the first declaration wins). When the ignored value is
+      # different, warn so it isn't a surprise -- whether the first
+      # declaration was in another file or earlier in this one. The
+      # warning's location (this file and line) comes from the load.
       #
       def clash( prior, name, value )
-        return if @mine.key?( prior )
         return if value.nil? || value.to_s.strip.empty?
         return if prior.value.to_s == value.to_s
 
+        where = @mine.key?( prior ) ? 'above' : 'in another loaded file'
         @engine.warn(
-          "'#{name}' is already declared in another loaded file with a " \
+          "'#{name}' is already declared #{where} with a " \
           "different value (#{prior.value.inspect} kept, #{value.inspect} ignored)."
         )
       end