references-0.3.0.0: references.cabal

name:                references
version:             0.3.0.0
synopsis:            Generalization of lenses, folds and traversals to handle monads and addition.

description:         References are data accessors that can read, write or update the accessed infromation through their context. They are first-class values, can be passed in functions, transformed, combined. References generalize lenses, folds and traversals for haskell (see: < https://hackage.haskell.org/package/lens>).
		     .
             References are more general than field selectors in traditional languages.
             .
              * References are first-class values. If there is a struct in C, for example, with an `int` field `fl`, then fl can only be used as part of an expression. One can not generalize a function to take a field selector and transform the selected data or use it in other ways.
             .
              * They can have different meanings, while field accessors can only represent data-level containment. They can express uncertain containment (like field selectors of C unions), different viewpoints of the same data, and other concepts.
             .              
		     There are two things that references can do but the previously mentioned access methods don't.
		     .
		      * References can cooperate with monads, for example IO. This opens many new applications.
             .
		      * References can be added using the @&+&@ operator, to create new lenses more easily.
		     .
		     Basic idea taken from the currently not maintained package <https://hackage.haskell.org/package/yall>. 
		     .
		     An example use of the references (a logger application that spawns new threads to update a global log):
		     .
		     > logger =
		     >   (forever $ do
		     >      log <- logChan ^? chan&logRecord    -- Extract the log record from the received log message
		     >      thrId <- forkIO (do time <- getTime
		     >                          ioref&lastLogTime != time $ logDB     -- Update the last logging time mutable log database
		     >                          let logMsg = senderThread .- show     -- Transform the thread id to a string and
		     >                                         $ loggingTime .= time  -- update the time
		     >                                         $ log                  -- inside the log message
		     >                          ioref&debugInfos !~ addLogEntry log $ logDB  -- update the table of log entries
		     >                          mvar !- (+1) $ count )
		     >      mvar !- (thrId:) $ updaters                               -- Record the spawned thread
		     >     ) `catch` stopUpdaters updaters
		     >   where stopUpdaters updaters ThreadKilled =    
		     >           mvar&traverse !| killThread $ updaters               -- Kill all spawned threads before stopping
		     .
		     There are a bunch of predefined references for datatypes included in standard libraries.
		     .
		     New references can be created in several ways:
		     .
		      * From getter, setter and updater, using the @reference@ function.
		     .
              * From getter and setter, using one of the simplified functions (@lens@, @simplePartial@, @partial@, ...).
		     .
		      * Using the `Data.Traversal` instance on a datatype to generate a traversal of each element.
		     .
		      * Using lenses from `Control.Lens` package. There are a lot of packages defining lenses, folds and traversals
		        for various data structures, so it is very useful that all of them can simply be converted into a reference.
		     .
		      * Generating references for newly defined datatypes using the `makeReferences` Template Haskell function.
		     .

homepage:            https://github.com/lazac/references
license:             BSD3
license-file:        LICENSE
author:              Boldizsar Nemeth
maintainer:          nboldi@elte.hu
-- copyright:           
category:            Control
build-type:          Simple
cabal-version:       >=1.8

-- For some reason, cabal won't allow me to write this:
--
-- source-repository:   head
--   type:       git
--   location:   git://github.com/lazac/references.git
-- source-repository:   this
--   type:       git
--   location:   git://github.com/lazac/references.git
--   tag:        0.2.1.2

library
  exposed-modules:     Control.Reference
                     , Control.Reference.TH.Records
                     , Control.Reference.TH.Tuple
                     , Control.Reference.Examples.TH
                     , Control.Reference.Representation
                     , Control.Reference.Operators
                     , Control.Reference.Predefined
                     , Control.Reference.Predefined.Containers
                     , Control.Reference.Predefined.Containers.Tree
                     , Control.Reference.TupleInstances
                     , Control.Reference.InternalInterface
  build-depends:       base                 >= 4.6 && < 5 
                     , text                 == 1.1.*
                     , array                == 0.5.*
                     , mtl                  == 2.2.*
                     , transformers         == 0.4.*
                     , containers           == 0.5.*
                     , either               == 4.3.*
                     , template-haskell     >= 2.8 && < 3
                     , instance-control     == 0.1.*
                     , directory            == 1.2.*
                     , filepath             == 1.3.*