From 07bb8aec885be42d05486e3bc431d5d0f31a191f Mon Sep 17 00:00:00 2001 From: Siraaj Khandkar Date: Tue, 6 Jan 2015 15:51:08 -0500 Subject: [PATCH] Expand description. --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 88 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e5578b4..d9b4464 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,49 @@ [![Build Status](https://travis-ci.org/ibnfirnas/hope.svg?branch=master)](https://travis-ci.org/ibnfirnas/hope) -Higher Order Programming in Erlang -================================== +Hope +==== A quest for a "standard" library with uniform, composable abstractions. +Originally motivated by a desire for an error monad and generic option type +operations, and stood for _Higher Order Programming in Erlang_. Soon after, I +wished all standard containers used consistent conventions and protocols (such +as consistent accessor names, argument positioning rules and expression of +semantics with option and result types). -Monads ------- +Here lies an experiment to see what something like that could look like. As all +proper experiments should, this one is used daily in production projects (hence +the high-ish version number, 'cause semver). + +Conventions +----------- + +I entertain any forward-thinking library design ideas, but more than anything +else, these are influenced by Jane Street's Core of the OCaml world. + +- A module per data type implementation +- Name of the module is the name of the type +- Inside the module, the type it implements is always named t(..), such as: + `hope_foo:t()`, _not_ `hope_foo:foo()` +- t(..) is always the first argument +- Names of private records _may_ be short, such as: `#foo{}` or `#t{}` (Though + I'm second-guessing this idea, since seeing `{t, ..}` in stack traces is less + than helpful. I'm considering requiring fully-qualified names for all record + definitions and maybe short-handing what would've been `#t{..}` as + `-define(T, ?MODULE). -record(?T, {..}).`, which may be a bit ugly. Still + thinking...) +- Names of public records _must_ be fully qualified, such as: `#hope_module_record{}` +- Names of all modules _must_ be fully qualified, such as: `hope_module` (this + should go without saying, but just to be sure...) + + +Abstractions +------------ + +### Monads + +A class of burritos, used for sequencing operations on a particular data type. Defined in `hope_gen_monad`, implemented as: - `hope_result`: for composition of common functions returning @@ -22,15 +57,61 @@ Defined in `hope_gen_monad`, implemented as: `'a Option.t`, Rust's `Option` and Haskell's `Data.Maybe a` [1]. -Containers ----------- +### Containers -### Dictionary +A class of abstract data types to which we have exclusive access and can put +things in and take them out. See issue #9 + +- Operations on all abstract types of containers _should_ share a common lexicon +- Concrete implementations of an abstract data type _must_ be swapable + +#### Dictionary Defined in `hope_gen_dictionary`, implemented as: - `hope_kv_list`. Equivalent to orddict/proplist. Operations implemented with BIFs from `lists` module, where possible +TBD: +- `hope_hash_tbl`. API around stdlib's `dict` +- `hope_gb_dict`. API around stdlib's `gb_trees` + +#### Set + +TBD: +- `hope_hash_set`. API around stdlib's `sets` +- `hope_gb_set`. API around stdlib's `gb_sets` + +#### Queue + +TBD + +Should include both FIFO (queue) and LIFO (stack), so that user can swap if a +different order is desired. + +Should we attempt to include priority queues or make them a separate abstract +type? + +#### Sequence + +TBD + +Not yet defined and only partially implemented as: + +- `hope_list` + + +### Resources + +A class of abstract systems to which we share access with an unknown number of +users and can make requests to perform operations which may not get done for +any number of reasons. + +#### Storage + +TBD + +See issue #11 + [1]: http://en.wikipedia.org/wiki/Option_type -- 2.20.1