From 049586c3f0899a4de651ffd4fcfe59e5940ac9a3 Mon Sep 17 00:00:00 2001 From: Drew Date: Mon, 22 Jun 2026 12:59:14 -0400 Subject: [PATCH 1/6] spec: add canonical two-namespace definition page Introduce spec/namespaces.rst as the single source of truth for Gazprea's namespace rules: a type namespace (structs, typealiases) and a separate variable/function/procedure namespace. Subsequent commits remove the conflicting per-file descriptions that this page replaces. --- gazprea/spec/namespaces.rst | 44 +++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 gazprea/spec/namespaces.rst diff --git a/gazprea/spec/namespaces.rst b/gazprea/spec/namespaces.rst new file mode 100644 index 0000000..17305a3 --- /dev/null +++ b/gazprea/spec/namespaces.rst @@ -0,0 +1,44 @@ +.. _sec:namespaces: + +Namespaces +========== + +There are two namespaces in *Gazprea*: + +- Type namespace: user-defined types (structs and typealiases). +- Variable/function/procedure namespace: variables, functions, and procedures. + +Items in separate namespaces may share an identifier. Items within the same +namespace cannot share an identifier; this is a ``SymbolError``. + +:: + + // Does not conflict with the other statements + struct x (integer a, integer b); + + // These three statements all conflict with each other. + // Any two of them in the same program produces a SymbolError. + integer x = 3; + function x() returns integer; + procedure x() returns integer; + +:: + + // Type names and value names live in separate namespaces, so the + // following identifiers do not collide. + + typealias integer a; + typealias integer main; // Procedure and type do not conflict + struct b (a b, a a, main main); // Struct field names do not conflict with anything + + procedure main() returns integer { + + a a = 1; // type and variable do not conflict + + b b = b(a, 2, 3); + + if (true) { // New scope + a a = b.b; // New `a` shadows the old `a` + } + return 0; + } From 15a413314da7356de2c1c1ddcf84fb97ba425aa0 Mon Sep 17 00:00:00 2001 From: Drew Date: Mon, 22 Jun 2026 12:59:28 -0400 Subject: [PATCH 2/6] spec: register namespaces page in the toctree Add spec/namespaces to the Language Specification toctree, immediately after identifiers, so the new page is included in the rendered docs. --- gazprea/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/gazprea/index.rst b/gazprea/index.rst index 54a4f74..5eda096 100644 --- a/gazprea/index.rst +++ b/gazprea/index.rst @@ -18,6 +18,7 @@ Hardware Acceleration Laboratory in Markham, ON. spec/keywords spec/identifiers + spec/namespaces spec/comments spec/declarations spec/type_qualifiers From c5270fc1aa68d6486127dc0be59594d4a749c45a Mon Sep 17 00:00:00 2001 From: Drew Date: Mon, 22 Jun 2026 12:59:47 -0400 Subject: [PATCH 3/6] spec: remove outdated Namespaces section from identifiers The Namespaces section in identifiers.rst described a one-namespace model in which struct literals shared the function namespace, contradicting the two-namespace model used elsewhere. Replace it with a cross-reference to the canonical spec/namespaces page. No remaining references to the removed ssec:namespace label exist. --- gazprea/spec/identifiers.rst | 32 ++------------------------------ 1 file changed, 2 insertions(+), 30 deletions(-) diff --git a/gazprea/spec/identifiers.rst b/gazprea/spec/identifiers.rst index 4e742da..275659b 100644 --- a/gazprea/spec/identifiers.rst +++ b/gazprea/spec/identifiers.rst @@ -31,33 +31,5 @@ a number, contain invalid characters, or are a keyword: *Gazprea* imposes no restrictions on the length of identifiers. -.. _ssec:namespace: - -Namespaces -========== - -Identifiers are used by variables, user-defined types, functions and procedures. - -For the most part, user-defined types are in their own namespace because their -usage does not collide with variables or functions. -The one exception is that struct literals can look like function calls: - -:: - - struct A (integer i, real j); - A a = A(i, j); - -Consequently, struct literals and functions share the same namespace. -In the above example, a definition of function ``A`` should generate a -``SymbolError``, but a definition of variable ``A`` would not. -Outside of types, variables and functions/procedures share the same namespace -in a scope and shadowing is possible between these types. - -:: - - function x() returns integer; // "x" refers to this function in the global scope - - procedure main() { - integer x = 3; // "x" refers to this variable in the scope of main - } - ... +The rules governing which identifiers may coexist are described in +:ref:`sec:namespaces`. From a18de4121966a57f7d320dec09637288298417f2 Mon Sep 17 00:00:00 2001 From: Drew Date: Mon, 22 Jun 2026 13:00:06 -0400 Subject: [PATCH 4/6] spec: align struct namespacing with two-namespace model State that structs live in the type namespace and never conflict with variables, functions, or procedures, replacing the old claim that structs share the function and procedure namespaces. Rename the section label from the duplicated ssec:function_namespacing to ssec:struct_namespacing to remove the ambiguous-label collision (one of three identical definitions). --- gazprea/spec/types/struct.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/gazprea/spec/types/struct.rst b/gazprea/spec/types/struct.rst index 5a0a424..6bb5453 100644 --- a/gazprea/spec/types/struct.rst +++ b/gazprea/spec/types/struct.rst @@ -139,19 +139,14 @@ A struct itself cannot be cast or promoted. However, the fields within a struct can be individually cast/promoted, as described in sections :ref:`sec:typeCasting` and :ref:`sec:typePromotion`. -.. _ssec:function_namespacing: +.. _ssec:struct_namespacing: Struct Namespacing --------------------- +------------------ In *Gazprea*, struct declarations can occur in *any* scope. This means that two struct types with the same name *can* coexist in the same -gazprea program so long as they are not in the same scope +gazprea program so long as they are not in the same scope. -Additionally, ``structs`` share the following namespaces: - -- The ``procedure`` namespace: You cannot have a procedure and struct with - the same name in the same gazprea program. - -- The ``function`` namespace: You cannot have a function and struct with - the same name in the same gazprea program. +Structs live in the type namespace and therefore never conflict with variables, +functions, or procedures. See :ref:`sec:namespaces`. From 9a678caceb75f3aa6b5b33e3c9b70b01f655132d Mon Sep 17 00:00:00 2001 From: Drew Date: Mon, 22 Jun 2026 13:00:17 -0400 Subject: [PATCH 5/6] spec: align function namespacing with two-namespace model Replace the claim that functions share the struct and procedure namespaces with the correct rule: functions and procedures share one namespace and do not conflict with types. The section label ssec:function_namespacing is retained and is now unique after the struct section was renamed. --- gazprea/spec/functions.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/gazprea/spec/functions.rst b/gazprea/spec/functions.rst index 5cc1403..6975d2e 100644 --- a/gazprea/spec/functions.rst +++ b/gazprea/spec/functions.rst @@ -211,10 +211,6 @@ In *Gazprea* function declarations occur in the global scope. This means that two functions with the same name cannot coexist in the same gazprea program, nor can you forward declare the same function twice. -Additionally, functions share the following namespaces: - -- The ``struct`` namespace: you cannot have a struct and function with the same - name in the same gazprea program. - -- The ``procedure`` namespace: You cannot have a procedure and function with - the same name in the same gazprea program. +Functions and procedures share one namespace, so you cannot declare a function +and a procedure with the same name. Functions do not conflict with user-defined +types. See :ref:`sec:namespaces`. From 927584c96031e6cdfbb5af685837b9b324cd1d81 Mon Sep 17 00:00:00 2001 From: Drew Date: Mon, 22 Jun 2026 13:00:29 -0400 Subject: [PATCH 6/6] spec: align procedure namespacing with two-namespace model Replace the claim that procedures share the struct and function namespaces with the correct rule: procedures and functions share one namespace and do not conflict with types. Rename the section label from the duplicated ssec:function_namespacing to ssec:procedure_namespacing, removing the last of the three colliding label definitions. --- gazprea/spec/procedures.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/gazprea/spec/procedures.rst b/gazprea/spec/procedures.rst index af95cdb..ceff4ba 100644 --- a/gazprea/spec/procedures.rst +++ b/gazprea/spec/procedures.rst @@ -237,19 +237,15 @@ value of procedures can have both explicit and inferred sizes. Similarly, slices can be used whereever arrays are declared as parameters, and unlike functions, array parameters in procedures can be ``var``. -.. _ssec:function_namespacing: +.. _ssec:procedure_namespacing: Procedure Namespacing --------------------- +--------------------- In *Gazprea* procedure declarations occur in the global scope. This means that two procedures with the same name cannot coexist in the same gazprea program, nor can you forward declare the same procedure twice. -Additionally, procedures share the following namespaces: - -- The ``struct`` namespace: you cannot have a struct and function with the same - name in the same gazprea program. - -- The ``function`` namespace: You cannot have a procedure and function with - the same name in the same gazprea program. +Procedures and functions share one namespace, so you cannot declare a procedure +and a function with the same name. Procedures do not conflict with user-defined +types. See :ref:`sec:namespaces`.