Metastatic.
View Source
Transform Cure source / Cure AST (M1) into MetaAST (M2).
This is the abstraction function α_Cure that lifts a Cure program to the meta-level. Unlike the Python / Ruby / Haskell adapters -- which marshal a foreign-language AST through a subprocess -- the Cure compiler already emits 3-tuples in the MetaAST shape because MetaAST was designed as Cure's primary AST. This module therefore does only two jobs:
- invoke the Cure compiler's lexer + parser (when it is linked in at runtime);
- normalise any lingering adapter-specific metadata so the result
round-trips cleanly through
Metastatic.AST.conforms?/1.
When the Cure.Compiler.Lexer / Cure.Compiler.Parser modules are
not available at runtime (e.g. Metastatic is used as a library in a
host project that does not depend on Cure) the from_source/2
entry point returns {:error, :cure_not_available}. The
normalize/1 entry point -- which accepts an already-parsed AST --
works unconditionally.
Entry Points
from_source/2-- parse Cure source into a canonical MetaAST.from_ast/1-- normalise an already-parsed Cure AST.normalize/1-- compact alias forfrom_ast/1.
v0.20.0 Notes
Cure v0.20.0 added :bin_segment and :comment node types plus the
segment-list payload for {:literal, [subtype: :bytes], ...}. All
three are part of the MetaAST M2.1 core layer, so this adapter does
not need to rewrite them -- it only walks the tree to ensure every
3-tuple has a keyword-list metadata in the second position (the
Cure parser emits [] when no metadata applies, which is already
canonical).
Summary
Types
The MetaAST produced by this adapter.
M1 metadata preserved for round-tripping (currently empty).
Opaque Cure source code.
Functions
Return true if the Cure compiler is available at runtime.
Ensure Cure compiler modules are loaded into the VM. Attempts dynamic discovery of Cure ebin directories or escript/executable if Cure is not already loaded.
Normalise an already-parsed Cure AST into canonical MetaAST.
Parse a Cure source fragment into a canonical MetaAST.
Types
@type meta_ast() :: Metastatic.AST.meta_ast()
The MetaAST produced by this adapter.
@type metadata() :: map()
M1 metadata preserved for round-tripping (currently empty).
@type source() :: String.t()
Opaque Cure source code.
Functions
@spec available?() :: boolean()
Return true if the Cure compiler is available at runtime.
@spec ensure_cure_compiler() :: :ok | {:error, :cure_not_available}
Ensure Cure compiler modules are loaded into the VM. Attempts dynamic discovery of Cure ebin directories or escript/executable if Cure is not already loaded.
Normalise an already-parsed Cure AST into canonical MetaAST.
The Cure parser already emits 3-tuples with keyword metadata, so this is effectively a structure-preserving pass that ensures:
- the metadata list is always a keyword list (even when empty);
:literalnodes withsubtype: :byteskeep either their raw binary payload or their:bin_segmentchildren (v0.20.0+);:commentnodes carry a:comment_kindmetadata key (defaults to:linewhen the parser did not set one);:paramlists stored in:function_def/:lambdametadata are recursively normalised.
Nodes unknown to MetaAST are passed through unchanged so analyzers
can use Metastatic.AST.conforms?/1 to surface them.
Parse a Cure source fragment into a canonical MetaAST.
Returns {:ok, meta_ast, metadata} on success, {:error, reason}
otherwise. metadata is a map reserved for future M1-specific
round-trip hints; it is currently %{language: :cure}.
When the Cure compiler's Cure.Compiler.Lexer /
Cure.Compiler.Parser modules are not linked in at runtime the
function returns {:error, :cure_not_available} instead of
attempting to parse. Call available?/0 to probe ahead of time.