Skip to content

Aliases and Native Blocks

Sceleratis edited this page Oct 20, 2026 · 1 revision

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.

Behavior aliases

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.

A canonical alias document

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.

Inclusive counted loops

The statement excerpt for i = first to last: means:

  1. Evaluate first, then last, once each before the loop.
  2. Count upward by one and include both endpoints.
  3. Execute no iterations if first is greater than last.
  4. 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.

Native blocks

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.

Margin and extent

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.

Protection and limits

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.

Choosing a surface for target features

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.

Clone this wiki locally