This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== 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 and outputs ==== Some ports are **auto-bound** — when the functor is placed inside a compatible container, the port automatically connects to the relevant internal port of that container without needing an explicit connection. Auto-binding applies to both input and output ports. **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. Auto-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. Auto-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]]. Auto-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]]. Auto-binds to the ''regionId'' internal output of the enclosing [[Region]] container. * **''tableManager''** — on [[Merge Sub Tables]], [[Sub Table]], [[Table Manager Value]]. Auto-binds to the ''tableManager'' internal output of the enclosing [[Table Manager]] container. * **''currentIndividual''** — on [[Get Current Individual]]. Auto-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]]. Auto-binds to the ''condition'' internal input of the enclosing [[While]] or [[Do While]] container. * **''fitness''** — on [[Set Fitness]]. Auto-binds to the ''fitness'' internal input of the enclosing [[Genetic Algorithm Tool]] container. ===== Output Ports ===== A functor may produce one or more outputs. In EGO Script, outputs are bound to variables using the '':='' operator (see [[ego_script#functor_calls|Functor calls]]). 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''. See [[ego_script#nominal_syntax|Nominal syntax]] for how port names appear in functor calls. * **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 (see [[ego_script#constants|Constants]]): * ''.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 contained functors. 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 the contained functors BACK TO the container. These are set by dedicated functors placed inside the block (such as [[Set While Condition]] for the ''condition'' port of a loop). ==== Internal outputs by container ==== ^ Container ^ Internal output port ^ Type ^ Description ^ | [[Do While]] | ''step'' | NonNegativeIntegerValue | Current iteration index, starting at 0. | | [[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 0. | | [[While]] | ''step'' | NonNegativeIntegerValue | Current iteration index, starting at 0. | | [[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. | ==== Internal inputs by container ==== ^ 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. | See [[ego_script#internal_output_ports|Internal output ports]] and [[ego_script#internal_input_ports|Internal input ports]] for EGO Script 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.