Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
ego_script [2026/07/29 01:39]
hermann old revision restored (2026/07/26 14:19) 		ego_script [2026/08/31 15:12] (current)
hermann
Line 39: Line 39:
   * Variables written **before** the '':​=''​ operator are bound to its **output** ports.   * Variables written **before** the '':​=''​ operator are bound to its **output** ports.
  
-So in ''​x := LoadMap "​c:/​map.tif"'',​ the string ''"​c:/​map.tif"''​ is an input and ''​x''​ receives the output; in ''​SaveMap x "​c:/​map-copy.ers"'',​ both ''​x''​ and the filename are inputs, and the call produces no output ​that the script needs to keep.+So in ''​x := LoadMap "​c:/​map.tif"'',​ the string ''"​c:/​map.tif"''​ is an input and ''​x''​ receives the output; in ''​SaveMap x "​c:/​map-copy.ers"'',​ both ''​x''​ and the filename are inputs, and the call produces no output ​at all.
  
 A variable name must begin with an underscore or a letter, and may be followed by any combination of underscores,​ letters, and digits (''​[_a-zA-Z][_a-zA-Z0-9]*''​). Variable names are case-sensitive. A variable name must begin with an underscore or a letter, and may be followed by any combination of underscores,​ letters, and digits (''​[_a-zA-Z][_a-zA-Z0-9]*''​). Variable names are case-sensitive.
Line 59: Line 59:
 ===== Functor calls ===== ===== Functor calls =====
  
-A functor call binds **outputs** — the variables written before '':​=''​ — and consumes **inputs** — the values, variables, and constants written after the functor name. Every functor defines a fixed set of typed **[[ports]]** for its inputs and outputs:+A functor call binds **outputs** — the variables written before '':​=''​ — and consumes **inputs** — the values, variables, and constants written after the functor name. Every functor defines a fixed set of typed **[[#ports|ports]]** for its inputs and outputs:
  
 <​code>​ <​code>​
Line 68: Line 68:
  
 Inputs can be supplied in three interchangeable styles — [[#​positional_syntax|positional]],​ [[#​nominal_syntax|nominal]],​ and [[#​inline_syntax|inline]]. The styles may be mixed freely between calls, and even within a single call. Inputs can be supplied in three interchangeable styles — [[#​positional_syntax|positional]],​ [[#​nominal_syntax|nominal]],​ and [[#​inline_syntax|inline]]. The styles may be mixed freely between calls, and even within a single call.
 +
 +==== Ports ====
 +
 +A **port** is a typed connection point on a functor. Input ports receive data; output ports produce it. Every input port is either **required** or **optional**:​
 +
 +  * **Required** ports must always be supplied — either by connecting an output from another functor or by providing a constant value directly. A model cannot run if a required input is missing.
 +  * **Optional** ports have a **default value**, used automatically when the port is left unconnected and no constant is supplied. The default is specific to each port and is shown in the functor'​s own documentation. See [[#​positional_syntax|Positional syntax]] and [[#​nominal_syntax|Nominal syntax]] below for how optional inputs are omitted in a call.
 +
 +Some optional ports are also **nullable** — they explicitly accept the absence of a value as meaningful input. For a nullable port whose default is already ''​.none'',​ omitting the port and explicitly supplying ''​.none''​ both leave it without a value — but they aren't quite the same: omitting it falls back to the default, while writing ''​.none''​ signals that the absence of a value was chosen deliberately. See [[#​constants|Constants]] below for the ''​.none''​ and ''​.UNBOUND''​ dot constants, which are available to any input port.
 +
 +An **editable** port can receive a constant value typed directly into the GUI or written as a constant in a script call. Non-editable ports must instead be connected to an output from another functor; they cannot be supplied with a constant.
 +
 +A port's **type** determines what data it can carry — it accepts data of its exact type, or any type that converts to it automatically across a connection. See [[basic_data_flow#​functors_and_connections|Basic Data Flow]] for how that conversion works, and [[type_system|Type System]] for the full list of types and their conversions.
 +
 +For how a functor'​s inputs are supplied and its outputs are bound — including how to discard unwanted outputs — see [[#​positional_syntax|Positional syntax]], [[#​nominal_syntax|Nominal syntax]], and [[#​inline_syntax|Inline syntax]] below. For how port names differ between the GUI and the script itself, see [[#​alias_and_variable_name_conversion|Alias and variable name conversion]]. For the ports that connect containers to the functors nested inside them, and the ports that auto-bind to them, see [[#​internal_output_ports|Internal output ports]] and [[#​internal_input_ports|Internal input ports]] below.
  
 ==== Constants ==== ==== Constants ====
Line 73: Line 88:
 Constants supply a fixed value directly to an input port, without connecting a functor. Despite often looking similar in syntax, every constant is interpreted and validated according to the type of the port it is supplied to — a value that is valid for one port type may be rejected by another. They come in four forms. Constants supply a fixed value directly to an input port, without connecting a functor. Despite often looking similar in syntax, every constant is interpreted and validated according to the type of the port it is supplied to — a value that is valid for one port type may be rejected by another. They come in four forms.
  
-Automatic type conversion — such as a Real value becoming a Tuple, or a String becoming a Code value — only happens when a value is **connected** from one port to another: a variable reference, or a functor call inlined directly into an argument. It never applies to a constant written directly into a port. A constant is parsed by that port's own type-specific parser, which accepts only its own type's literal syntax and rejects anything else outright, even a literal that some other, compatible type would otherwise accept. See [[basic_data_flow|Basic Data Flow]] for this same distinction stated generally, independent of EGO Script or any other notation.+Automatic type conversion — such as a Real value becoming a Tuple, or a String becoming a Code value — only happens when a value is **connected** from one port to another: a variable reference, or a functor call inlined directly into an argument. It never applies to a constant written directly into a port. A constant is parsed by that port's own type-specific parser, which accepts only its own type's literal syntax and rejects anything else outright, even a literal that some other, compatible type would otherwise accept. See [[basic_data_flow|Basic Data Flow]] for this same distinction stated generally, independent of EGO Script or any other notation, and [[type_system|Type System]] for the complete catalog of types and how they convert into one another.
  
 **Numeric literals** — integer or real values written directly: ''​0'',​ ''​250'',​ ''​3.14''​. **Numeric literals** — integer or real values written directly: ''​0'',​ ''​250'',​ ''​3.14''​.
Line 89: Line 104:
 </​code>​ </​code>​
  
-For ''​String''​ ports that contain line breaks or double-quote characters, use the extended form ''​$"​DELIMITER(content)DELIMITER"''​. The content is everything between the opening ''​(''​ and the closing ''​)'',​ and the DELIMITER — any sequence of characters placed between the ''​%%"​%%''​ and the ''​('',​ including empty — makes the closing ''​)"''​ unambiguous. The delimiter must be identical on both sides. ​This extended form is **only accepted by ''​String''​ ports**:+[[code_type|Code]] ports also accept this basic ''"​text"''​ form, but interpret it differently from the types above: rather than validating the text itself, the content is decoded as base64 to produce the script — see the note below. 
 + 
 +For ''​String''​ ports that contain line breaks or double-quote characters, use the extended form ''​$"​DELIMITER(content)DELIMITER"''​. The content is everything between the opening ''​(''​ and the closing ''​)'',​ and the DELIMITER — any sequence of characters placed between the ''​%%"​%%''​ and the ''​('',​ including empty — makes the closing ''​)"''​ unambiguous. The delimiter must be identical on both sides. ​[[code_type|Code]] ports accept this same extended form directly too, using the content as the literal script text with no encoding involved — see [[code_type|Code Type]] for the full grammar. No other port type accepts it:
  
 <​code>​ <​code>​
Line 141: Line 158:
 Here ''​[ 2->1 0.05 ]''​ is a structured constant representing a transition matrix with a 5% rate from class 2 to class 1. Here ''​[ 2->1 0.05 ]''​ is a structured constant representing a transition matrix with a 5% rate from class 2 to class 1.
  
-> **Note:​** ​''​Code'' ​— the type used for expression inputs such as the Python code in [[Calculate Python Expression]] — is not a text constant. Code values are stored as base64 in the underlying script, making them impractical to write directly. When a port expects a ''​Code''​ value, supply a ''​String'' ​carrier functor containing ​the expression ​text; the automatic ​''​String → Code'' ​conversion handles ​the rest.+> **Note:​** ​[[code_type|Code]] — the type used for expression inputs such as the Python code in [[calculate_python_expression|Calculate Python Expression]] — has its own literal syntax, parsed ​directly ​rather than through ​a conversion, and accepts two forms: the extended ​''​$"​DELIMITER(content)DELIMITER"​'' ​form described above, taken directly as the script'​s ​text with no encoding involved; and the basic double-quoted ​''​"​text"​'' ​form, whose content is instead decoded as base64 to produce the script. See [[code_type|Code Type]] for the full grammar and examples of both forms.
  
 ==== Positional syntax ==== ==== Positional syntax ====
Line 157: Line 174:
  
 <​code>​ <​code>​
-landscape := LoadCategoricalMap "​c:/​landscape.ers"​ .no .no 0 0 .none .none;+landscape := LoadCategoricalMap "​c:/​landscape.ers"​ .none .default ​0 0 0 100 100;
 </​code>​ </​code>​
  
Line 169: Line 186:
 patchInfo _ _ := GetElevationGraphInfo elevationGraph .no .no; patchInfo _ _ := GetElevationGraphInfo elevationGraph .no .no;
 </​code>​ </​code>​
 +
 +A functor with no outputs at all is written as a bare call, with no assignment and no underscore — there is nothing to discard. [[Print]] and [[Save Map]] are the common cases.
  
 ==== Nominal syntax ==== ==== Nominal syntax ====
  
-In nominal syntax (also referred to as **named parameters** in the Dinamica EGO GUI options), inputs are enclosed in a pair of **single curly braces** ''​{ }''​ and bound **by port name**: each entry is written as ''​portName = value'',​ with entries separated by commas. Order does not matter, and any optional port may be omitted regardless of position. See [[ports]] for a full description of port properties including types, nullability,​ and default values. This is the clearest style for functors with many optional inputs:+In nominal syntax (also referred to as **named parameters** in the Dinamica EGO GUI options), inputs are enclosed in a pair of **single curly braces** ''​{ }''​ and bound **by port name**: each entry is written as ''​portName = value'',​ with entries separated by commas. Order does not matter, and any optional port may be omitted regardless of position. See [[#ports|Ports]] above for a full description of port properties including types, nullability,​ and default values. This is the clearest style for functors with many optional inputs:
  
 <​code>​ <​code>​
Line 204: Line 223:
 </​code>​ </​code>​
  
-Any output can be replaced with ''​_'' ​to discard ​it when only some outputs are needed.+When only some of a functor'​s outputs are wanted, the rest can simply be left out of the block entirely — nominal syntax binds by name, so there'​s no position to hold open the way [[#​positional_syntax|positional syntax]] requires. An unwanted ​output can also be bound to ''​_'' ​instead of omitted; this changes nothing about execution, ​it only makes explicit, at the call site, that the output was considered and deliberately discarded rather than overlooked.
  
 So inputs read ''​portName = value''​ while outputs read ''​variable = portName''​. The two directions are summarized below: So inputs read ''​portName = value''​ while outputs read ''​variable = portName''​. The two directions are summarized below:
Line 294: Line 313:
  
 <​code>​ <​code>​
-_ := Print "​Beginning execution"​ "​Finished execution"​ {{+Print "​Beginning execution"​ "​Finished execution"​ {{
     // Perform some complicated computation that produces a numeric result...     // Perform some complicated computation that produces a numeric result...
     result := ...;     result := ...;
Line 303: Line 322:
  
 <​code>​ <​code>​
-_ := Print "​Beginning execution"​ .none {{+Print "​Beginning execution"​ .none {{
     // Perform some complicated computation that produces a numeric result...     // Perform some complicated computation that produces a numeric result...
     result := ...;     result := ...;
Line 310: Line 329:
         NumberValue result 1;         NumberValue result 1;
     }};     }};
-    ​_ := Print message .none {{ }};+    Print message .none {{ }};
 }}; }};
 </​code>​ </​code>​
Line 323: Line 342:
   * ''​sequenceOutput''​ — connecting this output to another container'​s ''​sequenceInput''​ forces this container to complete before the other one starts.   * ''​sequenceOutput''​ — connecting this output to another container'​s ''​sequenceInput''​ forces this container to complete before the other one starts.
  
-These ports carry no data of their own; their only purpose is to impose execution ordering. Because any data type can be connected to a ''​sequenceInput''​ port, the output of one container can feed directly into the next container'​s sequencing slot:+These ports carry no data of their own; their only purpose is to impose execution ordering. Because any data type can be connected to a ''​sequenceInput''​ port — every type in the system converts to it automatically, the same conversion [[type_system#​sequencing|Type System]] catalogs against every type it applies to — the output of one container can feed directly into the next container'​s sequencing slot:
  
 <​code>​ <​code>​
Line 345: Line 364:
 <​code>​ <​code>​
 ForEachCategory categorization {{ ForEachCategory categorization {{
-    ​currentCategory = step;             // read the internal output port `step`+    // read the internal output port `step` 
 +    currentCategory = step;
     categoryId := Step currentCategory;​     categoryId := Step currentCategory;​
     // ...     // ...
Line 352: Line 372:
  
 Here ''​step''​ is the port the loop provides, and ''​currentCategory''​ is the variable that receives it for use inside the block. Here ''​step''​ is the port the loop provides, and ''​currentCategory''​ is the variable that receives it for use inside the block.
 +
 +The binding is optional in this particular case. [[Step]]'​s own input is auto-bound to the enclosing container'​s ''​step''​ port — see [[#​auto-bound_ports|Auto-bound ports]] below — so ''​categoryId := Step;''​ on its own would have worked. It is written out here to make the port visible; internal outputs with no such auto-bound consumer, like the one in the next example, always have to be read explicitly.
  
 ''​RegionManager''​ provides another example. It creates a region context and exposes it to the functors inside its block through an internal output port: ''​RegionManager''​ provides another example. It creates a region context and exposes it to the functors inside its block through an internal output port:
Line 357: Line 379:
 <​code>​ <​code>​
 RegionManager regionMap 0 {{ RegionManager regionMap 0 {{
-    ​manager = regionManager; ​           ​// read the internal output port `regionManager`+    // read the internal output port `regionManager` 
 +    manager = regionManager;​
     allRegions := GetAllRegionsInfo manager;     allRegions := GetAllRegionsInfo manager;
 }}; }};
Line 368: Line 391:
 An **internal input port** carries a value the other way: from the functors inside the block back to the container. The contained functors produce the value; the container consumes it. The condition that decides whether a loop repeats is the clearest example. An **internal input port** carries a value the other way: from the functors inside the block back to the container. The contained functors produce the value; the container consumes it. The condition that decides whether a loop repeats is the clearest example.
  
-A ''​While''​ or ''​DoWhile''​ loop has an internal input port for its repeat condition. It is fed by placing a [[Set While Condition]] functor inside the loop body — the ''​condition''​ output port of ''​SetWhileCondition''​ is **auto-bound** to the loop's ''​condition''​ internal input, so no explicit connection is needed:+A ''​While''​ or ''​DoWhile''​ loop has an internal input port for its repeat condition. It is fed by placing a [[Set While Condition]] functor inside the loop body — the ''​condition''​ output port of ''​SetWhileCondition''​ is **auto-bound** ​(see [[#​auto-bound_ports|Auto-bound ports]] below) ​to the loop's ''​condition''​ internal input, so no explicit connection is needed:
  
 <​code>​ <​code>​
 _ := DoWhile .none {{ _ := DoWhile .none {{
     // ... contained functors compute `keepGoing`,​ a non-zero value to continue ...     // ... contained functors compute `keepGoing`,​ a non-zero value to continue ...
-    ​_ := SetWhileCondition keepGoing; ​  // condition output auto-binds to the loop+    // condition output auto-binds to the loop 
 +    _ := SetWhileCondition keepGoing;
 }}; }};
 </​code>​ </​code>​
Line 380: Line 404:
  
 A container may also expose a sequencing-only internal port (carrying no data) used to force one container to finish before another begins — see [[#​sequence_ports|Sequence ports]]. A container may also expose a sequencing-only internal port (carrying no data) used to force one container to finish before another begins — see [[#​sequence_ports|Sequence ports]].
 +
 +==== Auto-bound ports ====
 +
 +Some ports are **auto-bound** — when a functor is placed inside a compatible container, the port connects automatically to that container'​s matching internal port, with no explicit binding needed. This is the general mechanism behind two examples already seen above: [[Step]]'​s input auto-binds to a loop's ''​step''​ internal output, and [[Set While Condition]]'​s output auto-binds to a loop's ''​condition''​ internal input.
 +
 +**Auto-bound input ports** connect automatically to an internal output of the enclosing container:
 +
 +  * ''​step''​ — on [[Step]], all ''​Load*''​ and ''​Save*''​ file I/O functors, and all ''​Select*''​ functors. Binds to the ''​step''​ internal output of the enclosing loop container ([[Repeat]],​ [[For]], [[For Each]], [[For Each Category]], [[For Each Region]], [[While]], [[Do While]]).
 +  * ''​workdir''​ — on all ''​Load*''​ and ''​Save*''​ file I/O functors. Binds to the ''​workdir''​ internal output of the enclosing [[Workdir]] container.
 +  * ''​regionManager''​ — on [[Get All Regions Info]], [[Get Region Info]], [[Region]], [[Region Manager Value]], [[Regional Map]], [[Regional Categorical Map]], [[Regionalize Map]], [[Regionalize Categorical Map]], [[Merge Regional Maps]], [[Merge Regional Categorical Maps]]. Binds to the ''​regionManager''​ internal output of the enclosing [[Region Manager]], [[Region]], or [[For Each Region]] container.
 +  * ''​regionId''​ — on [[Get Region Info]], [[Region]], [[Regional Map]], [[Regional Categorical Map]], [[Regionalize Map]], [[Regionalize Categorical Map]]. Binds to the ''​regionId''​ internal output of the enclosing [[Region]] container.
 +  * ''​tableManager''​ — on [[Merge Sub Tables]], [[Sub Table]], [[Table Manager Value]]. Binds to the ''​tableManager''​ internal output of the enclosing [[Table Manager]] container.
 +  * ''​currentIndividual''​ — on [[Get Current Individual]]. Binds to the ''​currentIndividual''​ internal output of the enclosing [[Genetic Algorithm Tool]] container.
 +
 +**Auto-bound output ports** connect automatically to an internal input of the enclosing container:
 +
 +  * ''​condition''​ — on [[Set While Condition]]. Binds to the ''​condition''​ internal input of the enclosing [[While]] or [[Do While]] container.
 +  * ''​fitness''​ — on [[Set Fitness]]. Binds to the ''​fitness''​ internal input of the enclosing [[Genetic Algorithm Tool]] container.
 +
 +The full set of internal ports exposed by each container:
 +
 +^ Container ^ Internal output port ^ Type ^ Description ^
 +| [[Do While]] | ''​step''​ | NonNegativeIntegerValue | Current iteration index, starting at 1. |
 +| [[For]] | ''​step''​ | RealValue | Current value in the numeric range being iterated. |
 +| [[For Each]] | ''​step''​ | RealValue | Current row value from the table being iterated. |
 +| [[For Each Category]] | ''​step''​ | IntegerValue | Current category code from the categorical map. |
 +| [[For Each Region]] | ''​step''​ | IntegerValue | Current region identifier. |
 +| [[For Each Region]] | ''​regionManager''​ | RegionManager | The region manager for the current region. |
 +| [[Repeat]] | ''​step''​ | NonNegativeIntegerValue | Current iteration index, starting at 1. |
 +| [[While]] | ''​step''​ | NonNegativeIntegerValue | Current iteration index, starting at 1. |
 +| [[Region Manager]] | ''​regionManager''​ | RegionManager | The region manager for the current region context. |
 +| [[Region]] | ''​regionManager''​ | RegionManager | The region manager. |
 +| [[Region]] | ''​regionId''​ | IntegerValue | The current region identifier. |
 +| [[Workdir]] | ''​workdir''​ | Workdir | The working directory defined by the container. |
 +| [[Table Manager]] | ''​tableManager''​ | TableManager | The table manager defined by the container. |
 +| [[Genetic Algorithm Tool]] | ''​currentIndividual''​ | LookupTableGroup | The current individual in the genetic algorithm population. |
 +
 +^ Container ^ Internal input port ^ Type ^ Set by ^
 +| [[While]] | ''​condition''​ | BooleanValue | [[Set While Condition]] — the ''​condition''​ output port is auto-bound to this internal input. |
 +| [[Do While]] | ''​condition''​ | BooleanValue | [[Set While Condition]] — the ''​condition''​ output port is auto-bound to this internal input. |
 +| [[Genetic Algorithm Tool]] | ''​fitness''​ | RealValue | [[Set Fitness]] — the ''​fitness''​ output port is auto-bound to this internal input. |
  
 ==== Carrying and selecting values across iterations ==== ==== Carrying and selecting values across iterations ====
Line 413: Line 478:
 ==== Error-handling pattern ==== ==== Error-handling pattern ====
  
-The error-handling containers are most useful when combined ​with a [[#​carrying_and_selecting_values_across_iterations|junction]] ​outside ​the block. The sentinel and the risky functor ​inside the container ​have no data dependency on each other, ​so they execute independently. The pattern works as follows:+The error-handling containers are most useful when paired ​with something outside the block that reacts to the outcome — a [[#​carrying_and_selecting_values_across_iterations|junction]] ​when the goal is a fallback value, [[If Then]]/[[If Not Then]] when the branches need to do different things (see below). The functors ​inside the container ​are typically independent of each other, ​with no data dependency forcing a particular order; what changes between the two containers is what happens to their results if one of them fails partway through. The pattern works as follows:
  
-  - If the risky functor raises an error, [[Skip All On Error]] captures it and discards **all** results produced by functors inside the container — including the sentinel, ​even though it completed successfully on its own. +  - If any functor ​inside ​raises an error, [[Skip All On Error]] captures it and discards **all** results produced by functors inside the container — even results that had already ​completed successfully on their own. 
-  - Outside the container, a **junction** tests whether ​anything ​propagated out. If the sentinel ​was discarded (error case), ​the container produced nothing and the junction falls back to its default ​value. If no error occurred, the sentinel ​propagates normally and the junction forwards it.+  - Outside the container, a **junction** tests whether ​a given value propagated out. If it was discarded (the error case), the junction falls back to its default. If no error occurred, the value propagates normally and the junction forwards it.
  
-This example ​tests whether ​a map file can be loaded successfully:+This example ​loads a categorical ​map together with a lookup table of transition weights that only makes sense paired with that specific map; if either ​file is missing, both should fall back to a matched pair of defaults, rather than risking a real map paired with mismatched default weights, or the reverse:
  
 <​code>​ <​code>​
 _ := SkipAllOnError .yes {{ _ := SkipAllOnError .yes {{
-    // The sentinel has no dependency on LoadMap — both execute independently. +    // loadedMap and loadedWeights need to succeed together or not at all -- 
-    // If LoadMap raises an error, SkipAllOnError discards ​all results inside, +    // if either file is missing, SkipAllOnError discards ​both, even 
-    // including this sentinel. +    // whichever one loaded successfully,​ so the junctions below always 
-    ​booleanValue0 ​:= BooleanValue ​.yes;+    // fall back to a matched, consistent pair of defaults. 
 +    ​loadedMap ​:= LoadMap mapFilename;​ 
 +    loadedWeights := LoadLookupTable weightsFilename;​ 
 +}}; 
 + 
 +// If either load failed, both loadedMap and loadedWeights were discarded,​ 
 +// and both junctions fall back to their defaults. If both succeeded, each 
 +// junction forwards the real value. 
 +mapOrDefault := MapJunction loadedMap defaultMap; 
 +weightsOrDefault := LookupTableJunction loadedWeights defaultWeights;​ 
 +</​code>​ 
 + 
 +When only a pass/fail signal is needed — not an actual fallback value — a junction is unnecessary:​ [[Skip All On Error]] already reports success or failure directly through its own ''​executionCompletedSuccessfully''​ output, with no sentinel or junction required: 
 + 
 +<​code>​ 
 +result := SkipAllOnError .yes {{
     _ := LoadMap inputMapFilename;​     _ := LoadMap inputMapFilename;​
 }}; }};
-// If the sentinel was discarded (error), the junction falls back to false (0). 
-// If no error occurred, the sentinel propagates and the junction returns true. 
-result := ValueJunction booleanValue0 0; 
 </​code>​ </​code>​
  
-[[Skip On Error]] behaves differently:​ instead of discarding all results, it preserves the outputs of any functors that had already completed when the error was raised. ​In the pattern ​above this means the sentinel ​would always propagate ​— making ​[[Skip On Error]] ​suitable for cases where partial results ​from a failed block are still useful, not for a simple success/failure test.+''​result''​ is that boolean directly. The paired-fallback pattern above earns its extra complexity only when a real value, not just a flag, needs a fallback on failure. 
 + 
 +[[Skip On Error]] behaves differently:​ instead of discarding all results, it preserves the outputs of any functors that had already completed when the error was raised. ​Substituting it into the paired-loading example ​above would be a mistake: since ''​loadedMap''​ and ''​loadedWeights''​ have no data dependency on each other — see [[#​functors_variables_and_binding|Functors,​ variables, and binding]] for that execution-order rule stated generally — nothing guarantees which of the two, if either, has already completed by the time the other'​s error is raised. The outcome ​would be a race: a real map could end up paired with default weights, or the reverse, unpredictably from run to run. [[Skip All On Error]] sidesteps that race entirely ​— it discards both regardless of which one failed or how far the other had gotten — which is exactly what "​succeed together or not at all" requires. ​[[Skip On Error]] ​instead earns its place when partial results are genuinely fine to keep on their own — see below. 
 + 
 +Whatever [[Skip On Error]] preserves is what each branch has to work with. If the branches only need to pick between two values — the case in the [[manipulating_tables_and_lookup_tables#​printing_a_table_with_a_generic_format|generic printer]] above — a junction is the simplest tool. But when the branches need to carry out different logic rather than just hand a value onward, [[If Then]]/[[If Not Then]] can test [[Skip On Error]]'​s own ''​executionCompletedSuccessfully''​ output directly — no separate sentinel needed, unlike the paired-loading [[Skip All On Error]] pattern above. This example attempts to load an optional mask map; if it loads, the matching branch has the mask itself to work with, and if it's missing or fails to load, the other branch proceeds without one: 
 + 
 +<​code>​ 
 +maskLoaded := SkipOnError .yes {{ 
 +    mask := LoadMap maskFilename;​ 
 +}}; 
 + 
 +// maskLoaded is SkipOnError'​s own boolean output; mask itself -- preserved 
 +// on success -- is what the matching branch below actually needs. 
 +_ := IfThen maskLoaded {{ 
 +    Print "Mask loaded; masking enabled"​ .none {{ }}; 
 +}}; 
 + 
 +_ := IfNotThen maskLoaded {{ 
 +    Print "​Mask ​not found; continuing without one" .none {{ }}; 
 +}}; 
 +</​code>​ 
 + 
 +Contrast this with picking ​a value out of two mutually exclusive attempts, as in [[manipulating_tables_and_lookup_tables#​printing_a_table_with_a_generic_format|Manipulating Tables and Lookup Tables]]: when both branches would just hand the same kind of value onward, a junction is the simpler tool; ''​IfThen''​/''​IfNotThen''​ earns its place when the branches need to do something different.
  
 ---- ----
Line 1017: Line 1116:
 | **Use abbreviated syntax for Calculate family functors** | Whether the ''​Calculate''​ family is written using the shorthand symbol (''#'',​ ''##'',​ ''​%'',​ etc.) or the full functor name. See the [[#​calculator_functor_shorthand|Calculator functor shorthand]] section for details. | | **Use abbreviated syntax for Calculate family functors** | Whether the ''​Calculate''​ family is written using the shorthand symbol (''#'',​ ''##'',​ ''​%'',​ etc.) or the full functor name. See the [[#​calculator_functor_shorthand|Calculator functor shorthand]] section for details. |
 | **Preferred number of columns before wrapping comments** | The line width at which the generator wraps long comment text. | | **Preferred number of columns before wrapping comments** | The line width at which the generator wraps long comment text. |
- 
-