Merge pull request #241 from diagrams/pre-1.3

Pre 1.3 - Mostly Lenses

diagrams-lib.cabal

@@ -25,7 +25,8 @@ Source-repository head
   location: http://github.com/diagrams/diagrams-lib.git
 
 Library
-  Exposed-modules:     Diagrams.Prelude,
+  Exposed-modules:     Diagrams,
+                       Diagrams.Prelude,
                        Diagrams.Align,
                        Diagrams.Angle,
                        Diagrams.Animation,
@@ -109,7 +110,7 @@ Library
                        data-default-class < 0.1,
                        fingertree >= 0.1 && < 0.2,
                        intervals >= 0.7 && < 0.8,
-                       lens >= 4.0 && < 4.8,
+                       lens >= 4.6 && < 4.9,
                        tagged >= 0.7,
                        optparse-applicative >= 0.11 && < 0.12,
                        filepath,

src/Diagrams.hs

@@ -0,0 +1,150 @@
+{-# OPTIONS_GHC -fno-warn-duplicate-exports #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module      :  Diagrams
+-- Copyright   :  (c) 2015 diagrams-lib team (see LICENSE)
+-- License     :  BSD-style (see LICENSE)
+-- Maintainer  :  diagrams-discuss@googlegroups.com
+--
+-- This module only contains exports defined in "diagrams-lib" or
+-- "diagrams-core". This module is less likely conflict with any
+-- other modules but importing "Diagrams.Prelude" is often more convenient.
+--
+-----------------------------------------------------------------------------
+
+module Diagrams
+  (
+    -- * Core library
+    -- | The core definitions of transformations, diagrams,
+    --   backends, and so on.
+    module Diagrams.Core
+
+    -- * Standard library
+
+    -- | Attributes (color, line style, etc.) and styles.
+  , module Diagrams.Attributes
+
+    -- | Alignment of diagrams relative to their envelopes.
+  , module Diagrams.Align
+
+    -- | Creating and using bounding boxes.
+  , module Diagrams.BoundingBox
+
+    -- | Combining multiple diagrams into one.
+  , module Diagrams.Combinators
+
+    -- | Giving concrete locations to translation-invariant things.
+  , module Diagrams.Located
+
+    -- | Linear and cubic bezier segments.
+  , module Diagrams.Segment
+
+    -- | Trails.
+  , module Diagrams.Trail
+
+    -- | Parametrization of segments and trails.
+  , module Diagrams.Parametric
+
+    -- | Adjusting the length of parameterized objects.
+  , module Diagrams.Parametric.Adjust
+
+    -- | Computing tangent and normal vectors of segments and
+    --   trails.
+  , module Diagrams.Tangent
+
+    -- | Trail-like things.
+  , module Diagrams.TrailLike
+
+    -- | Paths.
+  , module Diagrams.Path
+
+    -- | Cubic splines.
+  , module Diagrams.CubicSpline
+
+    -- | Some additional transformation-related functions, like
+    --   conjugation of transformations.
+  , module Diagrams.Transform
+
+    -- | Projective transformations and other deformations
+    -- lacking an inverse.
+  , module Diagrams.Deform
+
+    -- | Giving names to subdiagrams and later retrieving
+    --   subdiagrams by name.
+  , module Diagrams.Names
+
+    -- | Envelopes, aka functional bounding regions.
+  , module Diagrams.Envelope
+
+    -- | Traces, aka embedded raytracers, for finding points on
+    --   the boundary of a diagram.
+  , module Diagrams.Trace
+
+    -- | A query is a function that maps points in a vector space
+    --   to values in some monoid; they can be used to annotate
+    --   the points of a diagram with some values.
+  , module Diagrams.Query
+
+    -- | Utilities for working with points.
+  , module Diagrams.Points
+
+    -- | Utilities for working with size.
+  , module Diagrams.Size
+
+    -- | Angles
+  , module Diagrams.Angle
+
+    -- | Convenience infix operators for working with coordinates.
+  , module Diagrams.Coordinates
+
+    -- | Directions, distinguished from angles or vectors
+  , module Diagrams.Direction
+
+    -- | A wide range of things (shapes, transformations,
+    --   combinators) specific to creating two-dimensional
+    --   diagrams.
+  , module Diagrams.TwoD
+
+    -- | Extra things for three-dimensional diagrams.
+  , module Diagrams.ThreeD
+
+    -- | Tools for making animations.
+  , module Diagrams.Animation
+
+    -- | Various utility definitions.
+  , module Diagrams.Util
+
+  ) where
+
+import           Diagrams.Core
+
+import           Diagrams.Align
+import           Diagrams.Angle
+import           Diagrams.Animation
+import           Diagrams.Attributes
+import           Diagrams.BoundingBox       hiding (intersection, union, inside, outside, contains)
+import           Diagrams.Combinators
+import           Diagrams.Coordinates
+import           Diagrams.CubicSpline
+import           Diagrams.Deform
+import           Diagrams.Direction         hiding (dir)
+import           Diagrams.Envelope
+import           Diagrams.Located
+import           Diagrams.Names
+import           Diagrams.Parametric
+import           Diagrams.Parametric.Adjust
+import           Diagrams.Path
+import           Diagrams.Points
+import           Diagrams.Query
+import           Diagrams.Segment
+import           Diagrams.Size
+import           Diagrams.Tangent
+import           Diagrams.ThreeD
+import           Diagrams.Trace
+import           Diagrams.Trail             hiding (linePoints, loopPoints,
+                                             trailPoints)
+import           Diagrams.TrailLike
+import           Diagrams.Transform
+import           Diagrams.TwoD
+import           Diagrams.Util
+

src/Diagrams/Angle.hs

@@ -36,10 +36,11 @@ module Diagrams.Angle
        ) where
 
 import           Control.Applicative
-import           Control.Lens        (Iso', Lens', iso, over, review, (^.))
+import           Control.Lens        (AReview, Iso', Lens', iso, over, review, (^.))
 import           Data.Fixed
 import           Data.Monoid         hiding ((<>))
 import           Data.Semigroup
+import           Text.Read
 import           Prelude
 
 import           Diagrams.Core       (OrderedField)
@@ -52,7 +53,18 @@ import           Linear.Vector
 -- | Angles can be expressed in a variety of units.  Internally,
 --   they are represented in radians.
 newtype Angle n = Radians n
-  deriving (Read, Show, Eq, Ord, Enum, Functor)
+  deriving (Eq, Ord, Enum, Functor)
+
+instance Show n => Show (Angle n) where
+  showsPrec d (Radians a) = showParen (d > 5) $
+    showsPrec 6 a . showString " @@ rad"
+
+instance Read n => Read (Angle n) where
+  readPrec = parens . prec 5 $ do
+    x <- readPrec
+    Symbol "@@" <- lexP
+    Ident "rad" <- lexP
+    pure (Radians x)
 
 type instance N (Angle n) = n
 
@@ -74,21 +86,22 @@ instance Num n => Monoid (Angle n) where
   mappend = (<>)
   mempty  = Radians 0
 
--- | The radian measure of an @Angle@ @a@ can be accessed as @a
---   ^. rad@.  A new @Angle@ can be defined in radians as @pi \@\@ rad@.
+-- | The radian measure of an 'Angle' @a@ can be accessed as @a '^.'
+--   rad@. A new 'Angle' can be defined in radians as @pi \@\@
+--   rad@.
 rad :: Iso' (Angle n) n
 rad = iso (\(Radians r) -> r) Radians
 {-# INLINE rad #-}
 
--- | The measure of an @Angle@ @a@ in full circles can be accessed as
---   @a ^. turn@.  A new @Angle@ of one-half circle can be defined in as
+-- | The measure of an 'Angle' @a@ in full circles can be accessed as
+--   @a '^.' turn@.  A new 'Angle' of one-half circle can be defined in as
 --   @1/2 \@\@ turn@.
 turn :: Floating n => Iso' (Angle n) n
 turn = iso (\(Radians r) -> r / (2*pi)) (Radians . (*(2*pi)))
 {-# INLINE turn #-}
 
--- | The degree measure of an @Angle@ @a@ can be accessed as @a
---   ^. deg@.  A new @Angle@ can be defined in degrees as @180 \@\@
+-- | The degree measure of an 'Angle' @a@ can be accessed as @a
+--   '^.' deg@. A new 'Angle' can be defined in degrees as @180 \@\@
 --   deg@.
 deg :: Floating n => Iso' (Angle n) n
 deg = iso (\(Radians r) -> r / (2*pi/360)) (Radians . ( * (2*pi/360)))
@@ -141,7 +154,7 @@ atan2A y x = Radians $ atan2 y x
 
 -- | Similar to 'atan2A' but without the 'RealFloat' constraint. This means it
 --   doesn't handle negative zero cases. However, for most geometric purposes,
---   outcome will be the same.
+--   the outcome will be the same.
 atan2A' :: OrderedField n => n -> n -> Angle n
 atan2A' y x = atan2' y x @@ rad
 
@@ -156,13 +169,30 @@ atan2' y x
   | x==0 && y==0     =  y     -- must be after the other double zero tests
   | otherwise        =  x + y -- x or y is a NaN, return a NaN (via +)
 
--- | @30 \@\@ deg@ is an @Angle@ of the given measure and units.
+-- | @30 \@\@ deg@ is an 'Angle' of the given measure and units.
+--
+-- >>> pi @@ rad
+-- 3.141592653589793 @@ rad
+--
+-- >>> 1 @@ turn
+-- 6.283185307179586 @@ rad
+--
+-- >>> 30 @@ deg
+-- 0.5235987755982988 @@ rad
+--
+--   For 'Iso''s, ('@@') reverses the 'Iso'' on its right, and applies
+--   the 'Iso'' to the value on the left. 'Angle's are the motivating
+--   example where this order improves readability.
+--
+--   This is the same as a flipped 'review'.
 --
---   More generally, @\@\@@ reverses the @Iso\'@ on its right, and
---   applies the @Iso\'@ to the value on the left.  @Angle@s are the
---   motivating example where this order improves readability.
-(@@) :: b -> Iso' a b -> a
--- The signature above is slightly specialized, in favor of readability
+-- @
+-- ('@@') :: a -> 'Iso''      s a -> s
+-- ('@@') :: a -> 'Prism''    s a -> s
+-- ('@@') :: a -> 'Review'    s a -> s
+-- ('@@') :: a -> 'Equality'' s a -> s
+-- @
+(@@) :: b -> AReview a b -> a
 a @@ i = review i a
 
 infixl 5 @@
@@ -180,12 +210,12 @@ normalizeAngle = over rad (`mod'` (2 * pi))
 ------------------------------------------------------------
 -- Polar Coordinates
 
--- | The class of types with at least one angle coordinate, called _theta.
+-- | The class of types with at least one angle coordinate, called '_theta'.
 class HasTheta t where
   _theta :: RealFloat n => Lens' (t n) (Angle n)
 
 -- | The class of types with at least two angle coordinates, the second called
---   _phi. _phi is the positive angle measured from the z axis.
+--   '_phi'. '_phi' is the positive angle measured from the z axis.
 class HasTheta t => HasPhi t where
   _phi :: RealFloat n => Lens' (t n) (Angle n)