From e5c8ff50d8d0f917e8aa925a876463c11fabbb12 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 8 Sep 2026 16:17:44 -0700 Subject: [PATCH 1/2] Revise User's Guide --- docs/fpp-users-guide.html | 51 +++++++++++++++++-- docs/users-guide/Defining-Modules.adoc | 22 ++++++++ .../Specifying-Models-as-Files.adoc | 22 +++++++- 3 files changed, 90 insertions(+), 5 deletions(-) diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 967e773ec..800b199c7 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -2096,6 +2096,30 @@

5. Defining Modules

+

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:

+
+
+
+
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.

+
+

As with namespaces in C++, you can close a module definition and reopen it later. All the definitions enclosed by the same name go in the module @@ -13779,6 +13803,20 @@

16.4.3. which occurs before the analyzer has complete information about definitions and their uses.

+
+

You can also write a location specifier using the leading +dot syntax, like this:

+
+
+
+
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.

+

16.4.4. Included Files

@@ -13903,8 +13941,15 @@

-
locate constant a at "Constants/a.fpp"
+
locate constant .a at "Constants/a.fpp"
+
+
+

Notice that the tool uses the 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.

@@ -13925,7 +13970,7 @@

16.5.2.

-
locate constant a at "a.fpp"
+
locate constant .a at "a.fpp"
@@ -17353,7 +17398,7 @@

18.4. S diff --git a/docs/users-guide/Defining-Modules.adoc b/docs/users-guide/Defining-Modules.adoc index 0560b71ca..f47794a65 100644 --- a/docs/users-guide/Defining-Modules.adoc +++ b/docs/users-guide/Defining-Modules.adoc @@ -41,6 +41,28 @@ 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`. + 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 diff --git a/docs/users-guide/Specifying-Models-as-Files.adoc b/docs/users-guide/Specifying-Models-as-Files.adoc index 584682d7b..cc699dff4 100644 --- a/docs/users-guide/Specifying-Models-as-Files.adoc +++ b/docs/users-guide/Specifying-Models-as-Files.adoc @@ -431,6 +431,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 <>, 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 @@ -527,9 +539,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 <> +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 @@ -545,7 +563,7 @@ generates the location specifier [source,fpp] ---- -locate constant a at "a.fpp" +locate constant .a at "a.fpp" ---- ==== Included Definitions From 2b8ea04acd8508e1f21d95bb7506d8535542a4a3 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 6 Oct 2026 18:16:46 -0700 Subject: [PATCH 2/2] Revise User's Guide --- docs/fpp-spec.html | 2 +- docs/fpp-users-guide.html | 8 +++++--- docs/users-guide/Defining-Modules.adoc | 4 +++- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index ba8ae4900..11261ce23 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -14526,7 +14526,7 @@

25.4. Translation Tools

diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 94d12f735..9e86df0f4 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -2100,7 +2100,8 @@

5. Defining Modules

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 C++ 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. @@ -2140,7 +2141,8 @@

5. Defining Modules

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.

+level, we have to write .a. +(The C++ equivalent is ::a.)

As with namespaces in C++, you can close a module definition and @@ -18569,7 +18571,7 @@

19.4. S

diff --git a/docs/users-guide/Defining-Modules.adoc b/docs/users-guide/Defining-Modules.adoc index f47794a65..eafd6e5ff 100644 --- a/docs/users-guide/Defining-Modules.adoc +++ b/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. @@ -62,6 +63,7 @@ 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.