www

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

README.md (2659B)

      1 [![Build Status,](https://img.shields.io/travis/jsmaniac/remember/main.svg)](https://travis-ci.org/jsmaniac/remember)
      2 [![Coverage Status,](https://img.shields.io/codecov/c/github/jsmaniac/remember/main.svg)](https://codecov.io/gh/jsmaniac/remember)
      3 [![Build Stats,](https://img.shields.io/badge/build-stats-blue.svg)](http://jsmaniac.github.io/travis-stats/#jsmaniac/remember)
      4 [![Online Documentation,](https://img.shields.io/badge/docs-online-blue.svg)](http://docs.racket-lang.org/remember/)
      5 [![Maintained as of 2017,](https://img.shields.io/maintenance/yes/2017.svg)](https://github.com/jsmaniac/remember/issues)
      6 [![License: CC0 v1.0.](https://img.shields.io/badge/license-CC0-blue.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
      7 
      8 remember
      9 ========
     10 
     11 This Racket library provides a compile-time memoize feature. It allows
     12 remembering a value with `(remember-write! 'category 'value)`. In subsequent
     13 compilations, `(get-remembered 'category)` will return a set of all
     14 previously-remembered values.
     15 
     16 Installation
     17 ============
     18 
     19 raco pkg install remember
     20 
     21 Example use case: the `phc-adt` library
     22 =======================================
     23 
     24 This library is used to implement "interned" structure and constructor types
     25 in the [`phc-adt`](https://github.com/jsmaniac/phc-adt) library. The `phc-adt`
     26 library needs to know the set of all structure and constructor types used in
     27 the program, and uses `remember` to automatically memoize structure
     28 descriptors and constructor names.
     29 
     30 When the `structure` macro defined in
     31 [`structure.hl.rkt`](https://github.com/jsmaniac/phc-adt/blob/refactor/structure.hl.rkt)
     32 encounters an unknown list of field names, it uses the `remember` library to
     33 append the tuple of field names to a user-specified file. That file is loaded
     34 in subsequent compilations, so that the tuple of fields is known to `phc-adt`.
     35 
     36 The memoized descriptors are used to know all possible structs that can
     37 contain a field with the desired name when accessing it with `(get instance
     38 field-name)`. The `get` macro can then retrieve the field's value using the
     39 right accessor (for example `(struct123-fieldname instance)`). Knowing all
     40 existing structures allows `get` to perform some kind of dynamic dispatch to
     41 obtain the appropriate accessor, for example using a `cond` which tests for
     42 all possible types.
     43 
     44 The `constructor` macro defined in
     45 [`constructor.hl.rkt`](https://github.com/jsmaniac/phc-adt/blob/refactor/constructor.hl.rkt)
     46 works in the same way, but remembers the name of the constructor's tag instead
     47 of field names. The memoization feature is used so that all uses of a
     48 constructor with a given name are equivalent, across all files.
     49