Module

Hylograph.Flow.Grouping

Package
purescript-hylograph-flow
Repository
afcondon/purescript-hylograph-flow

Grouping beside a flow, never in it: a nested partition of the flow's steps and items (a rose tree whose leaves are steps and items), and collapse, which draws a cut through it and gives the coarser flow.

What a group names

Member names a step and Holds names an item; a Group holds either, and groups. A grouping is well formed when every step, every item and every group id is in it at most once (groupingProblems says what is not). Nothing ties an item's group to its writer's: a table of entered data has no writer and belongs to its sheet; a module's output belongs to its package; an item may be held by one group and written by a step of another. An item no group holds is treated as 0.1 treated every item (see the last rule below), so a grouping of steps alone means what it meant.

What a closed group is, in the coarser flow

The core has two kinds of node and wires only between the two kinds, and collapse keeps to that. A closed group becomes

  • one step, GroupStep of its id, carrying the payloads of every step and every item shut inside it (Closed); and
  • at most one item, its summary, GroupItem of its id: what the group provides. It is there exactly when something leaves the group through an item, and it is written by the group's step and by nothing else, so the one-writer rule holds of it by construction.

Which side of the cut an element is on:

  • a step under a closed group is inside it (the outermost closed group over it; an open group is transparent);
  • an item a closed group holds is inside it, unless an open step writes it. An item written by a step that stays drawn stays drawn: it is the one thing that can stand between that step and the group, since a wire joins an item and a step, and it is not invented;
  • an item no closed group holds is inside a closed group only as in 0.1: when that group writes it, and it is read, and read only there.

And then every wire of the finer flow is exactly one of these:

| the wire | in the coarser flow | |---|---| | both ends inside one closed group | gone: it is inside the group | | neither end inside a closed group | itself | | a step inside G, an item that stays | the same wire at GroupStep G, by the member's port (MemberPort); parallel ones merged, as in 0.1 | | an item inside G read by a step outside G | a read of G's summary: by the reader's own port, or by SummaryPort G where the reader is itself a closed group's step | | an item inside G written by a step inside another closed group H | a read of H's summary by GroupStep G, at SummaryPort H |

Wires left with one identity are merged, their payloads combined with <> in wire order. A summary's one write wire carries the combination of every wire that became a read of it: what a group provides is what is taken from it. No wire of the coarser flow is invented: each stands for at least one wire of the finer flow, which is why Semigroup is enough.

So what crosses a group's boundary is conserved. The wires of the finer flow with one end inside G and one outside are, payload for payload, the wires of the coarser flow that join G's step or summary to anything else (the summary's own write wire is inside the group's two nodes and repeats what the reads of it carry).

Between two closed groups G and H, everything that goes from G to H through items inside either is one wire, Reads (GroupItem G) (GroupStep H) (SummaryPort G). Under Steps that is one edge from G to H, and one from H to G where each reads the other: a cycle between two closed groups is two edges, neither dropped. Under Both a providing group is its step, its summary, and the wire between; under Holders it is its summary alone, with an edge from every summary and item it reads, and a group that provides nothing is no node (as a step that writes nothing is no edge). A second edge between two closed groups can only run through an item that stayed drawn, which is an item no closed group holds.

Identities

GroupStep, GroupItem, MemberPort and SummaryPort are constructors no step, item or port of a source has. So whatever the source's elements are called, none is taken for a group's, and a flow already collapsed can be collapsed again: a Member may name a GroupStep and a Holds a GroupItem. (The one thing left to the caller: a second cut must not reuse the id of a group the first cut closed, unless it holds that group's step.)

One mechanism for a radio's fused runs, for semantic zoom, for the rig chart's machines opened into their voices, for a workbook by sheet and a workspace by package.

#Grouping Source

data Grouping

A step, an item, or a named group of groupings.

Constructors

#Collapsed Source

data Collapsed item step

A step of the coarser flow: one kept as it was, or a closed group with the payloads of everything shut inside it: its steps in step order, and its items in item order. Every step of the finer flow is kept or is in exactly one closed group's steps, and every item is kept or is in exactly one closed group's items.

Constructors

Instances

#CollapsedItem Source

data CollapsedItem item

An item of the coarser flow: one kept as it was, or a closed group's summary with the payloads of the items it stands for, in item order: those inside the group that something outside reads, and those inside another closed group that this group writes. There is always one, since a summary is there only when something leaves through it.

Constructors

Instances

#GroupingProblem Source

data GroupingProblem

What keeps a forest from being a partition.

Constructors

Instances

#members Source

members :: Grouping -> Array StepId

Every step under a grouping.

#held Source

held :: Grouping -> Array ItemId

Every item under a grouping.

#groupingProblems Source

groupingProblems :: Array Grouping -> Array GroupingProblem

A forest is well formed when no step, no item and no group id is in it twice. (collapse is total even so: where a forest puts an element under two closed groups, it is in the later one.)

#collapse Source

collapse :: forall i s w. Semigroup w => Array Grouping -> Set GroupId -> Flow i s w -> Flow (CollapsedItem i) (Collapsed i s) w

The coarser flow for a cut: the groups in closed are drawn shut; a closed group shuts everything under it; an open one is transparent. The module's header says what each element and each wire becomes.

Parallel wires are merged: where several members of a closed group read one item that stays visible, the group reads it by one wire, at the port of the first of them, carrying what they carried, combined in wire order. (Likewise for writes, and for any two wires left with one identity.) The group keeps no port for a wire merged away. So between a closed group and an item there is at most one wire each way, and no two wires of the coarser flow share an identity.

Order: the items that stay, in item order, then the summaries in the order of their groups in the forest. A closed group's step stands where the first of its member steps stood; one with no step of the flow under it (a group of items only) comes after every other step, in forest order. A closed group with nothing of the flow inside it is no step. Wires in the order of the first wire each stands for, a summary's write just before the first read of it.

Semigroup, not a function argument: the merge has to be associative for the result not to depend on how the wires happen to be bracketed, which is the one law the class states, and Unit already has it.

#groupStep Source

groupStep :: GroupId -> StepId

The step a closed group becomes.

#groupItem Source

groupItem :: GroupId -> ItemId

The summary item of a closed group: what it provides.

Re-exports from Hylograph.Flow

#GroupId Source

newtype GroupId

Which group, of a grouping beside a flow (Hylograph.Flow.Grouping). Here, and not there, because a closed group's step, its summary item and the port between them are named by it.

Constructors

Instances