diagrams-core-1.5.1.1: Core libraries for diagrams EDSL

Copyright | (c) 2011-2015 diagrams-core team (see LICENSE)
License | BSD-style (see LICENSE)
Maintainer | diagrams-discuss@googlegroups.com
Safe Haskell | None
Language | Haskell2010

Diagrams.Core.Types

Contents

- Diagrams
  - Annotations
    - Static annotations
    - Dynamic (monoidal) annotations
  - Basic type definitions
- Operations on diagrams
  - Creating diagrams
  - Extracting information
  - Combining diagrams
  - Modifying diagrams
    - Names
    - Other
- Subdiagrams
- Subdiagram maps
- Primtives
- Backends
  - Null backend
  - Number classes
- Renderable
- Orphan instances

Description

The core library of primitives forming the basis of an embedded domain-specific language for describing and rendering diagrams.

Diagrams.Core.Types defines types and classes for primitives, diagrams, and backends.

Synopsis

- data Annotation
  - = Href String
  - | OpacityGroup Double
  - | KeyVal (String, String)
- applyAnnotation :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Annotation -> QDiagram b v n m -> QDiagram b v n m
- href :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => String -> QDiagram b v n m -> QDiagram b v n m
- opacityGroup :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Double -> QDiagram b v n m -> QDiagram b v n m
- groupOpacity :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Double -> QDiagram b v n m -> QDiagram b v n m
- keyVal :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => (String, String) -> QDiagram b v n m -> QDiagram b v n m
- type UpAnnots b (v :: Type -> Type) n m = Deletable (Envelope v n) ::: (Deletable (Trace v n) ::: (Deletable (SubMap b v n m) ::: (Query v n m ::: ())))
- type DownAnnots (v :: Type -> Type) n = (Transformation v n :+: Style v n) ::: (Name ::: ())
- transfToAnnot :: forall (v :: Type -> Type) n. Transformation v n -> DownAnnots v n
- transfFromAnnot :: forall (v :: Type -> Type) n. (Additive v, Num n) => DownAnnots v n -> Transformation v n
- data QDiaLeaf b (v :: Type -> Type) n m
  - = PrimLeaf (Prim b v n)
  - | DelayedLeaf (DownAnnots v n -> n -> n -> QDiagram b v n m)
- withQDiaLeaf :: forall b (v :: Type -> Type) n r m. (Prim b v n -> r) -> ((DownAnnots v n -> n -> n -> QDiagram b v n m) -> r) -> QDiaLeaf b v n m -> r
- newtype QDiagram b (v :: Type -> Type) n m = QD (DUALTree (DownAnnots v n) (UpAnnots b v n m) Annotation (QDiaLeaf b v n m))
- type Diagram b = QDiagram b (V b) (N b) Any
- mkQD :: forall b (v :: Type -> Type) n m. Prim b v n -> Envelope v n -> Trace v n -> SubMap b v n m -> Query v n m -> QDiagram b v n m
- mkQD' :: forall b (v :: Type -> Type) n m. QDiaLeaf b v n m -> Envelope v n -> Trace v n -> SubMap b v n m -> Query v n m -> QDiagram b v n m
- pointDiagram :: forall (v :: Type -> Type) n b m. (Metric v, Fractional n) => Point v n -> QDiagram b v n m
- envelope :: forall n (v :: Type -> Type) m b. (OrderedField n, Metric v, Monoid' m) => Lens' (QDiagram b v n m) (Envelope v n)
- trace :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Lens' (QDiagram b v n m) (Trace v n)
- subMap :: forall (v :: Type -> Type) m n b. (Metric v, Semigroup m, OrderedField n) => Lens' (QDiagram b v n m) (SubMap b v n m)
- names :: forall (v :: Type -> Type) m n b. (Metric v, Semigroup m, OrderedField n) => QDiagram b v n m -> [(Name, [Point v n])]
- query :: forall m b (v :: Type -> Type) n. Monoid m => QDiagram b v n m -> Query v n m
- atop :: forall n (v :: Type -> Type) m b. (OrderedField n, Metric v, Semigroup m) => QDiagram b v n m -> QDiagram b v n m -> QDiagram b v n m
- nameSub :: forall nm (v :: Type -> Type) n m b. (IsName nm, Metric v, OrderedField n, Semigroup m) => (QDiagram b v n m -> Subdiagram b v n m) -> nm -> QDiagram b v n m -> QDiagram b v n m
- lookupName :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> QDiagram b v n m -> Maybe (Subdiagram b v n m)
- withName :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> (Subdiagram b v n m -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m
- withNameAll :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> ([Subdiagram b v n m] -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m
- withNames :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => [nm] -> ([Subdiagram b v n m] -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m
- localize :: forall b (v :: Type -> Type) n m. (Metric v, OrderedField n, Semigroup m) => QDiagram b v n m -> QDiagram b v n m
- setEnvelope :: forall b (v :: Type -> Type) n m. (OrderedField n, Metric v, Monoid' m) => Envelope v n -> QDiagram b v n m -> QDiagram b v n m
- setTrace :: forall b (v :: Type -> Type) n m. (OrderedField n, Metric v, Semigroup m) => Trace v n -> QDiagram b v n m -> QDiagram b v n m
- data Subdiagram b (v :: Type -> Type) n m = Subdiagram (QDiagram b v n m) (DownAnnots v n)
- mkSubdiagram :: forall b (v :: Type -> Type) n m. QDiagram b v n m -> Subdiagram b v n m
- getSub :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Subdiagram b v n m -> QDiagram b v n m
- rawSub :: forall b (v :: Type -> Type) n m. Subdiagram b v n m -> QDiagram b v n m
- location :: forall (v :: Type -> Type) n b m. (Additive v, Num n) => Subdiagram b v n m -> Point v n
- subPoint :: forall (v :: Type -> Type) n b m. (Metric v, OrderedField n) => Point v n -> Subdiagram b v n m
- newtype SubMap b (v :: Type -> Type) n m = SubMap (Map Name [Subdiagram b v n m])
- fromNames :: forall a b (v :: Type -> Type) n m. IsName a => [(a, Subdiagram b v n m)] -> SubMap b v n m
- rememberAs :: forall a b (v :: Type -> Type) n m. IsName a => a -> QDiagram b v n m -> SubMap b v n m -> SubMap b v n m
- lookupSub :: forall nm b (v :: Type -> Type) n m. IsName nm => nm -> SubMap b v n m -> Maybe [Subdiagram b v n m]
- data Prim b (v :: Type -> Type) n where
  - Prim :: forall p b. (Transformable p, Typeable p, Renderable p b) => p -> Prim b (V p) (N p)
- _Prim :: (Typeable p, Renderable p b) => Prism' (Prim b (V p) (N p)) p
- class Backend b (v :: Type -> Type) n where
  - data Render b (v :: Type -> Type) n
  - type Result b (v :: Type -> Type) n
  - data Options b (v :: Type -> Type) n
  - adjustDia :: (Additive v, Monoid' m, Num n) => b -> Options b v n -> QDiagram b v n m -> (Options b v n, Transformation v n, QDiagram b v n m)
  - renderRTree :: b -> Options b v n -> RTree b v n Annotation -> Result b v n
- type DTree b (v :: Type -> Type) n a = Tree (DNode b v n a)
- data DNode b (v :: Type -> Type) n a
  - = DStyle (Style v n)
  - | DTransform (Transformation v n)
  - | DAnnot a
  - | DDelay
  - | DPrim (Prim b v n)
  - | DEmpty
- type RTree b (v :: Type -> Type) n a = Tree (RNode b v n a)
- data RNode b (v :: Type -> Type) n a
  - = RStyle (Style v n)
  - | RAnnot a
  - | RPrim (Prim b v n)
  - | REmpty
- _RStyle :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p (Style v n) (f (Style v n)) -> p (RNode b v n a) (f (RNode b v n a))
- _RAnnot :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p a (f a) -> p (RNode b v n a) (f (RNode b v n a))
- _RPrim :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p (Prim b v n) (f (Prim b v n)) -> p (RNode b v n a) (f (RNode b v n a))
- _REmpty :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p () (f ()) -> p (RNode b v n a) (f (RNode b v n a))
- data NullBackend
- type D (v :: Type -> Type) n = QDiagram NullBackend v n Any
- type TypeableFloat n = (Typeable n, RealFloat n)
- class Transformable t => Renderable t b where
  - render :: b -> t -> Render b (V t) (N t)

# Diagrams

## Annotations

### Static annotations

data Annotation Source #

Static annotations which can be placed at a particular node of a diagram tree.

Constructors

Href String | Hyperlink
OpacityGroup Double |
KeyVal (String, String) |

#### Instances

Instances details

Show Annotation Source # |
Instance details Defined in Diagrams.Core.Types Methods showsPrec :: Int -> Annotation -> ShowS Source # show :: Annotation -> String Source # showList :: [Annotation] -> ShowS Source #

applyAnnotation :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Annotation -> QDiagram b v n m -> QDiagram b v n m Source #

Apply a static annotation at the root of a diagram.

href :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => String -> QDiagram b v n m -> QDiagram b v n m Source #

Make a diagram into a hyperlink. Note that only some backends will honor hyperlink annotations.

opacityGroup :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Double -> QDiagram b v n m -> QDiagram b v n m Source #

Change the transparency of a `Diagram` as a group.

groupOpacity :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Double -> QDiagram b v n m -> QDiagram b v n m Source #

Change the transparency of a `Diagram` as a group.

keyVal :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => (String, String) -> QDiagram b v n m -> QDiagram b v n m Source #

Apply a general Key-Value annotation

### Dynamic (monoidal) annotations

type UpAnnots b (v :: Type -> Type) n m = Deletable (Envelope v n) ::: (Deletable (Trace v n) ::: (Deletable (SubMap b v n m) ::: (Query v n m ::: ()))) Source #

Monoidal annotations which travel up the diagram tree, i.e. which are aggregated from component diagrams to the whole:

- envelopes (see Diagrams.Core.Envelope). The envelopes are "deletable" meaning that at any point we can throw away the existing envelope and replace it with a new one; sometimes we want to consider a diagram as having a different envelope unrelated to its "natural" envelope.
- traces (see Diagrams.Core.Trace), also deletable.
- name/subdiagram associations (see Diagrams.Core.Names)
- query functions (see Diagrams.Core.Query)

type DownAnnots (v :: Type -> Type) n = (Transformation v n :+: Style v n) ::: (Name ::: ()) Source #

Monoidal annotations which travel down the diagram tree, i.e. which accumulate along each path to a leaf (and which can act on the upwards-travelling annotations):

- styles (see Diagrams.Core.Style)
- names (see Diagrams.Core.Names)

transfToAnnot :: forall (v :: Type -> Type) n. Transformation v n -> DownAnnots v n Source #

Inject a transformation into a default downwards annotation value.

transfFromAnnot :: forall (v :: Type -> Type) n. (Additive v, Num n) => DownAnnots v n -> Transformation v n Source #

Extract the (total) transformation from a downwards annotation value.

## Basic type definitions

data QDiaLeaf b (v :: Type -> Type) n m Source #

A leaf in a `QDiagram` tree is either a `Prim`, or a "delayed" `QDiagram` which expands to a real `QDiagram` once it learns the "final context" in which it will be rendered. For example, in order to decide how to draw an arrow, we must know the precise transformation applied to it (since the arrow head and tail are scale-invariant).

Constructors

PrimLeaf (Prim b v n) |
DelayedLeaf (DownAnnots v n -> n -> n -> QDiagram b v n m) | The `QDiagram` produced by a `DelayedLeaf` function must already apply any transformation in the given `DownAnnots` (that is, the transformation will not be applied by the context).

#### Instances

Instances details

Functor (QDiaLeaf b v n) Source # |
Instance details Defined in Diagrams.Core.Types Methods fmap :: (a -> b0) -> QDiaLeaf b v n a -> QDiaLeaf b v n b0 Source # (<$) :: a -> QDiaLeaf b v n b0 -> QDiaLeaf b v n a Source #

withQDiaLeaf :: forall b (v :: Type -> Type) n r m. (Prim b v n -> r) -> ((DownAnnots v n -> n -> n -> QDiagram b v n m) -> r) -> QDiaLeaf b v n m -> r Source #

newtype QDiagram b (v :: Type -> Type) n m Source #

The fundamental diagram type. The type variables are as follows:

- `b` represents the backend, such as `SVG` or `Cairo`. Note that each backend also exports a type synonym `B` for itself, so the type variable `b` may also typically be instantiated by `B`, meaning "use whatever backend is in scope".
- `v` represents the vector space of the diagram. Typical instantiations include `V2` (for a two-dimensional diagram) or `V3` (for a three-dimensional diagram).
- `n` represents the numerical field the diagram uses. Typically this will be a concrete numeric type like `Double`.
- `m` is the monoidal type of "query annotations": each point in the diagram has a value of type `m` associated to it, and these values are combined according to the `Monoid` instance for `m`. Most often, `m` is simply instantiated to `Any`, associating a simple `Bool` value to each point indicating whether the point is inside the diagram; `Diagram` is a synonym for `QDiagram` with `m` thus instantiated to `Any`.

Diagrams can be combined via their `Monoid` instance, transformed via their `Transformable` instance, and assigned attributes via their `HasStyle` instance.

Note that the `Q` in `QDiagram` stands for "Queriable", as distinguished from `Diagram`, where `m` is fixed to `Any`. This is not really a very good name, but it's probably not worth changing it at this point.

Constructors

QD (DUALTree (DownAnnots v n) (UpAnnots b v n m) Annotation (QDiaLeaf b v n m)) |

#### Instances

Instances details

Functor (QDiagram b v n) Source # |
Instance details Defined in Diagrams.Core.Types Methods fmap :: (a -> b0) -> QDiagram b v n a -> QDiagram b v n b0 Source # (<$) :: a -> QDiagram b v n b0 -> QDiagram b v n a Source #
(Metric v, OrderedField n, Monoid' m) => Enveloped (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods getEnvelope :: QDiagram b v n m -> Envelope (V (QDiagram b v n m)) (N (QDiagram b v n m)) Source #
(Metric v, OrderedField n, Semigroup m) => HasOrigin (QDiagram b v n m) Source # | Every diagram has an intrinsic "local origin" which is the basis for all combining operations.
Instance details Defined in Diagrams.Core.Types Methods moveOriginTo :: Point (V (QDiagram b v n m)) (N (QDiagram b v n m)) -> QDiagram b v n m -> QDiagram b v n m Source #
(Metric v, OrderedField n, Monoid' m) => Juxtaposable (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods juxtapose :: Vn (QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m -> QDiagram b v n m Source #
(Metric v, OrderedField n, Semigroup m) => Qualifiable (QDiagram b v n m) Source # | Diagrams can be qualified so that all their named points can now be referred to using the qualification prefix.
Instance details Defined in Diagrams.Core.Types Methods (.>>) :: IsName a => a -> QDiagram b v n m -> QDiagram b v n m Source #
(Metric v, OrderedField n, Semigroup m) => HasStyle (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods applyStyle :: Style (V (QDiagram b v n m)) (N (QDiagram b v n m)) -> QDiagram b v n m -> QDiagram b v n m Source #
(Metric v, OrderedField n, Semigroup m) => Traced (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods getTrace :: QDiagram b v n m -> Trace (V (QDiagram b v n m)) (N (QDiagram b v n m)) Source #
(OrderedField n, Metric v, Semigroup m) => Transformable (QDiagram b v n m) Source # | Diagrams can be transformed by transforming each of their components appropriately.
Instance details Defined in Diagrams.Core.Types Methods transform :: Transformation (V (QDiagram b v n m)) (N (QDiagram b v n m)) -> QDiagram b v n m -> QDiagram b v n m Source #

(Metric v, OrderedField n, Semigroup m) => Monoid (QDiagram b v n m) Source #

Diagrams form a monoid since each of their components do: the empty diagram has no primitives, an empty envelope, an empty trace, no named subdiagrams, and a constantly empty query function.

Diagrams compose by aligning their respective local origins. The new diagram has all the primitives and all the names from the two diagrams combined, and query functions are combined pointwise. The first diagram goes on top of the second. "On top of" probably only makes sense in vector spaces of dimension lower than 3, but in theory it could make sense for, say, 3-dimensional diagrams when viewed by 4-dimensional beings.

Instance details Defined in Diagrams.Core.Types Methods mempty :: QDiagram b v n m Source # mappend :: QDiagram b v n m -> QDiagram b v n m -> QDiagram b v n m Source # mconcat :: [QDiagram b v n m] -> QDiagram b v n m Source #
(Metric v, OrderedField n, Semigroup m) => Semigroup (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods (<>) :: QDiagram b v n m -> QDiagram b v n m -> QDiagram b v n m Source # sconcat :: NonEmpty (QDiagram b v n m) -> QDiagram b v n m Source # stimes :: Integral b0 => b0 -> QDiagram b v n m -> QDiagram b v n m Source #
Wrapped (QDiagram b v n m) Source # |

Instance details

Defined in Diagrams.Core.Types

Associated Types

type Unwrapped (QDiagram b v n m) |
Instance details Defined in Diagrams.Core.Types type Unwrapped (QDiagram b v n m) = DUALTree (DownAnnots v n) (UpAnnots b v n m) Annotation (QDiaLeaf b v n m)

Methods

_Wrapped' :: Iso' (QDiagram b v n m) (Unwrapped (QDiagram b v n m)) Source #

Rewrapped (QDiagram b v n m) (QDiagram b' v' n' m') Source # |
Instance details Defined in Diagrams.Core.Types
type N (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type N (QDiagram b v n m) = n
type V (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type V (QDiagram b v n m) = v
type Unwrapped (QDiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type Unwrapped (QDiagram b v n m) = DUALTree (DownAnnots v n) (UpAnnots b v n m) Annotation (QDiaLeaf b v n m)

type Diagram b = QDiagram b (V b) (N b) Any Source #

`Diagram b` is a synonym for ``QDiagram` b (V b) (N b) `Any``. That is, the default sort of diagram is one where querying at a point simply tells you whether the diagram contains that point or not. Transforming a default diagram into one with a more interesting query can be done via the `Functor` instance of ``QDiagram` b v n` or the `value` function.

# Operations on diagrams

## Creating diagrams

mkQD :: forall b (v :: Type -> Type) n m. Prim b v n -> Envelope v n -> Trace v n -> SubMap b v n m -> Query v n m -> QDiagram b v n m Source #

Create a diagram from a single primitive, along with an envelope, trace, subdiagram map, and query function.

mkQD' :: forall b (v :: Type -> Type) n m. QDiaLeaf b v n m -> Envelope v n -> Trace v n -> SubMap b v n m -> Query v n m -> QDiagram b v n m Source #

Create a diagram from a generic QDiaLeaf, along with an envelope, trace, subdiagram map, and query function.

pointDiagram :: forall (v :: Type -> Type) n b m. (Metric v, Fractional n) => Point v n -> QDiagram b v n m Source #

Create a "point diagram", which has no content, no trace, an empty query, and a point envelope.

## Extracting information

envelope :: forall n (v :: Type -> Type) m b. (OrderedField n, Metric v, Monoid' m) => Lens' (QDiagram b v n m) (Envelope v n) Source #

Lens onto the `Envelope` of a `QDiagram`.

trace :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Lens' (QDiagram b v n m) (Trace v n) Source #

Lens onto the `Trace` of a `QDiagram`.

subMap :: forall (v :: Type -> Type) m n b. (Metric v, Semigroup m, OrderedField n) => Lens' (QDiagram b v n m) (SubMap b v n m) Source #

Lens onto the `SubMap` of a `QDiagram` (i.e. an association from names to subdiagrams).

names :: forall (v :: Type -> Type) m n b. (Metric v, Semigroup m, OrderedField n) => QDiagram b v n m -> [(Name, [Point v n])] Source #

Get a list of names of subdiagrams and their locations.

query :: forall m b (v :: Type -> Type) n. Monoid m => QDiagram b v n m -> Query v n m Source #

Get the query function associated with a diagram.

## Combining diagrams

For many more ways of combining diagrams, see Diagrams.Combinators and Diagrams.TwoD.Combinators from the diagrams-lib package.

atop :: forall n (v :: Type -> Type) m b. (OrderedField n, Metric v, Semigroup m) => QDiagram b v n m -> QDiagram b v n m -> QDiagram b v n m infixl 6 Source #

A convenient synonym for `mappend` on diagrams, designed to be used infix (to help remember which diagram goes on top of which when combining them, namely, the first on top of the second).

## Modifying diagrams

### Names

nameSub :: forall nm (v :: Type -> Type) n m b. (IsName nm, Metric v, OrderedField n, Semigroup m) => (QDiagram b v n m -> Subdiagram b v n m) -> nm -> QDiagram b v n m -> QDiagram b v n m Source #

Attach an atomic name to a certain subdiagram, computed from the given diagram /with the mapping from name to subdiagram included/. The upshot of this knot-tying is that if `d' = d # named x`, then `lookupName x d' == Just d'` (instead of `Just d`).

lookupName :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> QDiagram b v n m -> Maybe (Subdiagram b v n m) Source #

Lookup the most recent diagram associated with (some qualification of) the given name.

withName :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> (Subdiagram b v n m -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m Source #

Given a name and a diagram transformation indexed by a subdiagram, perform the transformation using the most recent subdiagram associated with (some qualification of) the name, or perform the identity transformation if the name does not exist.

withNameAll :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> ([Subdiagram b v n m] -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m Source #

Given a name and a diagram transformation indexed by a list of subdiagrams, perform the transformation using the collection of all such subdiagrams associated with (some qualification of) the given name.

withNames :: forall nm (v :: Type -> Type) m n b. (IsName nm, Metric v, Semigroup m, OrderedField n) => [nm] -> ([Subdiagram b v n m] -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m Source #

Given a list of names and a diagram transformation indexed by a list of subdiagrams, perform the transformation using the list of most recent subdiagrams associated with (some qualification of) each name. Do nothing (the identity transformation) if any of the names do not exist.

localize :: forall b (v :: Type -> Type) n m. (Metric v, OrderedField n, Semigroup m) => QDiagram b v n m -> QDiagram b v n m Source #

"Localize" a diagram by hiding all the names, so they are no longer visible to the outside.

### Other

setEnvelope :: forall b (v :: Type -> Type) n m. (OrderedField n, Metric v, Monoid' m) => Envelope v n -> QDiagram b v n m -> QDiagram b v n m Source #

Replace the envelope of a diagram.

setTrace :: forall b (v :: Type -> Type) n m. (OrderedField n, Metric v, Semigroup m) => Trace v n -> QDiagram b v n m -> QDiagram b v n m Source #

Replace the trace of a diagram.

# Subdiagrams

data Subdiagram b (v :: Type -> Type) n m Source #

A `Subdiagram` represents a diagram embedded within the context of a larger diagram. Essentially, it consists of a diagram paired with any accumulated information from the larger context (transformations, attributes, etc.).

Constructors

Subdiagram (QDiagram b v n m) (DownAnnots v n) |

#### Instances

Instances details

Functor (Subdiagram b v n) Source # |
Instance details Defined in Diagrams.Core.Types Methods fmap :: (a -> b0) -> Subdiagram b v n a -> Subdiagram b v n b0 Source # (<$) :: a -> Subdiagram b v n b0 -> Subdiagram b v n a Source #
(OrderedField n, Metric v, Monoid' m) => Enveloped (Subdiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods getEnvelope :: Subdiagram b v n m -> Envelope (V (Subdiagram b v n m)) (N (Subdiagram b v n m)) Source #
(Metric v, OrderedField n) => HasOrigin (Subdiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods moveOriginTo :: Point (V (Subdiagram b v n m)) (N (Subdiagram b v n m)) -> Subdiagram b v n m -> Subdiagram b v n m Source #
(OrderedField n, Metric v, Semigroup m) => Traced (Subdiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods getTrace :: Subdiagram b v n m -> Trace (V (Subdiagram b v n m)) (N (Subdiagram b v n m)) Source #
Transformable (Subdiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods transform :: Transformation (V (Subdiagram b v n m)) (N (Subdiagram b v n m)) -> Subdiagram b v n m -> Subdiagram b v n m Source #
type N (Subdiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type N (Subdiagram b v n m) = n
type V (Subdiagram b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type V (Subdiagram b v n m) = v

mkSubdiagram :: forall b (v :: Type -> Type) n m. QDiagram b v n m -> Subdiagram b v n m Source #

Turn a diagram into a subdiagram with no accumulated context.

getSub :: forall (v :: Type -> Type) n m b. (Metric v, OrderedField n, Semigroup m) => Subdiagram b v n m -> QDiagram b v n m Source #

Turn a subdiagram into a normal diagram, including the enclosing context. Concretely, a subdiagram is a pair of (1) a diagram and (2) a "context" consisting of an extra transformation and attributes. `getSub` simply applies the transformation and attributes to the diagram to get the corresponding "top-level" diagram.

rawSub :: forall b (v :: Type -> Type) n m. Subdiagram b v n m -> QDiagram b v n m Source #

Extract the "raw" content of a subdiagram, by throwing away the context.

location :: forall (v :: Type -> Type) n b m. (Additive v, Num n) => Subdiagram b v n m -> Point v n Source #

Get the location of a subdiagram; that is, the location of its local origin with respect to the vector space of its parent diagram. In other words, the point where its local origin "ended up".

subPoint :: forall (v :: Type -> Type) n b m. (Metric v, OrderedField n) => Point v n -> Subdiagram b v n m Source #

Create a "point subdiagram", that is, a `pointDiagram` (with no content and a point envelope) treated as a subdiagram with local origin at the given point. Note this is not the same as `mkSubdiagram . pointDiagram`, which would result in a subdiagram with local origin at the parent origin, rather than at the given point.

# Subdiagram maps

newtype SubMap b (v :: Type -> Type) n m Source #

A `SubMap` is a map associating names to subdiagrams. There can be multiple associations for any given name.

Constructors

SubMap (Map Name [Subdiagram b v n m]) |

#### Instances

Instances details

Action Name (SubMap b v n m) Source # | A name acts on a name map by qualifying every name in it.
Instance details Defined in Diagrams.Core.Types Methods act :: Name -> SubMap b v n m -> SubMap b v n m Source #
Functor (SubMap b v n) Source # |
Instance details Defined in Diagrams.Core.Types Methods fmap :: (a -> b0) -> SubMap b v n a -> SubMap b v n b0 Source # (<$) :: a -> SubMap b v n b0 -> SubMap b v n a Source #
(OrderedField n, Metric v) => HasOrigin (SubMap b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods moveOriginTo :: Point (V (SubMap b v n m)) (N (SubMap b v n m)) -> SubMap b v n m -> SubMap b v n m Source #
Qualifiable (SubMap b v n m) Source # | `SubMap`s are qualifiable: if `ns` is a `SubMap`, then `a |> ns` is the same `SubMap` except with every name qualified by `a`.
Instance details Defined in Diagrams.Core.Types Methods (.>>) :: IsName a => a -> SubMap b v n m -> SubMap b v n m Source #
Transformable (SubMap b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods transform :: Transformation (V (SubMap b v n m)) (N (SubMap b v n m)) -> SubMap b v n m -> SubMap b v n m Source #
Monoid (SubMap b v n m) Source # | `SubMap`s form a monoid with the empty map as the identity, and map union as the binary operation. No information is ever lost: if two maps have the same name in their domain, the resulting map will associate that name to the concatenation of the information associated with that name.
Instance details Defined in Diagrams.Core.Types Methods mempty :: SubMap b v n m Source # mappend :: SubMap b v n m -> SubMap b v n m -> SubMap b v n m Source # mconcat :: [SubMap b v n m] -> SubMap b v n m Source #
Semigroup (SubMap b v n m) Source # |
Instance details Defined in Diagrams.Core.Types Methods (<>) :: SubMap b v n m -> SubMap b v n m -> SubMap b v n m Source # sconcat :: NonEmpty (SubMap b v n m) -> SubMap b v n m Source # stimes :: Integral b0 => b0 -> SubMap b v n m -> SubMap b v n m Source #
Wrapped (SubMap b v n m) Source # |

Instance details

Defined in Diagrams.Core.Types

Associated Types

type Unwrapped (SubMap b v n m) |
Instance details Defined in Diagrams.Core.Types type Unwrapped (SubMap b v n m) = Map Name [Subdiagram b v n m]

Methods

_Wrapped' :: Iso' (SubMap b v n m) (Unwrapped (SubMap b v n m)) Source #

Rewrapped (SubMap b v n m) (SubMap b' v' n' m') Source # |
Instance details Defined in Diagrams.Core.Types
type N (SubMap b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type N (SubMap b v n m) = n
type V (SubMap b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type V (SubMap b v n m) = v
type Unwrapped (SubMap b v n m) Source # |
Instance details Defined in Diagrams.Core.Types type Unwrapped (SubMap b v n m) = Map Name [Subdiagram b v n m]

fromNames :: forall a b (v :: Type -> Type) n m. IsName a => [(a, Subdiagram b v n m)] -> SubMap b v n m Source #

Construct a `SubMap` from a list of associations between names and subdiagrams.

rememberAs :: forall a b (v :: Type -> Type) n m. IsName a => a -> QDiagram b v n m -> SubMap b v n m -> SubMap b v n m Source #

Add a name/diagram association to a submap.

lookupSub :: forall nm b (v :: Type -> Type) n m. IsName nm => nm -> SubMap b v n m -> Maybe [Subdiagram b v n m] Source #

Look for the given name in a name map, returning a list of subdiagrams associated with that name. If no names match the given name exactly, return all the subdiagrams associated with names of which the given name is a suffix.

# Primtives

Ultimately, every diagram is essentially a tree whose leaves are primitives, basic building blocks which can be rendered by backends. However, not every backend must be able to render every type of primitive; the collection of primitives a given backend knows how to render is determined by instances of `Renderable`.

data Prim b (v :: Type -> Type) n where Source #

A value of type `Prim b v n` is an opaque (existentially quantified) primitive which backend `b` knows how to render in vector space `v`.

Constructors

Prim :: forall p b. (Transformable p, Typeable p, Renderable p b) => p -> Prim b (V p) (N p) |

#### Instances

Instances details

Transformable (Prim b v n) Source # | The `Transformable` instance for `Prim` just pushes calls to `transform` down through the `Prim` constructor.
Instance details Defined in Diagrams.Core.Types Methods transform :: Transformation (V (Prim b v n)) (N (Prim b v n)) -> Prim b v n -> Prim b v n Source #
Renderable (Prim b v n) b Source # | The `Renderable` instance for `Prim` just pushes calls to `render` down through the `Prim` constructor.
Instance details Defined in Diagrams.Core.Types Methods render :: b -> Prim b v n -> Render b (V (Prim b v n)) (N (Prim b v n)) Source #
type N (Prim b v n) Source # |
Instance details Defined in Diagrams.Core.Types type N (Prim b v n) = n
type V (Prim b v n) Source # |
Instance details Defined in Diagrams.Core.Types type V (Prim b v n) = v

_Prim :: (Typeable p, Renderable p b) => Prism' (Prim b (V p) (N p)) p Source #

# Backends

class Backend b (v :: Type -> Type) n where Source #

Abstract diagrams are rendered to particular formats by backends. Each backend/vector space combination must be an instance of the `Backend` class.

A minimal complete definition consists of `Render`, `Result`, `Options`, and `renderRTree`. However, most backends will want to implement `adjustDia` as well; the default definition does nothing. Some useful standard definitions are provided in the `Diagrams.TwoD.Adjust` module from the `diagrams-lib` package.

Minimal complete definition

renderRTree

Associated Types

data Render b (v :: Type -> Type) n Source #

An intermediate representation used for rendering primitives. (Typically, this will be some sort of monad, but it need not be.) The `Renderable` class guarantees that a backend will be able to convert primitives into this type; how these rendered primitives are combined into an ultimate `Result` is completely up to the backend.

type Result b (v :: Type -> Type) n Source #

The result of running/interpreting a rendering operation.

data Options b (v :: Type -> Type) n Source #

Backend-specific rendering options.

Methods

adjustDia :: (Additive v, Monoid' m, Num n) => b -> Options b v n -> QDiagram b v n m -> (Options b v n, Transformation v n, QDiagram b v n m) Source #

`adjustDia` allows the backend to make adjustments to the final diagram (e.g. to adjust the size based on the options) before rendering it. It returns a modified options record, the transformation applied to the diagram (which can be used to convert attributes whose value is `Measure`, or transform e.g. screen coordinates back into local diagram coordinates), and the adjusted diagram itself.

See the diagrams-lib package (particularly the `Diagrams.TwoD.Adjust` module) for some useful implementations.

renderRTree :: b -> Options b v n -> RTree b v n Annotation -> Result b v n Source #

Given some options, take a representation of a diagram as a tree and render it. The `RTree` has already been simplified and has all measurements converted to `Output` units.

#### Instances

Instances details

Backend NullBackend v n Source # |

Instance details

Defined in Diagrams.Core.Types

Associated Types

data Render NullBackend v n |
Instance details Defined in Diagrams.Core.Types data Render NullBackend v n = NullBackendRender
type Result NullBackend v n |
Instance details Defined in Diagrams.Core.Types type Result NullBackend v n = ()
data Options NullBackend v n |
Instance details Defined in Diagrams.Core.Types data Options NullBackend v n

Methods

adjustDia :: (Additive v, Monoid' m, Num n) => NullBackend -> Options NullBackend v n -> QDiagram NullBackend v n m -> (Options NullBackend v n, Transformation v n, QDiagram NullBackend v n m) Source #

renderRTree :: NullBackend -> Options NullBackend v n -> RTree NullBackend v n Annotation -> Result NullBackend v n Source #

type DTree b (v :: Type -> Type) n a = Tree (DNode b v n a) Source #

A `DTree` is a raw tree representation of a `QDiagram`, with all the `u`-annotations removed. It is used as an intermediate type by diagrams-core; backends should not need to make use of it. Instead, backends can make use of `RTree`, which `DTree` gets compiled and optimized to.

data DNode b (v :: Type -> Type) n a Source #

Constructors

DStyle (Style v n) |
DTransform (Transformation v n) |
DAnnot a |
DDelay | `DDelay` marks a point where a delayed subtree was expanded. Such subtrees already take all non-frozen transforms above them into account, so when later processing the tree, upon encountering a `DDelay` node we must drop any accumulated non-frozen transformation.
DPrim (Prim b v n) |
DEmpty |

type RTree b (v :: Type -> Type) n a = Tree (RNode b v n a) Source #

An `RTree` is a compiled and optimized representation of a `QDiagram`, which can be used by backends. They have the following invariant which backends may rely upon:

- `RPrim` nodes never have any children.

data RNode b (v :: Type -> Type) n a Source #

Constructors

RStyle (Style v n) | A style node.
RAnnot a |
RPrim (Prim b v n) | A primitive.
REmpty |

_RStyle :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p (Style v n) (f (Style v n)) -> p (RNode b v n a) (f (RNode b v n a)) Source #

Prism onto a style of an `RNode`.

_RAnnot :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p a (f a) -> p (RNode b v n a) (f (RNode b v n a)) Source #

Prism onto an annotation of an `RNode`.

_RPrim :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p (Prim b v n) (f (Prim b v n)) -> p (RNode b v n a) (f (RNode b v n a)) Source #

Prism onto a `Prim` of an `RNode`.

_REmpty :: forall b (v :: Type -> Type) n a p f. (Choice p, Applicative f) => p () (f ()) -> p (RNode b v n a) (f (RNode b v n a)) Source #

Prism onto an empty `RNode`.

## Null backend

data NullBackend Source #

A null backend which does no actual rendering. It is provided mainly for convenience in situations where you must give a diagram a concrete, monomorphic type, but don't actually care which one. See `D` for more explanation and examples.

It is courteous, when defining a new primitive `P`, to make an instance

    instance Renderable P NullBackend where
      render _ _ = mempty

This ensures that the trick with `D` annotations can be used for diagrams containing your primitive.

#### Instances

Instances details

Backend NullBackend v n Source # |

Instance details

Defined in Diagrams.Core.Types

Associated Types

data Render NullBackend v n |
Instance details Defined in Diagrams.Core.Types data Render NullBackend v n = NullBackendRender
type Result NullBackend v n |
Instance details Defined in Diagrams.Core.Types type Result NullBackend v n = ()
data Options NullBackend v n |
Instance details Defined in Diagrams.Core.Types data Options NullBackend v n

Methods

adjustDia :: (Additive v, Monoid' m, Num n) => NullBackend -> Options NullBackend v n -> QDiagram NullBackend v n m -> (Options NullBackend v n, Transformation v n, QDiagram NullBackend v n m) Source #

renderRTree :: NullBackend -> Options NullBackend v n -> RTree NullBackend v n Annotation -> Result NullBackend v n Source #

Monoid (Render NullBackend v n) Source # |
Instance details Defined in Diagrams.Core.Types Methods mempty :: Render NullBackend v n Source # mappend :: Render NullBackend v n -> Render NullBackend v n -> Render NullBackend v n Source # mconcat :: [Render NullBackend v n] -> Render NullBackend v n Source #
Semigroup (Render NullBackend v n) Source # |
Instance details Defined in Diagrams.Core.Types Methods (<>) :: Render NullBackend v n -> Render NullBackend v n -> Render NullBackend v n Source # sconcat :: NonEmpty (Render NullBackend v n) -> Render NullBackend v n Source # stimes :: Integral b => b -> Render NullBackend v n -> Render NullBackend v n Source #
data Options NullBackend v n Source # |
Instance details Defined in Diagrams.Core.Types data Options NullBackend v n
data Render NullBackend v n Source # |
Instance details Defined in Diagrams.Core.Types data Render NullBackend v n = NullBackendRender
type Result NullBackend v n Source # |
Instance details Defined in Diagrams.Core.Types type Result NullBackend v n = ()

type D (v :: Type -> Type) n = QDiagram NullBackend v n Any Source #

The `D` type is provided for convenience in situations where you must give a diagram a concrete, monomorphic type, but don't care which one. Such situations arise when you pass a diagram to a function which is polymorphic in its input but monomorphic in its output, such as `width`, `height`, `phantom`, or `names`. Such functions compute some property of the diagram, or use it to accomplish some other purpose, but do not result in the diagram being rendered. If the diagram does not have a monomorphic type, GHC complains that it cannot determine the diagram's type.

For example, here is the error we get if we try to compute the width of an image (this example requires `diagrams-lib`):

      ghci> width (image (uncheckedImageRef "foo.png" 200 200))
      <interactive>:11:8:
          No instance for (Renderable (DImage n0 External) b0)
            arising from a use of image
          The type variables n0, b0 are ambiguous
          Possible fix: add a type signature that fixes these type variable(s)
          Note: there is a potential instance available:
            instance Fractional n => Renderable (DImage n a) NullBackend
              -- Defined in Image
          Possible fix:
            add an instance declaration for
            (Renderable (DImage n0 External) b0)
          In the first argument of width, namely
            `(image (uncheckedImageRef "foo.png" 200 200))'
          In the expression:
            width (image (uncheckedImageRef "foo.png" 200 200))
          In an equation for it:
              it = width (image (uncheckedImageRef "foo.png" 200 200))

GHC complains that there is no instance for `Renderable (DImage n0 External) b0`; what is really going on is that it does not have enough information to decide what backend to use (hence the uninstantiated `n0` and `b0`). This is annoying because we know that the choice of backend cannot possibly affect the width of the image (it's 200! it's right there in the code!); but there is no way for GHC to know that.

The solution is to annotate the call to `image` with the type ``D` `V2` `Double``, like so:

      ghci> width (image (uncheckedImageRef "foo.png" 200 200) :: D V2 Double)
      200.00000000000006

(It turns out the width wasn't 200 after all...)

As another example, here is the error we get if we try to compute the width of a radius-1 circle:

      ghci> width (circle 1)
      <interactive>:12:1:
          Couldn't match expected type V2 with actual type `V a0'
          The type variable a0 is ambiguous
          Possible fix: add a type signature that fixes these type variable(s)
          In the expression: width (circle 1)
          In an equation for it: it = width (circle 1)

There's even more ambiguity here. Whereas `image` always returns a `Diagram`, the `circle` function can produce any `TrailLike` type, and the `width` function can consume any `Enveloped` type, so GHC has no idea what type to pick to go in the middle. However, the solution is the same:

      ghci> width (circle 1 :: D V2 Double)
      1.9999999999999998

## Number classes

type TypeableFloat n = (Typeable n, RealFloat n) Source #

Constraint for numeric types that are `RealFloat` and `Typeable`, which often occur together. This is used to shorten shorten type constraint contexts.

# Renderable

class Transformable t => Renderable t b where Source #

The Renderable type class connects backends to primitives which they know how to render.

Methods

render :: b -> t -> Render b (V t) (N t) Source #

Given a token representing the backend and a transformable object, render it in the appropriate rendering context.

#### Instances

Instances details

Renderable (Prim b v n) b Source # | The `Renderable` instance for `Prim` just pushes calls to `render` down through the `Prim` constructor.
Instance details Defined in Diagrams.Core.Types Methods render :: b -> Prim b v n -> Render b (V (Prim b v n)) (N (Prim b v n)) Source #

# Orphan instances

Action Name a => Action Name (Deletable a) Source # |
Instance details Methods act :: Name -> Deletable a -> Deletable a Source #
Action Name (Envelope v n) Source # |
Instance details Methods act :: Name -> Envelope v n -> Envelope v n Source #
Action Name (Trace v n) Source # |
Instance details Methods act :: Name -> Trace v n -> Trace v n Source #
Action Name (Query v n m) Source # |
Instance details Methods act :: Name -> Query v n m -> Query v n m Source #