The references package

[ Tags: bsd3, control, library ] [ Propose Tags ]

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.

There are two things that references can do but the previously mentioned access methods don't.

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:


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.2.1.0, 0.2.1.1, 0.2.1.2, 0.3.0.0, 0.3.0.1, 0.3.1.0, 0.3.1.1, 0.3.2.0, 0.3.2.1, 0.3.2.2, 0.3.3.0
Change log CHANGELOG.md
Dependencies array (>=0.5 && <1), base (>=4.9 && <5), containers (>=0.5 && <1), directory (>=1.2 && <2), either (>=4.3 && <5), filepath (>=1.3 && <2), instance-control (>=0.1 && <1), mtl (>=2.2 && <3), template-haskell (>=2.8 && <3), text (>=1.1 && <2), transformers (>=0.4 && <1), uniplate (>=1.6 && <2) [details]
License BSD3
Copyright Boldizsar Nemeth, 2014
Author Boldizsar Nemeth
Maintainer nboldi@elte.hu
Category Control
Home page https://github.com/lazac/references
Source repository head: git clone git://github.com/lazac/references.git
Uploaded Wed Sep 27 06:39:38 UTC 2017 by lazac
Distributions LTSHaskell:0.3.3.0, NixOS:0.3.3.0, Stackage:0.3.3.0, Tumbleweed:0.3.2.1
Downloads 1557 total (23 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-09-27 [all 1 reports]
Hackage Matrix CI

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for references-0.3.3.0

[back to package 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. References are more potent than lenses, folds and traversals:
  • 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 number 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. Hackage