Diagrams.Combinators

Higher-level tools for combining diagrams.

Unary operations

withBounds :: (Backend b (V a), Boundable a, Monoid m) => a -> AnnDiagram b (V a) m -> AnnDiagram b (V a) m

Use the bounding region from some boundable object as the bounding region for a diagram, in place of the diagram's default bounding region.

phantom :: (Backend b (V a), Boundable a, Monoid m) => a -> AnnDiagram b (V a) m

phantom x produces a "phantom" diagram, which has the same bounding region as x but produces no output.

strut :: (Backend b v, InnerSpace v, OrderedField (Scalar v), Monoid m) => v -> AnnDiagram b v m

strut v is a diagram which produces no output, but for the purposes of alignment and bounding regions acts like a 1-dimensional segment oriented along the vector v, with local origin at its center. Useful for manually creating separation between two diagrams.

pad :: (Backend b v, InnerSpace v, OrderedField (Scalar v), Monoid m) => Scalar v -> AnnDiagram b v m -> AnnDiagram b v m

pad s "pads" a diagram, expanding its bounding region by a factor of s (factors between 0 and 1 can be used to shrink the bounding region). Note that the bounding region will expand with respect to the local origin, so if the origin is not centered the padding may appear "uneven". If this is not desired, the origin can be centered (using, e.g., centerXY for 2D diagrams) before applying pad.

Binary operations

beside :: (HasOrigin a, Boundable a, Monoid a) => V a -> a -> a -> a

Place two bounded, monoidal objects (i.e. diagrams or paths) next to each other along the given vector. In particular, place the first object so that the vector points from its local origin to the local origin of the second object, at a distance so that their bounding regions are just tangent. The local origin of the new, combined object is at the point of tangency, along the line between the old local origins.

besideBounds :: (HasOrigin a, Boundable a) => Bounds (V a) -> V a -> a -> a

besideBounds b v x positions x so it is beside the bounding region b in the direction of v. The origin of the new diagram is the origin of the bounding region.

append :: (HasOrigin a, Boundable a, Monoid a) => V a -> a -> a -> a

Like beside, but the origin of the final combined object is the origin of the first object. See also appends.

n-ary operations

appends :: (HasOrigin a, Boundable a, Monoid a) => a -> [(V a, a)] -> a

appends x ys appends each of the objects in ys to the object x in the corresponding direction. Note that each object in ys is positioned beside x without reference to the other objects in ys, so this is not the same as iterating append.

position :: (HasOrigin a, Monoid a) => [(Point (V a), a)] -> a

Position things absolutely: combine a list of objects (e.g. diagrams or paths) by assigning them absolute positions in the vector space of the combined object.

decorateTrail :: (HasOrigin a, Monoid a) => Trail (V a) -> [a] -> a

Combine a list of diagrams (or paths) by using them to "decorate" a trail, placing the local origin of one object at each successive vertex of the trail. The first vertex of the trail is placed at the origin. If the trail and list of objects have different lengths, the extra tail of the longer one is ignored.

decoratePath :: (HasOrigin a, Monoid a) => Path (V a) -> [a] -> a

Combine a list of diagrams (or paths) by using them to "decorate" a path, placing the local origin of one object at each successive vertex of the path. If the path and list of objects have different lengths, the extra tail of the longer one is ignored.

cat :: (HasOrigin a, Boundable a, Monoid a) => V a -> [a] -> a

cat v positions a list of objects so that their local origins lie along a line in the direction of v. Successive objects will have their bounding regions just touching. The local origin of the result will be the same as the local origin of the first object.

See also cat', which takes an extra options record allowing certain aspects of the operation to be tweaked.

cat' :: (HasOrigin a, Boundable a, Monoid a) => V a -> CatOpts (V a) -> [a] -> a

Like cat, but taking an extra CatOpts arguments allowing the user to specify

• The spacing method: catenation (uniform spacing between boundaries) or distribution (uniform spacing between local origins). The default is catenation.
• The amount of separation between successive diagram boundaries/origins (depending on the spacing method). The default is 0.

CatOpts is an instance of Default, so with may be used for the second argument, as in cat' (1,2) with {sep = 2}.

Note that cat' v with {catMethod = Distrib} === mconcat (distributing with a separation of 0 is the same as superimposing).

data CatOpts v

Options for cat'.

Constructors

CatOpts

Fields

catMethod :: CatMethod

Which CatMethod should be used: normal catenation (default), or distribution?

sep :: Scalar v

How much separation should be used between successive diagrams (default: 0)? When catMethod = Cat, this is the distance between boundaries; when catMethod = Distrib, this is the distance between origins.

catOptsvProxy__ :: Proxy v

This field exists solely to aid type inference; please ignore it.

Instances

Num (Scalar v) => Default (CatOpts v)

data CatMethod

Methods for concatenating diagrams.

Constructors

Cat

Normal catenation: simply put diagrams next to one another (possibly with a certain distance in between each). The distance between successive diagram boundaries will be consistent; the distance between origins may vary if the diagrams are of different sizes.

Distrib

Distribution: place the local origins of diagrams at regular intervals. With this method, the distance between successive origins will be consistent but the distance between boundaries may not be. Indeed, depending on the amount of separation, diagrams may overlap.