diagrams-lib-1.4.6: Embedded domain-specific language for declarative graphics

Copyright | (c) 2013 diagrams-lib team (see LICENSE)
License | BSD-style (see LICENSE)
Maintainer | diagrams-discuss@googlegroups.com
Safe Haskell | Safe-Inferred
Language | Haskell2010

Diagrams.Names

Contents

- Names
- Subdiagrams
- Subdiagram maps
- Naming things
- Querying by name

Description

Names can be given to subdiagrams, and subdiagrams can later be queried by name. This module exports types for representing names and subdiagrams, and various functions for working with them.

Synopsis

- data AName
- data Name
- class (Typeable a, Ord a, Show a) => IsName a where
  - toName :: a -> Name
- (.>) :: (IsName a1, IsName a2) => a1 -> a2 -> Name
- class Qualifiable q where
  - (.>>) :: IsName a => a -> q -> q
- data Subdiagram b (v :: Type -> Type) n m
- mkSubdiagram :: forall b (v :: Type -> Type) n m. QDiagram b v n m -> Subdiagram b v n m
- subPoint :: forall (v :: Type -> Type) n b m. (Metric v, OrderedField n) => Point v n -> 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
- data SubMap b (v :: Type -> Type) 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]
- named :: (IsName nm, Metric v, OrderedField n, Semigroup m) => nm -> 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
- namePoint :: (IsName nm, Metric v, OrderedField n, Semigroup m) => (QDiagram b v n m -> Point v n) -> nm -> 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
- names :: forall (v :: Type -> Type) m n b. (Metric v, Semigroup m, OrderedField n) => QDiagram b v n m -> [(Name, [Point v n])]
- 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

# Names

data AName Source #

Atomic names. `AName` is just an existential wrapper around things which are `Typeable`, `Ord` and `Show`.

#### Instances

Instances details

Show AName |
Instance details Defined in Diagrams.Core.Names Methods showsPrec :: Int -> AName -> ShowS Source # show :: AName -> String Source # showList :: [AName] -> ShowS Source #
IsName AName |
Instance details Defined in Diagrams.Core.Names Methods toName :: AName -> Name Source #
Eq AName |
Instance details Defined in Diagrams.Core.Names Methods (==) :: AName -> AName -> Bool Source # (/=) :: AName -> AName -> Bool Source #
Ord AName |
Instance details Defined in Diagrams.Core.Names Methods compare :: AName -> AName -> Ordering Source # (<) :: AName -> AName -> Bool Source # (<=) :: AName -> AName -> Bool Source # (>) :: AName -> AName -> Bool Source # (>=) :: AName -> AName -> Bool Source # max :: AName -> AName -> AName Source # min :: AName -> AName -> AName Source #
Each Name Name AName AName |
Instance details Defined in Diagrams.Core.Names Methods each :: Traversal Name Name AName AName Source #

data Name Source #

A (qualified) name is a (possibly empty) sequence of atomic names.

#### Instances

Instances details

Monoid Name |
Instance details Defined in Diagrams.Core.Names Methods mempty :: Name Source # mappend :: Name -> Name -> Name Source # mconcat :: [Name] -> Name Source #
Semigroup Name |
Instance details Defined in Diagrams.Core.Names Methods (<>) :: Name -> Name -> Name Source # sconcat :: NonEmpty Name -> Name Source # stimes :: Integral b => b -> Name -> Name Source #
Show Name |
Instance details Defined in Diagrams.Core.Names Methods showsPrec :: Int -> Name -> ShowS Source # show :: Name -> String Source # showList :: [Name] -> ShowS Source #
IsName Name |
Instance details Defined in Diagrams.Core.Names Methods toName :: Name -> Name Source #
Qualifiable Name | Of course, names can be qualified using `(.>)`.
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a => a -> Name -> Name Source #
Eq Name |
Instance details Defined in Diagrams.Core.Names Methods (==) :: Name -> Name -> Bool Source # (/=) :: Name -> Name -> Bool Source #
Ord Name |
Instance details Defined in Diagrams.Core.Names Methods compare :: Name -> Name -> Ordering Source # (<) :: Name -> Name -> Bool Source # (<=) :: Name -> Name -> Bool Source # (>) :: Name -> Name -> Bool Source # (>=) :: Name -> Name -> Bool Source # max :: Name -> Name -> Name Source # min :: Name -> Name -> Name Source #
Wrapped Name |
Instance details Defined in Diagrams.Core.Names Associated Types type Unwrapped Name Source # Methods _Wrapped' :: Iso' Name (Unwrapped Name) Source #
Rewrapped Name Name |
Instance details Defined in Diagrams.Core.Names
Each Name Name AName AName |
Instance details Defined in Diagrams.Core.Names Methods each :: Traversal Name Name AName AName Source #
Action Name (SubMap b v n m) | 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 #
type Unwrapped Name |
Instance details Defined in Diagrams.Core.Names type Unwrapped Name = [AName]

class (Typeable a, Ord a, Show a) => IsName a where Source #

Class for those types which can be used as names. They must support `Typeable` (to facilitate extracting them from existential wrappers), `Ord` (for comparison and efficient storage) and `Show`.

To make an instance of `IsName`, you need not define any methods, just declare it.

WARNING: it is not recommended to use `GeneralizedNewtypeDeriving` in conjunction with `IsName`, since in that case the underlying type and the `newtype` will be considered equivalent when comparing names. For example:

        newtype WordN = WordN Int deriving (Show, Ord, Eq, Typeable, IsName)

is unlikely to work as intended, since `(1 :: Int)` and `(WordN 1)` will be considered equal as names. Instead, use

        newtype WordN = WordN Int deriving (Show, Ord, Eq, Typeable, IsName)
        instance IsName WordN

Minimal complete definition

Nothing

Methods

toName :: a -> Name Source #

#### Instances

Instances details

IsName AName |
Instance details Defined in Diagrams.Core.Names Methods toName :: AName -> Name Source #
IsName Name |
Instance details Defined in Diagrams.Core.Names Methods toName :: Name -> Name Source #
IsName Integer |
Instance details Defined in Diagrams.Core.Names Methods toName :: Integer -> Name Source #
IsName () |
Instance details Defined in Diagrams.Core.Names Methods toName :: () -> Name Source #
IsName Bool |
Instance details Defined in Diagrams.Core.Names Methods toName :: Bool -> Name Source #
IsName Char |
Instance details Defined in Diagrams.Core.Names Methods toName :: Char -> Name Source #
IsName Double |
Instance details Defined in Diagrams.Core.Names Methods toName :: Double -> Name Source #
IsName Float |
Instance details Defined in Diagrams.Core.Names Methods toName :: Float -> Name Source #
IsName Int |
Instance details Defined in Diagrams.Core.Names Methods toName :: Int -> Name Source #
IsName a => IsName (Maybe a) |
Instance details Defined in Diagrams.Core.Names Methods toName :: Maybe a -> Name Source #
IsName a => IsName [a] |
Instance details Defined in Diagrams.Core.Names Methods toName :: [a] -> Name Source #
(IsName a, IsName b) => IsName (a, b) |
Instance details Defined in Diagrams.Core.Names Methods toName :: (a, b) -> Name Source #
(IsName a, IsName b, IsName c) => IsName (a, b, c) |
Instance details Defined in Diagrams.Core.Names Methods toName :: (a, b, c) -> Name Source #

(.>) :: (IsName a1, IsName a2) => a1 -> a2 -> Name infixr 5 Source #

Convenient operator for writing qualified names with atomic components of different types. Instead of writing `toName a1 <> toName a2 <> toName a3` you can just write `a1 .> a2 .> a3`.

class Qualifiable q where Source #

Instances of `Qualifiable` are things which can be qualified by prefixing them with a name.

Methods

(.>>) :: IsName a => a -> q -> q infixr 5 Source #

Qualify with the given name.

#### Instances

Instances details

Qualifiable Name | Of course, names can be qualified using `(.>)`.
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a => a -> Name -> Name Source #
(Ord a, Qualifiable a) => Qualifiable (Set a) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> Set a -> Set a Source #
Qualifiable a => Qualifiable (TransInv a) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> TransInv a -> TransInv a Source #
Qualifiable a => Qualifiable (Located a) Source # |
Instance details Defined in Diagrams.Located Methods (.>>) :: IsName a0 => a0 -> Located a -> Located a Source #
Qualifiable a => Qualifiable [a] |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> [a] -> [a] Source #
Qualifiable a => Qualifiable (Map k a) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> Map k a -> Map k a Source #
Qualifiable a => Qualifiable (Measured n a) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> Measured n a -> Measured n a Source #
Qualifiable a => Qualifiable (b -> a) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> (b -> a) -> b -> a Source #
(Qualifiable a, Qualifiable b) => Qualifiable (a, b) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> (a, b) -> (a, b) Source #
(Qualifiable a, Qualifiable b, Qualifiable c) => Qualifiable (a, b, c) |
Instance details Defined in Diagrams.Core.Names Methods (.>>) :: IsName a0 => a0 -> (a, b, c) -> (a, b, c) Source #
(Metric v, OrderedField n, Semigroup m) => Qualifiable (QDiagram b v n m) | 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 #
Qualifiable (SubMap b v n m) | `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 #

# 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.).

#### Instances

Instances details

Functor (Subdiagram b v n) |
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) |
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) |
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) |
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) |
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) |
Instance details Defined in Diagrams.Core.Types type N (Subdiagram b v n m) = n
type V (Subdiagram b v n m) |
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.

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.

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".

# Subdiagram maps

data 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.

#### Instances

Instances details

Action Name (SubMap b v n m) | 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) |
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 #
Monoid (SubMap b v n m) | `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) |
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 #
(OrderedField n, Metric v) => HasOrigin (SubMap b v n m) |
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) | `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) |
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 #
Wrapped (SubMap b v n m) |
Instance details Defined in Diagrams.Core.Types Associated Types type Unwrapped (SubMap b v n m) Source # 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') |
Instance details Defined in Diagrams.Core.Types
type N (SubMap b v n m) |
Instance details Defined in Diagrams.Core.Types type N (SubMap b v n m) = n
type V (SubMap b v n m) |
Instance details Defined in Diagrams.Core.Types type V (SubMap b v n m) = v
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]

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.

# Naming things

named :: (IsName nm, Metric v, OrderedField n, Semigroup m) => nm -> QDiagram b v n m -> QDiagram b v n m Source #

Attach an atomic name to a diagram.

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`).

namePoint :: (IsName nm, Metric v, OrderedField n, Semigroup m) => (QDiagram b v n m -> Point v n) -> nm -> QDiagram b v n m -> QDiagram b v n m Source #

Attach an atomic name to a certain point (which may be computed from the given diagram), treated as a subdiagram with no content and a point envelope.

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.

# Querying by name

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.

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.