diff --git a/CHANGES.markdown b/CHANGES.markdown --- a/CHANGES.markdown +++ b/CHANGES.markdown @@ -1,3 +1,8 @@ +1.2.0.2 (22 August 2014) +------------------------ + +- Allow lens-4.4 + 1.2.0.1 (4 June 2014) --------------------- diff --git a/diagrams-core.cabal b/diagrams-core.cabal --- a/diagrams-core.cabal +++ b/diagrams-core.cabal @@ -1,5 +1,5 @@ Name: diagrams-core -Version: 1.2.0.1 +Version: 1.2.0.2 Synopsis: Core libraries for diagrams EDSL Description: The core modules underlying diagrams, an embedded domain-specific language @@ -44,7 +44,7 @@ newtype >= 0.2 && < 0.3, monoid-extras >= 0.3 && < 0.4, dual-tree >= 0.2 && < 0.3, - lens >= 4.0 && < 4.3 + lens >= 4.0 && < 4.5 hs-source-dirs: src Other-extensions: DeriveDataTypeable diff --git a/src/Diagrams/Core.hs b/src/Diagrams/Core.hs --- a/src/Diagrams/Core.hs +++ b/src/Diagrams/Core.hs @@ -19,6 +19,74 @@ -- occasionally find it useful to directly import one of the -- constituent core modules. -- +-- The diagrams library relies heavily on custom types and classes. Many +-- of the relevant definitions are in the "Diagrams.Core.Types" module. +-- Indeed the definition of the diagram type @QDiagram@ is contained in: +-- 'Diagrams.Core.Types.QDiagram'. +-- +-- The best place to start when learning +-- about diagrams\' types is the user manual: +-- +-- The following list shows which types are contained in each module of +-- "Diagrams.Core". +-- +-- * "Diagrams.Core.Types" +-- +-- * @Annotation@, +-- * @UpAnnots b v m@, @DownAnnots v@, +-- * @QDiaLeaf b v m@, @Measure v@, +-- * @Subdiagram b v m@, @SubMap b v m@, +-- * @Prim b v@, @Backend b v@, +-- * @DNode b v a@, @DTree b v a@, +-- * @RNode b v a@, @RTree b v a@, +-- * @NullBackend@, @Renderable t b@, +-- * @D v@. +-- +-- * "Diagrams.Core.Envelope" +-- +-- * @Envelope v@, @Enveloped v@, +-- * @OrderedField s@. +-- +-- * "Diagrams.Core.Juxtapose" +-- +-- * @Juxtaposable a@. +-- +-- * "Diagrams.Core.Names" +-- +-- * @AName@, @Name@, @IsName a@, +-- * @Qualifiable q@. +-- +-- * "Diagrams.Core.HasOrigin" +-- +-- * @HasOrigin t@. +-- +-- * "Diagrams.Core.Points" +-- +-- * @Point v@. +-- +-- * "Diagrams.Core.Query" +-- +-- * @Query v m@. +-- +-- * "Diagrams.Core.Style" +-- +-- * @AttributeClass a@, @Attribute v@, +-- * @Style v@, @HasStyle@. +-- +-- * "Diagrams.Core.Trace" +-- +-- * @SortedList a@, +-- * @Trace v@, @Traced a@. +-- +-- * "Diagrams.Core.Transform" +-- +-- * @u :-: v@, @HasLinearMap@, +-- * @Transformation v@, @Transformable t@, +-- * @TransInv t@. +-- +-- * "Diagrams.Core.V" +-- +-- * @V a@. ----------------------------------------------------------------------------- module Diagrams.Core diff --git a/src/Diagrams/Core/Names.hs b/src/Diagrams/Core/Names.hs --- a/src/Diagrams/Core/Names.hs +++ b/src/Diagrams/Core/Names.hs @@ -49,6 +49,26 @@ -- 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 +-- @ class (Typeable a, Ord a, Show a) => IsName a where toName :: a -> Name toName = Name . (:[]) . AName diff --git a/src/Diagrams/Core/Types.hs b/src/Diagrams/Core/Types.hs --- a/src/Diagrams/Core/Types.hs +++ b/src/Diagrams/Core/Types.hs @@ -345,11 +345,33 @@ href :: (HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Semigroup m) => String -> QDiagram b v m -> QDiagram b v m href = applyAnnotation . Href --- | The fundamental diagram type is represented by trees of --- primitives with various monoidal annotations. The @Q@ in --- @QDiagram@ stands for \"Queriable\", as distinguished from --- 'Diagram', a synonym for @QDiagram@ with the query type --- specialized to 'Any'. +-- | 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 @R2@ (for a two-dimensional diagram) or +-- @R3@ (for a three-dimensional diagram). +-- +-- * @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. newtype QDiagram b v m = QD (D.DUALTree (DownAnnots v) (UpAnnots b v m) Annotation (QDiaLeaf b v m)) deriving (Typeable) @@ -363,7 +385,8 @@ type instance V (QDiagram b v m) = v --- | The default sort of diagram is one where querying at a point +-- | @Diagram b v@ is a synonym for @'QDiagram' b v '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@ or