Differences

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

--- ports [2026/07/09 05:10]
hermann created
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Ports ======
-A **port** is a typed connection point on a functor. Input ports receive data; output ports produce it. Every functor defines a fixed set of ports — their names, types, and whether they are required or optional — and data flows between functors by connecting an output port of one to an input port of another.
-===== Input Ports =====
-==== Required and optional inputs ====
-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** that is used automatically when the port is not connected and no constant is provided. The default is specific to each port and is shown in the functor's documentation.
-==== Nullable inputs ====
-Some optional ports are also **nullable** — they explicitly accept the absence of a value as meaningful input. A nullable port whose default is already ''none'' can be left without a value intentionally by supplying the constant ''.none''. This is distinct from simply omitting the port (which uses the default) because it explicitly signals that no value is being provided.
-==== Editable inputs ====
-An **editable** port can receive a constant value typed directly into the GUI or written as a constant in an EGO Script call. Non-editable ports must be connected to an output from another functor; they cannot be supplied with a constant.
-==== Auto-bound inputs ====
-Some input ports inside a container functor can be **auto-bound** — they automatically link to a matching internal output produced by the container itself (for example, the current iteration value in a loop). Auto-bound ports do not need to be explicitly connected; the container wires them automatically when the model is executed.
-===== Output Ports =====
-A functor may produce one or more outputs. In EGO Script, outputs are bound to variables using the '':='' operator. When a functor produces multiple outputs and only some are needed, the underscore ''_'' discards unwanted ones:
-<code>
-// Bind all outputs
-{ areaTable = areas } := CalcAreas { source = landscape };
-// Bind only the first output; discard the rest
-result := SomeFunctor input1 input2;
-// Discard first output; keep second
-_ secondOutput := SomeFunctor input1 input2;
-</code>
-===== Port Naming =====
-Port names follow different conventions depending on context:
-  * **In EGO Script**, port names are written in camelCase with a lowercase first letter: ''cellType'', ''resultIsSparse'', ''nullValue''.
-  * **In the GUI**, the same ports are displayed with spaces between words and all words capitalised: "Cell Type", "Result Is Sparse", "Null Value".
-The conversion between the two follows the same rules as [[ego_script#alias_and_variable_name_conversion|alias and variable name conversion]] in EGO Script.
-===== Port Types =====
-Every port has a **type** that determines what data it can carry. A port accepts data of its exact type or any type that can be automatically converted to it. See the [[type_system|type system]] documentation for the full list of types and their conversions.
-Two special constants are available for any input port regardless of type:
-  * ''.UNBOUND'' — the port is not connected, or its connection is deliberately being ignored. Used especially when copying a fragment of a model to a text editor, where some connections may not be part of the selection.
-  * ''.none'' — the port is intentionally left without a value. Valid **only for optional nullable input ports**.
-===== Sequence Ports =====
-Most container functors expose two special sequencing ports:
-  * ''sequenceInput'' — connecting a value here ensures the functor that produced that value completes before this container starts. Accepts any data type.
-  * ''sequenceOutput'' — pass this to another functor's ''sequenceInput'' to force this container to complete first.
-These ports carry no data; their only purpose is to impose execution ordering. See [[ego_script#sequence_ports|Sequence ports]] in the EGO Script documentation for details and examples.
-===== Internal Ports (Container Functors) =====
-Container functors communicate with the functors inside them through **internal ports**:
-  * **Internal output ports** carry values from the container into the block — for example, the current iteration value in a loop or a region object from a region manager. In EGO Script these are bound as the first declarations inside the container block using the ''{ variable = portName }'' form.
-  * **Internal input ports** carry values from inside the block back out of the container — for example, the accumulated result of a loop. These are bound at the end of the block.
-See [[ego_script#internal_output_ports|Internal output ports]] and [[ego_script#internal_input_ports|Internal input ports]] for syntax details and examples.
-===== Hook Ports (Calculator Functors) =====
-The five [[calculate_functors|calculator functors]] ([[Calculate Map]], [[Calculate Categorical Map]], [[Calculate Value]], [[Calculate Lookup Table Values]], [[Calculate Lookup Table Keys And Values]]) connect their data inputs through **hook** functors rather than directly:
-  * [[Number Map]] ports — connect raster maps; referenced in expressions as ''i1'', ''i2'', …
-  * [[Number Table]] ports — connect tables and lookup tables; referenced as ''t1'', ''t2'', …
-  * [[Number Value]] ports — connect scalar values; referenced as ''v1'', ''v2'', …
-In the abbreviated (shorthand) syntax, hook ports are implicit — operands are referenced directly by variable name using a type sigil (''#'' for maps, ''%'' for tables, ''$'' for values). See [[ego_script#calculator_functor_shorthand|Calculator functor shorthand]] for details.