feat(pbs): support quoted project imports and installed authoring contracts
This commit is contained in:
@@ -17,6 +17,17 @@ Its purpose is to make diagnostics stable enough that:
|
||||
|
||||
## 2. Scope
|
||||
|
||||
The installed `pbs:example:game:1:production/GUIDE.md` reference maps global
|
||||
initializer, visibility, malformed project-address and unresolved-import
|
||||
diagnostics to their normative rules and complete positive/negative examples.
|
||||
Codes retain their existing identity; a bounds fault remains an execution
|
||||
outcome rather than a fabricated compile-time diagnostic. Blank quoted project
|
||||
names are source errors, not internal `ModuleReference` construction exceptions.
|
||||
|
||||
Existing explanation payloads have no navigable reference-ID field for these
|
||||
mappings. Tools MUST preserve that limitation and use the explicit installed
|
||||
guide rather than infer rules from rendered messages or expand a public schema.
|
||||
|
||||
This document defines:
|
||||
|
||||
- the required external diagnostic phases,
|
||||
|
||||
@@ -234,10 +234,27 @@ Imports target modules, never files.
|
||||
ImportDecl ::= 'import' ( ModuleRef | '{' ImportList '}' 'from' ModuleRef ) ';'
|
||||
ImportList ::= ImportItem (',' ImportItem)*
|
||||
ImportItem ::= Identifier ('as' Identifier)?
|
||||
ModuleRef ::= '@' Identifier ':' ModulePath
|
||||
ModuleRef ::= '@' ProjectName ':' ModulePath
|
||||
ProjectName ::= Identifier | StringLiteral
|
||||
ModulePath ::= Identifier ('/' Identifier)*
|
||||
```
|
||||
|
||||
`StringLiteral` here is the ordinary double-quoted string from section 4, with
|
||||
only the existing `\\`, `\"`, `\n`, `\r` and `\t` escapes. Text blocks and
|
||||
expressions are not project names. The decoded value must be nonblank and
|
||||
identifies the exact manifest project name; delimiters do not become identity.
|
||||
|
||||
```pbs
|
||||
import { Inventory } from @"zelda-1":inventory;
|
||||
import { Collision } from @"physics-2d":collision;
|
||||
```
|
||||
|
||||
This alternative applies to both module and named imports. Existing identifier
|
||||
imports remain valid. Quoting is limited to the project segment: module paths
|
||||
retain identifier segments. Unquoted `@zelda-1:inventory` is malformed; use
|
||||
`@"zelda-1":inventory`. Quoting does not create a universal current-project alias.
|
||||
See specification 5 for exact identity and reserved-space resolution.
|
||||
|
||||
### 6.1.1 Attributes
|
||||
|
||||
Attributes are bracketed compile-time metadata forms.
|
||||
|
||||
@@ -335,6 +335,27 @@ Rules:
|
||||
- `if`,
|
||||
- and `switch`.
|
||||
|
||||
#### Authoring state with private implementation details
|
||||
|
||||
Keep state construction and its private helper types in the defining module;
|
||||
expose operations and public result types rather than requiring consumers to
|
||||
construct the implementation. File-private declarations stay in their defining
|
||||
file. Use `mod` barrel entries for admitted sibling-file access and `pub` entries
|
||||
for importing modules. A private dependency used by a public implementation does
|
||||
not become a caller-visible declaration.
|
||||
|
||||
Use supported direct construction in global initializers and perform procedural
|
||||
factory calls in admitted executable contexts, including permitted `[Init]`
|
||||
bodies. This does not admit factory calls into global initializers or provide
|
||||
automatic placeholder values. The existing transitive init-admission rules and
|
||||
one-shot bootstrap order in specification 9 still apply. Imports of globals and
|
||||
services preserve their defining storage and singleton identity.
|
||||
|
||||
The installed `pbs:example:game:1:production/GUIDE.md` reference and its complete
|
||||
projects demonstrate these boundaries, including deliberately rejected controls.
|
||||
Joining files, exporting helpers or renaming private types is not a language
|
||||
requirement for the corrected production binding cases.
|
||||
|
||||
### 3.5 Enum declarations and values
|
||||
|
||||
Rules:
|
||||
|
||||
+32
-4
@@ -104,6 +104,27 @@ Rules:
|
||||
- Module path segments are directory-style segments separated by `/`.
|
||||
- The syntax is Java-like in organization and JavaScript-like in import surface.
|
||||
|
||||
The project segment accepts an identifier or ordinary quoted string, as defined
|
||||
in specification 3. `@game:state` and `@"game":state` resolve to the same canonical
|
||||
module; `@"zelda-1":state` represents the exact manifest name `zelda-1`.
|
||||
|
||||
The decoded string MUST match the existing resolved project name exactly. There
|
||||
is no trimming, case folding, slug conversion or path interpretation. Empty or
|
||||
blank names are source errors. The quoted representation works for the owning
|
||||
project and ordinary dependencies, including a dependency referencing its own
|
||||
modules. It does not discover dependencies or change their declared graph.
|
||||
`@app` is an ordinary project name, not a universal self alias.
|
||||
|
||||
Reserved-space checks use the decoded name: `@"sdk":gfx` and `@"core":color`
|
||||
still resolve exclusively against the selected stdlib. Quoting cannot bypass
|
||||
visibility, canonical-origin collisions or reserved-space rules. Source producers
|
||||
MUST quote and escape names that are not legal non-keyword PBS identifiers.
|
||||
|
||||
Well-formed but unavailable project/module names fail resolution; malformed
|
||||
literals fail lexical/syntax analysis. A frontend supporting this additive
|
||||
syntax is required to consume new quoted sources. Existing sources, the common
|
||||
manifest name contract, stdlib major, ABI and PBX remain unchanged.
|
||||
|
||||
Examples:
|
||||
|
||||
- `@game:player/state`
|
||||
@@ -199,12 +220,18 @@ Rules:
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
import { Gfx, color } from @sdk:gfx;
|
||||
import { Gfx } from @sdk:gfx;
|
||||
import { Color } from @core:color;
|
||||
|
||||
let c: color = color.red;
|
||||
Gfx.draw_pixel(1, 1, c);
|
||||
[Frame] fn frame() -> void {
|
||||
Gfx.fill_rect(1, 1, 8, 8, Color.rgb(255, 0, 0));
|
||||
}
|
||||
```
|
||||
|
||||
This Game source belongs to a module with `pub fn frame() -> void;` in its
|
||||
`mod.barrel`. The complete manifest and module are installed in the production
|
||||
Gfx example, indexed through `pbs:example:game:1:production/GUIDE.md`.
|
||||
|
||||
Rules:
|
||||
|
||||
- `Gfx` is not implicitly in scope.
|
||||
@@ -371,7 +398,8 @@ Rules:
|
||||
|
||||
### 9.4 Example interface module
|
||||
|
||||
Illustrative stdlib interface module:
|
||||
Illustrative stdlib interface module (hypothetical metadata example, not the
|
||||
distributed Game SDK API; use the actual Gfx/Color imports above for game code):
|
||||
|
||||
```pbs
|
||||
declare enum color(red, green, blue);
|
||||
|
||||
@@ -134,6 +134,27 @@ Nominal manifest metadata does not participate in this runtime boot choice.
|
||||
|
||||
The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise.
|
||||
|
||||
Boolean `&&` and `and` are equivalent eager conjunction operators; `||` and `or`
|
||||
are equivalent eager disjunction operators. None provides short-circuit
|
||||
evaluation. Each operand is evaluated once, left then right, before the operation,
|
||||
unless abrupt completion prevents subsequent evaluation. A false left operand
|
||||
of conjunction or true left operand of disjunction does not skip the right one.
|
||||
|
||||
Use nested `if` when a later call or access must depend on a prior check:
|
||||
|
||||
```pbs
|
||||
if index >= 0 {
|
||||
if index < values.length {
|
||||
if let value = values[index] { consume(value); }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is an illustrative body fragment; `values`, `index` and `consume` come from
|
||||
the surrounding program. `index < values.length && read(values[index])` does not
|
||||
protect the access. The installed production examples count evaluation effects
|
||||
and distinguish the safe guard from deliberately faulting eager operands.
|
||||
|
||||
### 7.2 Call evaluation
|
||||
|
||||
For application:
|
||||
@@ -205,6 +226,11 @@ At minimum, the following are abrupt-completion forms:
|
||||
|
||||
`else` is extraction with fallback, not error handling.
|
||||
|
||||
In particular, `values[index] else fallback` evaluates the array access first.
|
||||
A vacant position at a valid index can yield `none` and select the fallback;
|
||||
an invalid index faults, including in an empty array, before any fallback can
|
||||
recover a value. See specification 14 for the fixed-array contract.
|
||||
|
||||
### 9.4 Trap behavior
|
||||
|
||||
`optional` is trap-free by itself.
|
||||
|
||||
@@ -151,6 +151,12 @@ Host-owner lookup remains separate from type, value, and callable lookup.
|
||||
|
||||
### 8.1 Effective local imported name
|
||||
|
||||
PBS source project segments may use the identifier or quoted spelling defined
|
||||
in PBS specification 3. The frontend decodes the segment before common module
|
||||
identity/resolution. Equivalent spellings MUST share canonical project/module
|
||||
origin and preserve all collision and reserved-space rules below. Source quoting
|
||||
does not restrict common manifest names or introduce a self-project alias.
|
||||
|
||||
The local visible name introduced by an import is always the post-alias name when an alias is present.
|
||||
|
||||
Rules:
|
||||
|
||||
Reference in New Issue
Block a user