Repository navigation
Aliases and Native Blocks
PlainLogic 0.3 keeps a small common syntax while providing explicit ways to express behavior that depends on the target language. Use English for understandable behavior, an alias for a reusable body-taking behavior, and native code when exact target syntax matters. None of these establishes that the requested runtime can supply a promised guarantee.
See Syntax reference for the common subset and Examples for more complete documents.
This is an informal fragment, accepted as input by the agent workflow without canonical document headers:
alias NewThread -> Create and run new coroutine
NewThread:
for i = 1 to 100:
> Print i to console
alias Name -> description declares a document-local behavior. The invocation is the bare name followed by : and a required indented body. The body is supplied to the behavior as a unit. Aliases are not text macros or type aliases, and their names do not prove a matching target API exists.
Everything after the first -> is literal descriptive text, including quotes, #, additional arrows, punctuation, and Unicode. Alias declarations must be top-level and cannot have a body themselves. Invocations can occur at top level or inside a routine, English block, or another alias body. Forward invocations are allowed, but the document must declare exactly one matching alias. Aliases share the namespace with other top-level declarations; duplicates and collisions are errors.
Version 0.3 does not define arguments or return values for alias invocations. Run(1): and result = Run() are not alias syntax. Use a function, port, prose step, or native block when those are needed. An alias invocation has no automatic else/elif clause.
The description and context must settle material behavior: when and how often the body runs, scheduling, captured values, lifetime, failures, and the destinations of return, break, and continue. Do not infer synchronous or exactly-once execution from an alias's spelling. The VS Code extension gives alias bodies conservative local scopes; it does not link captured outer variables for completion or rename automatically.
For the example's intended target, distinguish Lua from host-specific dialects/runtimes. Lua coroutines do not imply operating-system threads, and resumption behavior must be clear. Consult the chosen runtime's documentation, such as the Lua 5.4 coroutine reference, when implementing.
This complete document makes the small example's scope explicit:
plainlogic 0.3
unit CoroutineExample
state ready
target "lua 5.4"
intent "Print integers 1 through 100 inside a newly created and started coroutine."
scope "One body, no yielding, extra scheduler, or native OS thread."
require R1 "Create and start a coroutine whose body prints each integer 1 through 100 once."
covers R1
alias NewThread -> Create and run new coroutine
NewThread:
for i = 1 to 100:
> Print i to console
Top-level covers R1 declares coverage for top-level alias/native behavior. At most one such line is allowed, and it needs a top-level invocation or native block. Functions continue to use their own covers entries. Alias declarations alone do not supply a document's required behavior unit. Coverage remains a declaration, not a semantic proof.
The statement excerpt for i = first to last: means:
- Evaluate
first, thenlast, once each before the loop. - Count upward by one and include both endpoints.
- Execute no iterations if
firstis greater thanlast. - Assign each integer to the loop variable before executing its body.
The variable belongs to its containing logical scope, retaining its last assigned value after an executed loop. An empty loop does not assign it. The checker does not prove that the bounds are integers or that the target's numeric behavior matches.
to is recognized outside strings and nested brackets: for i = first to len(values): is a counted loop, while a string containing " to " does not split a bound. Descending loops and custom steps use prose or native code; step is not part of the counted-loop grammar. This is PlainLogic notation, not a promise of matching target syntax.
Use native "language": or a simple unquoted label such as native lua:. The label is descriptive data, not an executable selector. Optional target "language/runtime/version" is document-level metadata; it does not select a compiler. A document can contain deliberate mixed-language regions, but their interfaces need validation.
Native blocks are allowed at top level for imports, declarations, attributes, interfaces, or macros, and inside function, alias, or prose bodies for target statements. Here is a complete canonical example from the repository:
plainlogic 0.3
unit NativeTarget
state ready
target "TypeScript 4.9 or later"
intent "Represent a generic target declaration and preserve its values through a routine."
scope "Illustrate exact target syntax; declarations and return behavior only."
require R1 "Declare a generic Pair<T> target type containing first and second values of T."
require R2 "Return both supplied text values as a Pair<Text> without changing them."
covers R1
native "typescript":
type Pair<T> = { first: T; second: T };
fn make_pair(first: Text, second: Text) -> Pair[Text]:
covers R2
native typescript:
return { first, second } satisfies Pair<string>;
Pair[Text] is a symbolic generic type application. Its mapping to Pair<string> is part of implementing the target contract; the checker does not infer the relationship. The TypeScript example is preserved target text, not code executed by PlainLogic tools.
Every nonblank native body line retains four spaces beyond the header's indentation as a container margin. Strip only that margin when adapting the target text. Preserve everything beyond it: target indentation, tabs, strings, comments, braces, punctuation, and keywords. Target indentation need not be a multiple of four.
A nonblank line dedented to the header's level ends the native block; blank lines remain inside it. A colon, quote, >, arrow, or apparent PlainLogic declaration inside the margin cannot switch the block back to PlainLogic. The block must contain nonblank target text. It cannot acquire a PlainLogic else/elif branch.
Native content is opaque to the canonical checker and the extension's PlainLogic analysis. Only its header, margin, and extent are checked. The extension can fold/highlight the protected region; it does not provide target-specific IntelliSense there. PlainLogic completion, symbol indexing, navigation, diagnostics, and rename do not inspect the literal body.
Native names do not automatically enter the PlainLogic symbol table. A later exact compute() call still needs a declared function/port even if native code defined that name. Use a contract or English step to make a cross-boundary relationship explicit. Check surrounding scope, values, effects, runtime feasibility, and target syntax during implementation. Native text does not override conflicting prose or hard logic silently.
| Need | Useful representation | Decide or verify |
|---|---|---|
| Coroutines, generators, tasks | Alias, prose, native | Scheduling, yielding/resumption, completion, cancellation, errors. |
| Callbacks, closures, methods, events | Prose, contracts, native declarations | Capture, receiver, lifetime, invocation count, reentrancy. |
| Cleanup, locks, transactions | Scoped alias/prose, existing port, native | Failure/early-exit cleanup, ownership, actual atomicity. |
| Multiple returns, destructuring, optional or variadic arguments | Prose, native, or an explicit record | Value order/count and meaningful defaults. |
| Pattern matching, custom iteration, comprehensions | Prose or native | Matching order, exhaustiveness, bounds, side effects. |
| Classes, interfaces, traits, generics, decorators, macros | Native declarations and refs | Target/version support and generated interfaces. |
| Pointers, mutable references, binary values, FFI | Symbolic types, contracts, native | Representation, aliasing, ownership/lifetimes, encoding, ABI. |
| Platform libraries, embedded languages | Target context, refs/ports, native | Real runtime capabilities and cross-language interfaces. |
An alias or native block can express a requirement that the platform cannot fulfill. Semantic validation must still detect the contradiction; structural acceptance alone does not settle it. Unclear context should lead to a focused question when consequential, not an automatic claim of impossibility.
Source baseline: docs/extensibility.md, examples/coroutine-canonical.plog, examples/native-target.plog, and test/checker_test.py.
PlainLogic 0.3 · Home · Implementation source · Validation limits
Learn
Install and use
Check and contribute