Module

Hylograph.Flow.Render.Engine

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

What any layout engine makes, and an engine as a value.

In 0.2 the renderer had one layout, the Sankey layout, and its types were that layout's: a Layout was what layout returned, a picture held Sankey Metrics and Widths, and the laws asserted Sankey facts. A trial that drew the same flows with a second engine had to pass its result off as a Sankey layout. This module is the layout result with the Sankey layout taken out of it, so that the tree draws a Layout and the laws and measures read one without knowing which engine made it.

It is designed for three engines and no others: the Sankey layout (Hylograph.Flow.Render.Sankey), layered-layout (ports, right-angled routes, no widths; its adapter lives outside this package, which must not depend on it), and Stemma, a rewrite of Graphviz dot (clusters, splines, ranks, top-down by default).

THE DECISIONS, each with its reason.

  • A route is data (Hylograph.Flow.Render.Route), and a placed edge has no path, start, end, width or stroke of its own: each is read from the route (Route.svgPath, Route.start, …), so none can disagree with it.
  • Ports are placed on nodes (PlacedNode.ports). A placed port is which port (its name, and whether it is one of the node's inputs or its outputs: a step may have an input and an output of one name), the side of the box it is on, and how far along that side: so it is on the box's boundary by construction, and portPoint says where. An engine places the ports it gives a place to and no others: the Sankey layout stacks a node's edges by where they go, not by port, and places none. Whether an edge meets a port is not a field of the edge: the edge already names its ports (Edge.fromPort, Edge.toPort, the core's), and the law is that where the node has that port placed the route ends there.
  • direction is the layout's, not the tree's or the caller's: the engine knows which way it ran. The laws read "forward" and "aligned" by it, and the tree sets a node's words by it.
  • layer stays a Maybe. It is the layer (dot's rank) the engine put a node in of the whole picture, and some placed nodes have none: the Sankey layout's shelf of nodes no edge touches, and every node of a layout made of several layerings (layered-layout run once for each open group). Both are real, so the case is not designed out; what is designed out is a layer that means something only within a part of the picture.
  • An engine is a value (Engine): a name, the function, and what it promises. A Picture is what every engine is told beside the projection: what is written in a node, and which groups are open. What only one engine can be told (the Sankey layout's Metrics and Widths, the other's spacings) is that engine's own configuration, given where the engine is made (sankey metrics widths), and is not in Picture. Node breadth is among those: an engine may size a node as it likes, and the law about words reads the breadth a node was given from its own box.
  • Promises are a closed ADT (Promise), one constructor for each law that holds of some engines and not of all. A promise carries what its law needs and no layout holds: WidthsConserved carries the scale and the edge's quantity. Hylograph.Flow.Render.Laws checks the general laws of every layout and, of an engine's layout, exactly the laws it promises: an engine that does not conserve widths is not asked to, so nothing has to be suppressed.

#Box Source

type Box = { height :: Number, width :: Number, x :: Number, y :: Number }

#Direction Source

data Direction

Which way the flow runs in a layout: its layers are columns (LeftToRight) or rows (TopDown).

Constructors

Instances

#Side Source

data Side

A side of a box.

Constructors

Instances

#PortFlow Source

data PortFlow

Which of a node's ports a name is among: its inputs or its outputs.

Constructors

Instances

#PlacedPort Source

type PlacedPort = { along :: Number, flow :: PortFlow, name :: PortName, side :: Side }

A port with a place. along: how far along side it is, in pixels from the side's top (a left or right side) or its left end (a top or bottom side).

#portPoint Source

portPoint :: Box -> PlacedPort -> Point

Where on the picture a port of a box is.

#Course Source

data Course

Forward: with the flow. Backward: an edge the engine turned back to close a cycle (a scan reading what it wrote).

Constructors

Instances

#PlacedNode Source

type PlacedNode = { box :: Box, index :: Int, layer :: Maybe Int, node :: Node, ports :: Array PlacedPort, words :: Maybe SetWords }

index: the node's place in the projection. layer: its layer in the whole picture, where the engine gave it one (see the module's header). words: what is written in it, as set, where the picture said (Picture.words); Nothing where it did not. ports: the ports the engine gave a place; none for an item, which has none.

#PlacedEdge Source

type PlacedEdge wire = { course :: Course, edge :: Edge wire, index :: Int, route :: Route }

index: the edge's place in the projection. edge: the projection's own, with the wires it stands for, so what is known of a wire can be shown on it. route: the line it is drawn along, from its source to its target.

#PlacedOutline Source

type PlacedOutline = { box :: Box, depth :: Int, group :: GroupId, header :: Number, members :: Array Int, name :: String, parent :: Maybe GroupId }

An open group's outline. name: the group's, from the grouping. header: the height of the strip at the top of box that is kept for the name. depth: how many outlines it is inside; parent: the nearest. members: the indices of the nodes inside it, however deep.

#Layout Source

type Layout wire = { direction :: Direction, edges :: Array (PlacedEdge wire), height :: Number, nodes :: Array PlacedNode, outlines :: Array PlacedOutline, width :: Number }

Nodes and edges in the projection's order. An edge with an end that is no node of the projection has no place and is left out (project makes none). Outlines outermost first, so drawn in order an outline is over the one that holds it; none unless the picture told of groups.

#Groups Source

type Groups = { closed :: Set GroupId, grouping :: Array Grouping }

The grouping, and the groups that are closed: what collapse was given to make the flow that was projected. Every other group is open.

#OutlineMetrics Source

type OutlineMetrics = { header :: Number, padding :: Number }

padding: from an outline to what is in it. header: the strip for the group's name.

#Picture Source

type Picture = { groups :: Maybe Groups, lettering :: Lettering, outline :: OutlineMetrics, words :: Maybe (Node -> Words) }

What every engine is told beside the projection. words: what is written in each node, for the engine to wrap to the breadth it gives the node and make room for; Nothing leaves every node as tall as the engine makes it and its label to the tree, on one line. groups: the open groups to outline; Nothing for none.

#plainPicture Source

plainPicture :: Picture

No words set and no group outlined.

#openPaths Source

openPaths :: Groups -> { nameOf :: GroupId -> String, pathOf :: ElementKey -> Array GroupId }

The open groups a drawn element is in, outermost first, and every group's name. A step is where Member puts it and an item where Holds does; a closed group's step and its summary are in the groups their group is in; an item a closed group holds that is drawn all the same (an open step writes it) is in the open groups over that group. An element no group holds is in none.

#Conservation Source

type Conservation wire = { pixelsPerUnit :: Number, unitsOf :: Edge wire -> Number }

What the law of conserved widths needs and no layout holds: the pixels to one unit of width, and an edge's width in units.

#Promise Source

data Promise wire

A law that holds of some engines' layouts and not of every layout; an engine lists the ones it keeps. What each says exactly is in Hylograph.Flow.Render.Laws.

  • FlowsForward: an edge not turned back runs with the flow, and where the projection has no cycle no edge is turned back.
  • LayersAligned: the nodes of one layer stand in one line across the flow.
  • RoutesOrthogonal: every route is straight legs along the axes.
  • WidthsConserved: every route is a ribbon as broad as its quantity says, and at each node the ribbons of a side stand in the node, beside one another, and the node is as tall as the broader side.

Constructors

#Engine Source

newtype Engine wire

A layout engine: what it is called, what it promises of every layout it makes, and the making.

Constructors

#run Source

run :: forall wire. Engine wire -> Picture -> Projection wire -> Layout wire

An engine's layout of a projection.

#engineName Source

engineName :: forall wire. Engine wire -> String

#promises Source

promises :: forall wire. Engine wire -> Array (Promise wire)

Re-exports from Hylograph.Flow.Render.Route

#Point Source

type Point = { x :: Number, y :: Number }