Skip to content

Collections.md

Latest commit

 

History

History
679 lines (516 loc) · 17.9 KB

Collections.md

File metadata and controls

679 lines (516 loc) · 17.9 KB

🐸 FROG Collections Library Specification

Definition of the standard frog.collections library for FROG v0.1
FROG — Free Open Graphical Language

Contents

1. Overview

This document defines the standard frog.collections library for FROG v0.1.

The frog.collections library provides a first standardized set of collection-oriented primitives for executable FROG diagrams.

For FROG v0.1, this library is intentionally limited to array-oriented primitives. It standardizes a compact but useful set of operations for:

  • array size inspection,
  • emptiness checks,
  • element access,
  • element replacement,
  • array growth,
  • array concatenation,
  • subarray extraction.

This library extends the practical expressiveness of FROG without expanding the minimal mandatory kernel defined by frog.core.

2. Goals

  • Practicality — provide a useful first standard collection library for everyday graphical programming.
  • Minimality — keep the v0.1 surface small enough to remain durable and easy to implement.
  • Clarity — assign every primitive a clear, stable role and a stable port model.
  • Portability — ensure collection primitives have portable source-level meaning across conforming implementations.
  • Extensibility — leave room for future collection families beyond arrays without forcing them into v0.1.

3. Relation with Other Specifications

This document complements the following specifications:

  • Expression/Diagram.md — defines how library primitives are serialized as executable diagram nodes.
  • Expression/Type.md — defines built-in types, including array types, and the compatibility and coercion rules that apply to primitive ports.
  • Expression/Control structures.md — defines standardized language structures, which remain distinct from ordinary primitive functions.
  • Libraries/Core.md — defines the minimal built-in primitive kernel on top of which higher-level library families may be added.

This document defines the standardized collection primitive catalog. It does not redefine the graph model, the type system, or the standardized control-structure model.

4. Role of frog.collections

The frog.collections library provides standardized collection-oriented executable primitives for FROG diagrams.

In language terms, these are library-level primitive functions. In the serialized diagram representation defined by Expression/Diagram.md, calls to these functions are represented as nodes of kind primitive.

For example:

  • frog.collections.length is a standardized collection primitive,
  • in a diagram, that function call appears as a primitive node with type = "frog.collections.length".

This library is a standard sibling of frog.core, not an expansion of it.

5. Naming and Namespace

FROG uses the following general namespace pattern for standardized primitives: 

frog.<library>.<primitive>

For this document:

  • frog identifies the language namespace,
  • collections identifies the standard collections library,
  • the final segment identifies the primitive name.

Examples: 

frog.collections.length
frog.collections.get
frog.collections.set
frog.collections.append
frog.collections.concat
frog.collections.slice

Primitive names in frog.collections SHOULD use lowercase snake_case where multiple words are needed.

6. Scope for v0.1

FROG v0.1 standardizes the following initial collection primitives:

  • structural query functions,
  • element access and update functions,
  • array growth and combination functions,
  • subarray extraction.

In v0.1, these functions apply only to standardized FROG array types.

This document does not yet standardize:

  • maps,
  • sets,
  • dictionaries,
  • heterogeneous tuples or records,
  • higher-order collection functions such as map, filter, or reduce,
  • sorting, searching, or advanced reshaping catalogs.

7. Collection Model for v0.1

For FROG v0.1, the only standardized collection family is the built-in array family defined by Expression/Type.md.

Accordingly:

  • array<T> is a valid collection type with dynamic size,
  • array<T, N> is a valid collection type with fixed size,
  • nested arrays are valid when the element type is itself an array type.

All collection primitives in this document operate on homogeneous arrays.

When a primitive in this document returns an array whose size depends on runtime values rather than a compile-time fixed type expression, the output type is the dynamic array form array<T>.

8. Typing Model

All frog.collections primitives are typed according to Expression/Type.md.

Unless stated otherwise:

  • array inputs MUST have valid FROG array types,
  • element ports MUST be type-compatible with the array element type,
  • index and length ports in this document MUST use type u64,
  • all implicit coercions MUST follow the standard FROG coercion rules,
  • all functions in this document are stateless and side-effect-free.

For primitives that require an index to be in range, the index validity condition is part of the primitive contract. If an implementation can prove a violation statically, it MUST reject the graph as invalid. If the violation is only detectable at execution time, the active execution profile MUST define the corresponding runtime failure behavior.

9. Structural Query Functions

9.1 frog.collections.length

Returns the number of elements in an array.

  • input port: array
  • output port: length

Rules:

  • the input MUST have type array<T> or array<T, N>,
  • the output type is u64.

For a fixed-size input array, the returned value is the fixed declared size. For a dynamic array, the returned value is the runtime element count.

9.2 frog.collections.is_empty

Returns whether an array contains zero elements.

  • input port: array
  • output port: result

Rules:

  • the input MUST have type array<T> or array<T, N>,
  • the output type is bool.

10. Element Access and Update Functions

10.1 frog.collections.get

Returns the element stored at a given index.

  • input ports: array, index
  • output port: value

Rules:

  • array MUST have type array<T> or array<T, N>,
  • index MUST have type u64,
  • value has type T,
  • the index MUST satisfy index < length(array).

10.2 frog.collections.set

Returns an array equal to the input array except at one index, where the value is replaced.

  • input ports: array, index, value
  • output port: result

Rules:

  • array MUST have type array<T> or array<T, N>,
  • index MUST have type u64,
  • value MUST be type-compatible with T,
  • the index MUST satisfy index < length(array).

Output typing:

  • if the input type is array<T>, the output type is array<T>,
  • if the input type is array<T, N>, the output type is array<T, N>.

11. Array Growth and Combination Functions

11.1 frog.collections.append

Returns an array formed by appending one element to the end of the input array.

  • input ports: array, value
  • output port: result

Rules:

  • array MUST have type array<T> or array<T, N>,
  • value MUST be type-compatible with T.

Output typing:

  • the output type is array<T>.

This output is dynamic in v0.1 even if the input array has fixed size, because the result length differs from the input length.

11.2 frog.collections.concat

Returns an array formed by concatenating two arrays of compatible element type.

  • input ports: a, b
  • output port: result

Rules:

  • a MUST have type array<T1> or array<T1, N1>,
  • b MUST have type array<T2> or array<T2, N2>,
  • T1 and T2 MUST be identical or implicitly coercible to a common element type T.

Output typing:

  • the output type is array<T>.

12. Subarray Functions

12.1 frog.collections.slice

Returns a contiguous subarray starting at a given index and spanning a given number of elements.

  • input ports: array, start, length
  • output port: result

Rules:

  • array MUST have type array<T> or array<T, N>,
  • start MUST have type u64,
  • length MUST have type u64,
  • the requested slice MUST satisfy start + length <= length(array).

Output typing:

  • the output type is array<T>.

The result type is dynamic in v0.1 because the slice length is provided as a runtime value.

13. Diagram Representation

Calls to frog.collections primitives are serialized as primitive nodes in the diagram.

Example: 

{
  "id": "len_1",
  "kind": "primitive",
  "type": "frog.collections.length"
}

Another example: 

{
  "id": "get_1",
  "kind": "primitive",
  "type": "frog.collections.get"
}

The exact port existence, direction, and typing of these nodes are resolved from this specification together with the type system and the graph rules.

14. Validation Rules

Implementations MUST enforce the following rules:

  • every frog.collections primitive reference MUST identify a valid standardized primitive name defined in this document,
  • all required input ports for the referenced primitive MUST exist,
  • all produced output ports MUST match the primitive definition,
  • all array inputs MUST use valid FROG array types,
  • all implicit coercions MUST follow Expression/Type.md.

For frog.collections.get and frog.collections.set specifically:

  • the index input MUST have type u64,
  • the referenced element position MUST be in range.

For frog.collections.slice specifically:

  • start and length MUST both have type u64,
  • the requested slice interval MUST be valid for the input array.

For frog.collections.append, frog.collections.concat, and frog.collections.set:

  • value inputs MUST be type-compatible with the resolved array element type.

15. Examples

15.1 Array length

{
  "id": "len_1",
  "kind": "primitive",
  "type": "frog.collections.length"
}

Conceptual ports: 

array → length

15.2 Element access

{
  "id": "get_1",
  "kind": "primitive",
  "type": "frog.collections.get"
}

Conceptual ports: 

array, index → value

15.3 Element replacement

{
  "id": "set_1",
  "kind": "primitive",
  "type": "frog.collections.set"
}

Conceptual ports: 

array, index, value → result

15.4 Array append

{
  "id": "append_1",
  "kind": "primitive",
  "type": "frog.collections.append"
}

Conceptual ports: 

array, value → result

15.5 Array slice

{
  "id": "slice_1",
  "kind": "primitive",
  "type": "frog.collections.slice"
}

Conceptual ports: 

array, start, length → result

15.6 Concatenate two arrays

{
  "diagram": {
    "nodes": [
      { "id": "input_a", "kind": "interface_input", "interface_port": "a" },
      { "id": "input_b", "kind": "interface_input", "interface_port": "b" },
      { "id": "concat_1", "kind": "primitive", "type": "frog.collections.concat" },
      { "id": "output_result", "kind": "interface_output", "interface_port": "result" }
    ],
    "edges": [
      { "id": "e1", "from": { "node": "input_a", "port": "value" }, "to": { "node": "concat_1", "port": "a" } },
      { "id": "e2", "from": { "node": "input_b", "port": "value" }, "to": { "node": "concat_1", "port": "b" } },
      { "id": "e3", "from": { "node": "concat_1", "port": "result" }, "to": { "node": "output_result", "port": "value" } }
    ]
  }
}

16. Out of Scope for v0.1

The following are outside the strict scope of frog.collections in v0.1:

  • maps, sets, dictionaries, and key-value collection families,
  • heterogeneous tuple, record, or cluster collection primitives,
  • sorting and searching catalogs,
  • insert-at and remove-at catalogs,
  • reshape, transpose, or multidimensional array algebra catalogs beyond what is expressible through ordinary nested arrays,
  • higher-order collection primitives such as map, filter, reduce, or fold,
  • streaming and lazy collection models,
  • text-oriented collection semantics, which belong in a dedicated text library.

17. Summary

The frog.collections library defines the first standardized collection-oriented primitive set for FROG v0.1.

It provides:

  • array size inspection,
  • emptiness checks,
  • element access,
  • element replacement,
  • array append,
  • array concatenation,
  • subarray extraction.

This library is intentionally compact. Its purpose is to provide a durable and practical first collection vocabulary aligned with the current FROG v0.1 type system while leaving room for richer collection families in later revisions.

End of FROG Collections Library Specification