Personal tools

Diagrams/Dev/Migrate0.6

From HaskellWiki

< Diagrams | Dev(Difference between revisions)
Jump to: navigation, search
(add note re: removal of StyleParam)
 
(Subdiagrams: write a bit more about subdiagram changes)
(2 intermediate revisions by one user not shown)
Line 1: Line 1:
This page describes API changes between diagrams 0.5 and 0.6, along with explanations of how to migrate to the new 0.6 API.
+
This page describes breaking API changes between diagrams 0.5 and 0.6, along with explanations of how to migrate to the new 0.6 API.
  +
  +
== Reorganizations to diagrams-core ==
  +
  +
* The modules in diagrams-core have all been renamed to be more consistent with the module naming scheme in the rest of the diagrams universe. For most users this should make no different, unless you are affected by [https://github.com/diagrams/diagrams-core/issues/17 diagrams-core#17] and have explicitly imported <code>Graphics.Rendering.Diagrams.Points</code>. In particular:
  +
** <code>Graphics.Rendering.Diagrams --> Diagrams.Core</code>
  +
** <code>Grahpics.Rendering.Diagrams.Core --> Diagrams.Core.Types</code>
  +
** <code>Graphics.Rendering.Diagrams.* --> Diagrams.Core.*</code>
  +
  +
== Subdiagrams ==
  +
  +
Previous versions of diagrams-core had a mechanism for associating names with a <code>LocatedEnvelope</code>. Now, names are associated with <code>Subdiagram</code>s. For example, the type of <code>withName</code> changed from
  +
  +
<pre>
  +
withName ::
  +
(IsName n,
  +
AdditiveGroup (Scalar v), Floating (Scalar v), InnerSpace v, HasLinearMap v)
  +
=>
  +
n -> (LocatedEnvelope v -> QDiagram b v m -> QDiagram b v m)
  +
-> QDiagram b v m -> QDiagram b v m
  +
</pre>
  +
  +
to
  +
  +
<pre>
  +
withName ::
  +
IsName n
  +
=>
  +
n -> (Subdiagram b v m -> QDiagram b v m -> QDiagram b v m)
  +
-> QDiagram b v m -> QDiagram b v m
  +
</pre>
  +
  +
(As you can see, some type class constraints also disappeared, due to the refactoring of the underlying data structure.)
  +
  +
The types of <code>withNameAll</code> and <code>withNames</code> changed similarly.
  +
  +
TODO: write more here
  +
  +
== Other diagrams-core API changes ==
  +
  +
TODO: write me
  +
  +
- 'Graphics.Rendering.Diagrams.UDTree' has been split out into a
  +
separate 'dual-tree' package (which has also been substantially
  +
rewritten).
  +
  +
- 'Graphics.Rendering.Diagrams.{Monoids,MList}' have been split
  +
out into a separate 'monoid-extras' package.
  +
  +
- The 'names' function now returns a list of names and their
  +
associated locations, instead of the associated subdiagrams. In
  +
particular the output is suitable to be rendered to a String
  +
using 'show'.
  +
  +
- The new 'subMap' function fills a similar role that 'names' used
  +
to play, returning the entire mapping from names to subdiagrams.
  +
  +
- 'juxtaposeDefault' is now the identity on the second object if
  +
either one has an empty envelope. In particular this means that
  +
'mempty' is now an identity element for 'beside' and friends.
  +
   
 
== StyleParam deleted from Diagrams.Backend.Cairo.Text ==
 
== StyleParam deleted from Diagrams.Backend.Cairo.Text ==

Revision as of 01:53, 22 October 2012

This page describes breaking API changes between diagrams 0.5 and 0.6, along with explanations of how to migrate to the new 0.6 API.

Contents

1 Reorganizations to diagrams-core

  • The modules in diagrams-core have all been renamed to be more consistent with the module naming scheme in the rest of the diagrams universe. For most users this should make no different, unless you are affected by diagrams-core#17 and have explicitly imported Graphics.Rendering.Diagrams.Points. In particular:
    • Graphics.Rendering.Diagrams --> Diagrams.Core
    • Grahpics.Rendering.Diagrams.Core --> Diagrams.Core.Types
    • Graphics.Rendering.Diagrams.* --> Diagrams.Core.*

2 Subdiagrams

Previous versions of diagrams-core had a mechanism for associating names with a LocatedEnvelope. Now, names are associated with Subdiagrams. For example, the type of withName changed from

withName :: 
  (IsName n, 
   AdditiveGroup (Scalar v), Floating (Scalar v), InnerSpace v, HasLinearMap v)
  => 
  n -> (LocatedEnvelope v -> QDiagram b v m -> QDiagram b v m) 
    -> QDiagram b v m -> QDiagram b v m

to

withName :: 
  IsName n 
  => 
  n -> (Subdiagram b v m -> QDiagram b v m -> QDiagram b v m) 
    -> QDiagram b v m -> QDiagram b v m

(As you can see, some type class constraints also disappeared, due to the refactoring of the underlying data structure.)

The types of withNameAll and withNames changed similarly.

TODO: write more here

3 Other diagrams-core API changes

TODO: write me

   - 'Graphics.Rendering.Diagrams.UDTree' has been split out into a
     separate 'dual-tree' package (which has also been substantially
     rewritten).
   - 'Graphics.Rendering.Diagrams.{Monoids,MList}' have been split
     out into a separate 'monoid-extras' package.
   - The 'names' function now returns a list of names and their
     associated locations, instead of the associated subdiagrams.  In
     particular the output is suitable to be rendered to a String
     using 'show'.
   - The new 'subMap' function fills a similar role that 'names' used
     to play, returning the entire mapping from names to subdiagrams.
   - 'juxtaposeDefault' is now the identity on the second object if
     either one has an empty envelope.  In particular this means that
     'mempty' is now an identity element for 'beside' and friends.


4 StyleParam deleted from Diagrams.Backend.Cairo.Text

The StyleParam type has been removed from Diagrams.Backend.Cairo.Text. Functions that used to take a StyleParam argument now take a Style R2 parameter, determining the style to apply to the text before rendering/querying information about the text. These parameters can be created a variety of ways, but the most direct will likely be by applying style-transforming functions such as font, fontSize, fontSlant, and fontWeight to mempty. This works because there are instances of HasStyle and Monoid for Style v.