Absolute qual id users guide

docs/fpp-spec.html

@@ -14526,7 +14526,7 @@ <h3 id="Analysis-and-Translation_Translation-Tools">25.4. Translation Tools</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-10-06 17:41:34 -0700
+Last updated 2026-10-06 18:15:25 -0700
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/fpp-users-guide.html

@@ -2100,7 +2100,8 @@ <h2 id="Defining-Modules">5. Defining Modules</h2>
 encloses.
 To write the qualified name, you write the qualifier, a dot, and the base name:
 for example <code>M.a</code>. (This is also the way that
-name qualification works in Python, Java, and Scala.)
+name qualification works in Python, Java, and Scala.
+The C&#43;&#43; equivalent is <code>M::a</code>.)
 Inside the module, you can use the qualified name or the unqualified
 name.
 Outside the module, you must use the qualified name.
@@ -2119,6 +2120,31 @@ <h2 id="Defining-Modules">5. Defining Modules</h2>
 </div>
 </div>
 <div class="paragraph">
+<p>Optionally, you can write a qualified name with a leading dot.
+This form says to compute the name starting at the top, instead
+of starting at the current level.
+For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="prettyprint highlight"><code data-lang="fpp">constant a = 0
+module M {
+  constant a = 1
+  constant b = a # a refers to M.a here; b = 1
+  constant c = .a # a refers to a here; c = 0
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As shown in the example, the leading-dot form is useful when
+a definition is hidden or <strong>shadowed</strong> by another definition
+with the same unqualified name in an inner scope.
+In the example above, inside module <code>M</code>, the name <code>a</code>
+refers to <code>M.a</code>, so to refer to the constant <code>a</code> defined at the top
+level, we have to write <code>.a</code>.
+(The C&#43;&#43; equivalent is <code>::a</code>.)</p>
+</div>
+<div class="paragraph">
 <p>As with namespaces in C&#43;&#43;, you can close a module definition and
 reopen it later.
 All the definitions enclosed by the same name go in the module
@@ -14632,6 +14658,20 @@ <h4 id="Specifying-Models-as-Files_Location-Specifiers_Definition-Names">17.4.3.
 which occurs before the analyzer has complete information about
 definitions and their uses.</p>
 </div>
+<div class="paragraph">
+<p>You can also write a location specifier using the <a href="#Defining-Modules">leading
+dot syntax</a>, like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="prettyprint highlight"><code data-lang="fpp">module M { locate constant .a at "M.fpp" }</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>In this case, the name <code>.a</code> is resolve to <code>a</code>, not <code>M.a</code>.
+The leading dot says to start the resolution at the top level,
+regardless of where the location specifier appears in the model.</p>
+</div>
 </div>
 <div class="sect3">
 <h4 id="Specifying-Models-as-Files_Location-Specifiers_Included-Files">17.4.4. Included Files</h4>
@@ -14756,9 +14796,16 @@ <h4 id="Specifying-Models-as-Files_Locating-Definitions_Running-fpp-locate-defs"
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="prettyprint highlight"><code data-lang="fpp">locate constant a at "Constants/a.fpp"</code></pre>
+<pre class="prettyprint highlight"><code data-lang="fpp">locate constant .a at "Constants/a.fpp"</code></pre>
 </div>
 </div>
+<div class="paragraph">
+<p>Notice that the tool uses the <a href="#Defining-Modules">leading dot</a>
+form of the definition name.
+That is because the names are always specified from the top level.
+The leading dot ensures that the name will have the same meaning
+regardless of where the location specifier appears in the model.</p>
+</div>
 </div>
 <div class="sect3">
 <h4 id="Specifying-Models-as-Files_Locating-Definitions_Location-Paths">17.5.2. Location Paths</h4>
@@ -14778,7 +14825,7 @@ <h4 id="Specifying-Models-as-Files_Locating-Definitions_Location-Paths">17.5.2.
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="prettyprint highlight"><code data-lang="fpp">locate constant a at "a.fpp"</code></pre>
+<pre class="prettyprint highlight"><code data-lang="fpp">locate constant .a at "a.fpp"</code></pre>
 </div>
 </div>
 </div>
@@ -18524,7 +18571,7 @@ <h3 id="Writing-C-Plus-Plus-Implementations_Serialization-of-FPP-Values">19.4. S
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-10-06 17:50:49 -0700
+Last updated 2026-10-06 18:15:28 -0700
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/users-guide/Defining-Modules.adoc

@@ -23,7 +23,8 @@ The name of a module qualifies the names of all the definitions that the module
 encloses.
 To write the qualified name, you write the qualifier, a dot, and the base name: 
 for example `M.a`. (This is also the way that
-name qualification works in Python, Java, and Scala.)
+name qualification works in Python, Java, and Scala.
+The {cpp} equivalent is `M::a`.)
 Inside the module, you can use the qualified name or the unqualified
 name.
 Outside the module, you must use the qualified name.
@@ -41,6 +42,29 @@ constant a = M.a
 constant c = b # Error: b is not in scope here
 --------
 
+Optionally, you can write a qualified name with a leading dot.
+This form says to compute the name starting at the top, instead
+of starting at the current level.
+For example:
+
+[source,fpp]
+----
+constant a = 0
+module M {
+  constant a = 1
+  constant b = a # a refers to M.a here; b = 1
+  constant c = .a # a refers to a here; c = 0
+}
+----
+
+As shown in the example, the leading-dot form is useful when
+a definition is hidden or *shadowed* by another definition
+with the same unqualified name in an inner scope.
+In the example above, inside module `M`, the name `a`
+refers to `M.a`, so to refer to the constant `a` defined at the top
+level, we have to write `.a`.
+(The {cpp} equivalent is `::a`.)
+
 As with namespaces in {cpp}, you can close a module definition and
 reopen it later.
 All the definitions enclosed by the same name go in the module

docs/users-guide/Specifying-Models-as-Files.adoc

@@ -434,6 +434,18 @@ The purpose of this rule is to facilitate dependency analysis,
 which occurs before the analyzer has complete information about
 definitions and their uses.
 
+You can also write a location specifier using the <<Defining-Modules,leading 
+dot syntax>>, like this:
+
+[source,fpp]
+----
+module M { locate constant .a at "M.fpp" }
+----
+
+In this case, the name `.a` is resolve to `a`, not `M.a`.
+The leading dot says to start the resolution at the top level,
+regardless of where the location specifier appears in the model.
+
 ==== Included Files
 
 When you write a file that contains definitions and you 
@@ -530,9 +542,15 @@ generates the location specifier
 
 [source,fpp]
 ----
-locate constant a at "Constants/a.fpp"
+locate constant .a at "Constants/a.fpp"
 ----
 
+Notice that the tool uses the <<Defining-Modules,leading dot>>
+form of the definition name.
+That is because the names are always specified from the top level.
+The leading dot ensures that the name will have the same meaning
+regardless of where the location specifier appears in the model.
+
 ==== Location Paths
 
 By default, the location path is relative to the current 
@@ -548,7 +566,7 @@ generates the location specifier
 
 [source,fpp]
 ----
-locate constant a at "a.fpp"
+locate constant .a at "a.fpp"
 ----
 
 ==== Included Definitions