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 c16c72d11..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. @@ -2119,6 +2120,31 @@

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. +(The C++ equivalent is ::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 @@ -14632,6 +14658,20 @@

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

+

17.4.4. Included Files

@@ -14756,9 +14796,16 @@

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

+

17.5.2. Location Paths

@@ -14778,7 +14825,7 @@

17.5.2.

-
locate constant a at "a.fpp"
+
locate constant .a at "a.fpp"
@@ -18524,7 +18571,7 @@

19.4. S diff --git a/docs/users-guide/Defining-Modules.adoc b/docs/users-guide/Defining-Modules.adoc index 0560b71ca..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. @@ -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 diff --git a/docs/users-guide/Specifying-Models-as-Files.adoc b/docs/users-guide/Specifying-Models-as-Files.adoc index 02c95631d..7e6deb3ca 100644 --- a/docs/users-guide/Specifying-Models-as-Files.adoc +++ b/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 <>, 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 <> +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