Skip to content

Table.md

Latest commit

 

History

History
319 lines (263 loc) · 10.2 KB

Table.md

File metadata and controls

319 lines (263 loc) · 10.2 KB

FROG Table Library Specification

Definition of the standard frog.table value and primitive surface for FROG v0.1
FROG - Free Open Graphical Language

Contents

1. Overview

frog.table defines a portable tabular value contract and the first value-only primitives for constructing, inspecting, extracting, updating, and formatting table data. It is a data library, not a table-widget helper library and not a database or spreadsheet engine.

Table widgets may display or edit frog.table values, but the computation that builds or transforms those values remains in ordinary diagram nodes.

2. Boundary

frog.table
  owns portable rectangular table values and pure table transforms

table widgets
  display/edit table values and expose widget interaction

frog.text
  owns general text operations

profiles
  own database, spreadsheet, CSV file I/O, and external data-frame integration

The v0.1 table surface is intentionally flat and rectangular. It does not define hierarchical tables, pivot tables, formula cells, database result-set handles, or host-native grid virtualization.

3. Value Shape

The minimal table value shape is: 

{
  "kind": "frog.table",
  "columns": array<string>,
  "rows": array<array<string>>
}

Rules:

  • columns contains display headers and stable column order.
  • rows contains row-major cell text.
  • Every row length MUST equal column_count.
  • Column count MAY be zero only when row count is also zero.

The v0.1 table value is text-cell oriented on purpose. Typed cells, column schemas, variants, row identifiers, metadata, and validation states remain deferred until the record/cluster and status corridors are settled. This keeps the first frog.table value compatible with the current public type system's built-in arrays and strings.

4. Published Surface

Primitive Inputs Outputs Role
frog.table.build columns, rows table Create a table value.
frog.table.empty columns table Create an empty table with headers.
frog.table.row_count table count Return the number of rows.
frog.table.column_count table count Return the number of columns.
frog.table.columns table columns Return column headers.
frog.table.rows table rows Return row-major cell text.
frog.table.cell table, row, column value Return one cell.
frog.table.with_cell table, row, column, value result Return a table with one replaced cell.
frog.table.row table, row values Return one row.
frog.table.column table, column values Return one column.
frog.table.append_row table, values result Return a table with one row appended.
frog.table.with_columns table, columns result Return a table with replacement headers.
frog.table.to_delimited_text table, delimiter, include_header text Format a table as simple delimited text.

5. Primitive Contracts

frog.table.build

  • columns: array<string>
  • rows: array<array<string>>
  • Every row length MUST equal the number of columns.
  • If columns is empty, rows MUST also be empty.

frog.table.empty

  • Creates a table with the supplied columns and zero rows.
  • Duplicate column names are allowed as display text in v0.1; stable typed column ids are deferred.

Structural queries

  • frog.table.row_count returns u64.
  • frog.table.column_count returns u64.
  • frog.table.columns returns array<string>.
  • frog.table.rows returns array<array<string>>.

Cell, row, and column access

  • row and column index inputs have type u64.
  • Indexes MUST be in range.
  • frog.table.cell returns string.
  • frog.table.row returns array<string> with length column_count.
  • frog.table.column returns array<string> with length row_count.

Pure updates

  • frog.table.with_cell returns a new table value; it does not mutate the input table in place.
  • frog.table.append_row requires the new row length to equal column_count.
  • frog.table.with_columns requires the replacement header count to equal the current column_count.

frog.table.to_delimited_text

  • delimiter has type string and MUST be non-empty.
  • include_header has type bool.
  • The result has type string.
  • Cells containing the delimiter, quotes, or line breaks are quoted with double quotes. Embedded double quotes are escaped by doubling them.
  • This is value formatting only; it does not read or write files.

6. Effects, Status, and FIR

Every published frog.table primitive has:

  • call_class = standard_library_value
  • effect = pure
  • status_model = none
  • no provider requirement

The library uses validation preconditions rather than local status outputs. Non-rectangular row data, out-of-range indexes, invalid replacement row length, invalid replacement column length, and empty delimiters are validation or execution-profile failures until the uniform status corridor is standardized.

FIR SHOULD preserve table calls as named public library calls with library_id = "frog.table". The table value may be represented as a library value object with explicit columns and rows fields, or as an equivalent FIR support value. FIR MUST NOT replace a table value with a table-widget instance, a host grid handle, a database cursor, or a private runtime cache.

7. Candidate Deferrals

  • Typed cells, column schemas, and cell variants.
  • Row ids, metadata, validation state, formatting state, and cell-level presentation state.
  • Sorting and filtering as value transforms distinct from widget view state.
  • CSV, TSV, spreadsheet, database, and data-frame import/export.
  • Streaming table rows and lazy result sets.
  • Record/cluster-backed rows after the base record/cluster value model is decided.

8. Non-goals

  • Do not make frog.table a wrapper for one host grid control.
  • Do not hide database or spreadsheet connectivity inside the intrinsic table library.
  • Do not treat Table widget viewport, selection, sorting, or editing state as the table value itself.
  • Do not standardize arbitrary heterogeneous records through table rows in v0.1.

9. Summary

frog.table publishes a small text-cell rectangular table value and pure table primitives for construction, inspection, extraction, replacement, row append, header replacement, and delimited-text formatting. It keeps table data separate from widgets, databases, spreadsheets, and private host grid implementations.

End of FROG Table Library Specification