Improved README file.
This commit is contained in:
Georges Dupéron
parent
9875f56755
commit
f31dccc107
255
graph-lib/README
255
graph-lib/README
|
|
@ -1,255 +0,0 @@
|
|||
How to build this project
|
||||
=========================
|
||||
|
||||
To install the build dependencies of this project on a clean Ubuntu 14.04
|
||||
machine, you need to install a recent version of racket. First, you need to
|
||||
install a recent version of racket. Then run the following commands:
|
||||
|
||||
cd graph-lib/
|
||||
sudo apt-get install git
|
||||
git submodule init
|
||||
git submodule update
|
||||
make build-dep
|
||||
|
||||
To build the project, simply run `make`:
|
||||
|
||||
make
|
||||
|
||||
List of files
|
||||
=============
|
||||
|
||||
Graph library
|
||||
-------------
|
||||
|
||||
* graph/graph.lp2.rkt
|
||||
|
||||
Implements a graph construction library. The user specifies a series of
|
||||
transformations from a root input value to a result node, and can safely call
|
||||
other transformations, without risking to run into an infinite loop.
|
||||
|
||||
The make-graph-constructor takes the types of the result nodes, and the
|
||||
transformations, and creates a graph-construction routine that detects cycles,
|
||||
and prevents infinite recursion.
|
||||
|
||||
For now, in the result, calls to other transformations are replaced by link
|
||||
requests, but later versions will allow seamless access to the target result
|
||||
node.
|
||||
|
||||
The make-graph-constructor macro can be used like this:
|
||||
|
||||
(define make-g
|
||||
(make-graph-constructor
|
||||
([ma (fav String) (faa ma) (fab mb)]
|
||||
[mb (fbv String) (fba ma)])
|
||||
[transform-a (s String) : ma
|
||||
(ma s
|
||||
(transform-a s)
|
||||
(transform-b "b"))]
|
||||
[transform-b (s String) : mb
|
||||
(mb s
|
||||
(transform-a s))]))
|
||||
|
||||
Then, when the resulting graph constructor is called:
|
||||
|
||||
(make-g "root-arg")
|
||||
|
||||
We get the following graph as a result:
|
||||
|
||||
(ma "root-arg" <link-request1> <link-request2>)
|
||||
^ | |
|
||||
`-------------------' ,------'
|
||||
v
|
||||
(mb "b" <link-request3>)
|
||||
^ |
|
||||
,--------------------------- | -----------'
|
||||
v |
|
||||
(ma "b" <link-request4> <link-request5>)
|
||||
^ |
|
||||
`------------'
|
||||
|
||||
* graph/type-system.scrbl
|
||||
|
||||
Documentation about the type system implemented by graph/graph2.lp2.rkt,
|
||||
graph/variant.lp2.rkt, graph/structure.lp2.rkt.
|
||||
|
||||
* graph/variant.lp2.rkt
|
||||
|
||||
Implements tagged unions, similar to those in caml, F#, or the unions in C if
|
||||
a tag field is added, with a distinct tag value for each type in the union.
|
||||
|
||||
* graph/structure.lp2.rkt
|
||||
|
||||
Implements structures with anonymous access: accessing the field “b” of a
|
||||
structure instance i can be written: (get i b), independently of the structure
|
||||
type of the instance. Traditionnally, if one creates two structs in Racket,
|
||||
using:
|
||||
|
||||
(struct s1 ([a : Number] [b : String]))
|
||||
(struct s2 ([b : String] [c : Boolean]))
|
||||
|
||||
then, to access the “b” field from an instance “i” of “s1”, one has to write
|
||||
“(s1-b i)”, whereas to access the field “b” from an instance “j” of “s2”, one
|
||||
has to write “(s2-b j)”. The fact that we need to know the type of an instance
|
||||
to access one of its fields is impractical when one needs to work with a large
|
||||
number of structs which share some field names.
|
||||
|
||||
Inheritance could solve this problem, but Racket only has single inheritance
|
||||
for structs, not multiple inheritance.
|
||||
|
||||
With the syntax offered by this library, one can write (get i b) for the first
|
||||
case and (get j b), therefore allowing more flexible use of structures
|
||||
containing similar fields.
|
||||
|
||||
* graph/equatable.rkt
|
||||
|
||||
Provides a struct in typed/racket with customizable equality, hashing and
|
||||
printing. This is similar to overriding .equals(), .hashCode() and .toString()
|
||||
in Java.
|
||||
|
||||
Untyped racket provides these features out of the box, but they are not
|
||||
normally available in typed/racket.
|
||||
|
||||
* graph/dotlang.rkt
|
||||
|
||||
Small programming language extension that allows writing “instance.f.g.h”
|
||||
instead of “(get (get (get instance f) g) h)”.
|
||||
|
||||
* graph/remember.rkt
|
||||
|
||||
This utility module is used by graph/structure.lp2.rkt to memoize structure
|
||||
descriptiors. When the “structure” macro defined in graph/structure.lp2.rkt
|
||||
encounters an unknown list of field names, it adds it to the file
|
||||
graph/remember.rkt. The memoized descriptors are used to know all possible
|
||||
structs that can contain a field with the desired name when aceesing it with
|
||||
“(get instance field-name)”. The “get” macro can then dispatch on these types,
|
||||
and retrieve the field's value using the right accessor (for example
|
||||
“(s123-field-name instance)”).
|
||||
|
||||
* graph/list-lang.rkt
|
||||
|
||||
Tiny programming language extension that allows constructing a list with the
|
||||
contents of all trailing lines in the file. This is used by graph/remember.rkt
|
||||
to easily add elements to the list of memoized structure descriptors, by just
|
||||
appending to the end of the file.
|
||||
|
||||
Type-expander
|
||||
-------------
|
||||
|
||||
* type-expander/type-expander.lp2.rkt
|
||||
|
||||
This library extends the type system to allow type-expander macros, much in
|
||||
the same way that “(match …)” allows match-expanders. For example, one can
|
||||
write the “(Repeat t n)” type-expander, which expands to a list of “n”
|
||||
elements of type “t”:
|
||||
|
||||
(define-type-expander (Repeat stx)
|
||||
(syntax-case stx ()
|
||||
[(_ t n)
|
||||
#`(List #,@(map (λ (x) #'t)
|
||||
(range (syntax->datum #'n))))]))
|
||||
|
||||
It can then be used in places where a regular type is expected:
|
||||
|
||||
(: count-five-more (→ Number (Repeat Number 5)))
|
||||
(define (count-five-more x)
|
||||
(list (+ x 1) (+ x 2) (+ x 3) (+ x 4) (+ x 5)))
|
||||
|
||||
(count-five-more 3)
|
||||
;; => '(4 5 6 7 8)
|
||||
|
||||
(ann (count-five-more 15) (Repeat Number 5))
|
||||
;; => '(16 17 18 19 20)
|
||||
|
||||
This will be used by the graph library in graph/graph.lp2.rkt to allow
|
||||
expressing graph types anonymously:
|
||||
|
||||
(: x-to-string (→ (graph (a [x Number] [b b])
|
||||
(b [a a] [y Boolean]))
|
||||
(graph (a [x String] [b b])
|
||||
(b [a a] [y Boolean]))))
|
||||
(define (x-to-string g) …)
|
||||
|
||||
* type-expander/multi-id.lp2.rkt
|
||||
|
||||
This library allows easy definition of an identifier with multiple semantics:
|
||||
the same identifier can be used as a constructor function, match expander,
|
||||
type, type-expander, expanded type (i.e. a type containing type-expanders,
|
||||
that has been expanded once), regular mutable or immutable variable, and with
|
||||
a custom write procedure.
|
||||
|
||||
It allows defining a new type with its constructor and match expander with
|
||||
very little boilerplate code.
|
||||
|
||||
Library functions and utilities
|
||||
-------------------------------
|
||||
|
||||
* lib/eval-get-values.rkt
|
||||
|
||||
Wrapper for the racket “eval” function that allows evaluation of code with
|
||||
multiple return values in typed/racket.
|
||||
|
||||
* lib/lib.rkt
|
||||
|
||||
Utilities that complement racket and typed/racket's standard libraries.
|
||||
|
||||
* lib/low.rkt
|
||||
|
||||
Lower-level utilities that complement racket and typed/racket's standard
|
||||
libraries.
|
||||
|
||||
* lib/low-untyped.rkt
|
||||
|
||||
Wrapper around lib/low.rkt that allows using it from a untyped racket file.
|
||||
|
||||
* lib/untyped/for-star-list-star.rkt
|
||||
|
||||
A utility macro similar to for*/list to iterate over collections and return a
|
||||
list of results, but which can return nested lists instead of just a flat one.
|
||||
|
||||
* lib/untyped.rkt
|
||||
|
||||
Aggregates lib/low-untyped.rkt, and lib/untyped/for-star-list-star.rkt.
|
||||
|
||||
* lib/test-framework.rkt
|
||||
|
||||
Some wrappers and utilities that allow easier use of the rackunit test
|
||||
framework from typed/racket files.
|
||||
|
||||
* lib/syntax/quasitemplate.rkt
|
||||
|
||||
Extension of the syntax/parse/experimental/template library, that allows using
|
||||
“unsyntax” and “unsyntax-splicing” inside a “quasitemplate”, just like in the
|
||||
normal “quasisyntax”.
|
||||
|
||||
* lib/path.rkt
|
||||
|
||||
Filesystem path manipulation utilities.
|
||||
|
||||
* lib/doc.rkt
|
||||
|
||||
Enhancements and utilities for documentation and literate programming files
|
||||
using scribble and scribble/lp2.
|
||||
|
||||
* lib/doc/math.rkt
|
||||
|
||||
Allows typesetting mathematical formulas in documentation and literate
|
||||
programming files using scribble and scribble/lp2.
|
||||
|
||||
* lib/doc/template.lp2.rkt
|
||||
|
||||
Example document using the features in lib/doc.rkt and lib/doc/math.rkt.
|
||||
|
||||
* lib/doc/example.lp2.rkt
|
||||
|
||||
Other example document using the features in lib/doc.rkt and lib/doc/math.rkt.
|
||||
|
||||
Makefile
|
||||
--------
|
||||
|
||||
* make/make.rkt
|
||||
This program acts like a Makefile, it is used to compile the rest of
|
||||
the code.
|
||||
|
||||
* make/lib.rkt
|
||||
Function definitions for the "unix make"-like tool, used by
|
||||
make/make.rkt
|
||||
260
graph-lib/README.md
Normal file
260
graph-lib/README.md
Normal file
|
|
@ -0,0 +1,260 @@
|
|||
[](https://travis-ci.org/jsmaniac/phc)
|
||||
|
||||
How to build this project
|
||||
=========================
|
||||
|
||||
To install the build dependencies of this project on a clean Ubuntu 14.04
|
||||
machine, you need to install a recent version of racket. First, you need to
|
||||
install a recent version of racket. Then run the following commands:
|
||||
|
||||
cd graph-lib/
|
||||
sudo apt-get install git
|
||||
git submodule init
|
||||
git submodule update
|
||||
make build-dep
|
||||
|
||||
To build the project, simply run `make`:
|
||||
|
||||
make
|
||||
|
||||
List of files
|
||||
=============
|
||||
|
||||
Graph library
|
||||
-------------
|
||||
|
||||
* `graph/graph.lp2.rkt`
|
||||
|
||||
Implements a graph construction library. The user specifies a series of
|
||||
transformations from a root input value to a result node, and can safely call
|
||||
other transformations, without risking to run into an infinite loop.
|
||||
|
||||
The make-graph-constructor takes the types of the result nodes, and the
|
||||
transformations, and creates a graph-construction routine that detects cycles,
|
||||
and prevents infinite recursion.
|
||||
|
||||
For now, in the result, calls to other transformations are replaced by link
|
||||
requests, but later versions will allow seamless access to the target result
|
||||
node.
|
||||
|
||||
The make-graph-constructor macro can be used like this:
|
||||
|
||||
(define make-g
|
||||
(make-graph-constructor
|
||||
([ma (fav String) (faa ma) (fab mb)]
|
||||
[mb (fbv String) (fba ma)])
|
||||
[transform-a (s String) : ma
|
||||
(ma s
|
||||
(transform-a s)
|
||||
(transform-b "b"))]
|
||||
[transform-b (s String) : mb
|
||||
(mb s
|
||||
(transform-a s))]))
|
||||
|
||||
Then, when the resulting graph constructor is called:
|
||||
|
||||
(make-g "root-arg")
|
||||
|
||||
We get the following graph as a result:
|
||||
|
||||
(ma "root-arg" <link-request1> <link-request2>)
|
||||
^ | |
|
||||
`-------------------' ,------'
|
||||
v
|
||||
(mb "b" <link-request3>)
|
||||
^ |
|
||||
,--------------------------- | -----------'
|
||||
v |
|
||||
(ma "b" <link-request4> <link-request5>)
|
||||
^ |
|
||||
`------------'
|
||||
|
||||
* `graph/type-system.scrbl`
|
||||
|
||||
Documentation about the type system implemented by `graph/graph2.lp2.rkt`,
|
||||
`graph/variant.lp2.rkt` and `graph/structure.lp2.rkt`.
|
||||
|
||||
* `graph/variant.lp2.rkt`
|
||||
|
||||
Implements tagged unions, similar to those in caml, F#, or the unions in C if
|
||||
a tag field is added, with a distinct tag value for each type in the union.
|
||||
|
||||
* `graph/structure.lp2.rkt`
|
||||
|
||||
Implements structures with anonymous access: accessing the field `b` of a
|
||||
structure instance `i` can be written: `(get i b)`, independently of the
|
||||
structure type of the instance. Traditionnally, if one creates two structs in
|
||||
Racket, using:
|
||||
|
||||
(struct s1 ([a : Number] [b : String]))
|
||||
(struct s2 ([b : String] [c : Boolean]))
|
||||
|
||||
then, to access the `b` field of an instance `i` of `s1`, one has to write
|
||||
`(s1-b i)`, whereas to access the field `b` of an instance `j` of `s2`, one
|
||||
has to write `(s2-b j)`. The fact that we need to know the type of an instance
|
||||
to access one of its fields is impractical when one needs to work with a large
|
||||
number of structs which share some field names.
|
||||
|
||||
Inheritance could solve this problem, but Racket only has single inheritance
|
||||
for structs, not multiple inheritance.
|
||||
|
||||
With the syntax offered by this library, one can write `(get i b)` for the
|
||||
first case and `(get j b)`, therefore allowing more flexible use of structures
|
||||
containing similar fields.
|
||||
|
||||
* `graph/equatable.rkt`
|
||||
|
||||
Provides a struct in typed/racket with customizable equality, hashing and
|
||||
printing. This is similar to overriding `.equals()`, `.hashCode()` and
|
||||
`.toString()` in Java.
|
||||
|
||||
Untyped racket provides these features out of the box, but they are not
|
||||
normally available in typed/racket.
|
||||
|
||||
* `graph/dotlang.rkt`
|
||||
|
||||
Small programming language extension that allows writing `instance.f.g.h`
|
||||
instead of `(get (get (get instance f) g) h)`.
|
||||
|
||||
* `graph/remember.rkt`
|
||||
|
||||
This utility module is used by `graph/structure.lp2.rkt` to memoize structure
|
||||
descriptiors. When the `structure` macro defined in `graph/structure.lp2.rkt`
|
||||
encounters an unknown list of field names, it adds it to the file
|
||||
`graph/remember.rkt`. The memoized descriptors are used to know all possible
|
||||
structs that can contain a field with the desired name when aceesing it with
|
||||
`(get instance field-name)`. The `get` macro can then dispatch on these types,
|
||||
and retrieve the field's value using the right accessor (for example
|
||||
`(s123-field-name instance)`).
|
||||
|
||||
* `graph/list-lang.rkt`
|
||||
|
||||
Tiny programming language extension that allows constructing a list with the
|
||||
contents of all trailing lines in the file. This is used by
|
||||
`graph/remember.rkt` to easily add elements to the list of memoized structure
|
||||
descriptors, by just appending to the end of the file.
|
||||
|
||||
Type-expander
|
||||
-------------
|
||||
|
||||
* `type-expander/type-expander.lp2.rkt`
|
||||
|
||||
This library extends the type system to allow type-expander macros, much in
|
||||
the same way that `(match …)` allows match-expanders. For example, one can
|
||||
write the `(Repeat t n)` type-expander, which expands to a list of `n`
|
||||
elements of type `t`:
|
||||
|
||||
(define-type-expander (Repeat stx)
|
||||
(syntax-case stx ()
|
||||
[(_ t n)
|
||||
#`(List #,@(map (λ (x) #'t)
|
||||
(range (syntax->datum #'n))))]))
|
||||
|
||||
It can then be used in places where a regular type is expected:
|
||||
|
||||
(: count-five-more (→ Number (Repeat Number 5)))
|
||||
(define (count-five-more x)
|
||||
(list (+ x 1) (+ x 2) (+ x 3) (+ x 4) (+ x 5)))
|
||||
|
||||
(count-five-more 3)
|
||||
;; => '(4 5 6 7 8)
|
||||
|
||||
(ann (count-five-more 15) (Repeat Number 5))
|
||||
;; => '(16 17 18 19 20)
|
||||
|
||||
This will be used by the graph library in `graph/graph.lp2.rkt` to allow
|
||||
expressing graph types anonymously:
|
||||
|
||||
(: x-to-string (→ (graph (a [x Number] [b b])
|
||||
(b [a a] [y Boolean]))
|
||||
(graph (a [x String] [b b])
|
||||
(b [a a] [y Boolean]))))
|
||||
(define (x-to-string g) …)
|
||||
|
||||
* `type-expander/multi-id.lp2.rkt`
|
||||
|
||||
This library allows easy definition of an identifier with multiple semantics:
|
||||
the same identifier can be used as a constructor function, match expander,
|
||||
type, type-expander, expanded type (i.e. a type containing type-expanders,
|
||||
that has been expanded once), regular mutable or immutable variable, and with
|
||||
a custom write procedure.
|
||||
|
||||
It allows defining a new type with its constructor and match expander with
|
||||
very little boilerplate code.
|
||||
|
||||
Library functions and utilities
|
||||
-------------------------------
|
||||
|
||||
* `lib/eval-get-values.rkt`
|
||||
|
||||
Wrapper for the racket `eval` function that allows evaluation of code with
|
||||
multiple return values in typed/racket.
|
||||
|
||||
* `lib/lib.rkt`
|
||||
|
||||
Utilities that complement racket and typed/racket's standard libraries.
|
||||
|
||||
* `lib/low.rkt`
|
||||
|
||||
Lower-level utilities that complement racket and typed/racket's standard
|
||||
libraries.
|
||||
|
||||
* `lib/low-untyped.rkt`
|
||||
|
||||
Wrapper around `lib/low.rkt` that allows using it from a untyped racket file.
|
||||
|
||||
* `lib/untyped/for-star-list-star.rkt`
|
||||
|
||||
A utility macro similar to `for*/list` to iterate over collections and return
|
||||
a list of results, but which can return nested lists instead of just a flat
|
||||
one.
|
||||
|
||||
* `lib/untyped.rkt`
|
||||
|
||||
Aggregates `lib/low-untyped.rkt`, and `lib/untyped/for-star-list-star.rkt`.
|
||||
|
||||
* `lib/test-framework.rkt`
|
||||
|
||||
Some wrappers and utilities that allow easier use of the rackunit test
|
||||
framework from typed/racket files.
|
||||
|
||||
* `lib/syntax/quasitemplate.rkt`
|
||||
|
||||
Extension of the `syntax/parse/experimental/template` library, that allows
|
||||
using `unsyntax` and `unsyntax-splicing` inside a `quasitemplate`, just like
|
||||
in the normal `quasisyntax`.
|
||||
|
||||
* `lib/path.rkt`
|
||||
|
||||
Filesystem path manipulation utilities.
|
||||
|
||||
* `lib/doc.rkt`
|
||||
|
||||
Enhancements and utilities for documentation and literate programming files
|
||||
using scribble and scribble/lp2.
|
||||
|
||||
* `lib/doc/math.rkt`
|
||||
|
||||
Allows typesetting mathematical formulas in documentation and literate
|
||||
programming files using scribble and scribble/lp2.
|
||||
|
||||
* `lib/doc/template.lp2.rkt`
|
||||
|
||||
Example document using the features in `lib/doc.rkt` and `lib/doc/math.rkt`.
|
||||
|
||||
* `lib/doc/example.lp2.rkt`
|
||||
|
||||
Other example document using the features in `lib/doc.rkt` and
|
||||
`lib/doc/math.rkt`.
|
||||
|
||||
Makefile
|
||||
--------
|
||||
|
||||
* `make/make.rkt`
|
||||
|
||||
This program acts like a Makefile, it is used to compile the rest of
|
||||
the code.
|
||||
|
||||
* `make/lib.rkt`
|
||||
|
||||
Function definitions used by the `make/make.rkt` tool.
|
||||
Loading…
Reference in New Issue
Block a user