diff --git a/THANKS.asciidoc b/THANKS.asciidoc new file mode 100644 index 0000000..132b228 --- /dev/null +++ b/THANKS.asciidoc @@ -0,0 +1,7 @@ +The following people, in chronological order, have sent patches, pull +requests, and/or bug reports that have been incorporated in CSCM's +documentation base: + +1. Joseph Wayne Norton +2. Klaus Trainer +3. ... diff --git a/src/contributors.asciidoc b/src/contributors.asciidoc index 18bc4f4..21568ae 100644 --- a/src/contributors.asciidoc +++ b/src/contributors.asciidoc @@ -18,42 +18,226 @@ Joseph Wayne Norton == Contributors -*The current call for help is to implement the Scheme R7RS base -library in Erlang. A little bit of Scheme and/or Erlang programming -experience is helpful but not absolutely necessary.* +*The current call for help is to review, implement _(in Erlang)_, and +test the Scheme R7RS base library.* + +- _v0.4.0_ Scheme base library (w/o numbers) + * section 6.1 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_equality.erl[ + Equivalence predicates] + * section 6.3 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_boolean.erl[ + Booleans] + * section 6.4 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_list.erl[ + Pairs and lists] + * section 6.5 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_symbol.erl[ + Symbols] + * section 6.6 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_char.erl[ + Characters] + * section 6.7 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_string.erl[ + Strings] + * section 6.8 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_vector.erl[ + Vectors] + * section 6.9 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_bytevector.erl[ + Bytevectors] + * section 6.10 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_control.erl[ + Control features] + * section 6.11 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_exception.erl[ + Exceptions] + * section 6.13 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_io.erl[ + Input and output] + * section 6.14 https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_system.erl[ + System interface] + +A little bit of Scheme and/or Erlang programming experience is helpful +but not absolutely necessary. CAUTION: _Please stay tuned for CSCM updates. The specification, documentation, and software are under construction._ == Getting Started -An incomplete *todo* list of "Getting Started" steps. +An incomplete list of steps for "Getting Started". *Mandatory* -- read the Scheme overview brief -- read the Scheme R7RS specification -- download scm -- build scm -- run "hello world" example -- review and understand - * the layout of the scm git repository - * the CSCM data model - ** mapping between Scheme and Erlang - ** Erlang "specs" and "types" used for documentation and dialyzer - purposes - * the Scheme tokenzier and parser - * the Scheme environment implementation - * the Scheme primitive expression implementation - * the Scheme derived expression implementation - * the Scheme continuations and exceptions implementation - * ... - -*Optional (but necessary)* - -- run xref -- setup and run dialyzer -- generate edocs +1. read the Scheme + http://trac.sacrideo.us/wg/raw-attachment/wiki/WikiStart/overview.pdf[overview] + paper + +2. download and build ++ +[source,shell] +------ +git clone git://github.com/the-concurrent-schemer/scm.git +cd scm +make deps +make + +------ ++ +TIP: Check the Software Requirements listed below before attempting to +download and build! + +3. run "hello world" example ++ +[source,scheme] +------ +(define hello-world + (lambda () + (display "Hello World!"))) +------ ++ + +Since CSCM is under construction, this example must be run manually +for the time being. Let's use the Erlang shell for illustrative +purposes. + + a. Start the Erlang shell. ++ +[source,shell] +------ +erl -pa ./deps/parse-tools/ebin -pa ebin +------ + + b. Save the "hello word" program as an Erlang string. ++ +[source,erlang] +------ +Str = "(define hello-world (lambda () (display \"Hello World!\")))". +------ ++ + + c. Create an empty Scheme environment. ++ +[source,erlang] +------ +Env = scmi_env:the_empty(). +------ ++ + + d. Create and register a native Erlang function as a simple + implementation for the Scheme display library procedure. The + Erlang function writes the given arguments to stdout as Erlang + terms and simply returns a Scheme #false to the caller. ++ +[source,erlang] +------ +False = {boolean,undefined,false}. +Proc = {nipv, 0, fun(Args) -> io:format("~p~n", [Args]), False end}. +scmi_env:define_variable('display', Proc, Env). +------ ++ + + e. Parse and evaluate the "hello world" program. ++ +[source,erlang] +------ +{ok, Exp} = scmd_parse:string(Str). +scmi_eval:eval(Exp, Env). +------ ++ + + f. Call the Scheme "hello-world" procedure and show the Scheme + return value in the Erlang shell. ++ +[source,erlang] +------ +R = scmi_eval:eval(['hello-world'], Env). +R. +------ + +*Optional (but helpful)* + +1. read the Scheme R7RS + http://trac.sacrideo.us/wg/raw-attachment/wiki/WikiStart/r7rs-draft-9.pdf[draft9] + specification + +2. review and understand + a. the layout of the scm git + https://github.com/the-concurrent-schemer/scm/tree/dev[repository] ++ +TIP: Filename prefixes have meaning => +scmd_+ is "datum", +scmi_+ is +"interpreter", +scmc_+ is "compiler", and +scml_+ is "library". + + b. the CSCM datum model + ** https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_types_impl.erl[implementation] + of Scheme datums by Erlang terms + ** Erlang + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_types.erl[types] + used for documentation and static type analysis ++ +TIP: If helpful, review Erlang's +http://www.erlang.org/doc/reference_manual/typespec.html[documentation] +about types and function specifications. + + c. Scheme + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_scan.xrl[datum] + and number + (https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_scan_num2.xrl[base + 2], + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_scan_num8.xrl[base + 8], + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_scan_num10.xrl[base + 10], and + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_scan_num16.xrl[base + 16]) tokenizers + + d. Scheme + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_parse.yrl[datum] + and + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmd_parse_numR.yrl[number] + parsers + + e. Scheme environment resource + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmi_env.erl[wrapper] + and + https://github.com/the-concurrent-schemer/scm/blob/dev/c_src/scmi_env.cc[NIF] ++ +TIP: If helpful, review Erlang's +http://www.erlang.org/doc/man/erl_nif.html[documentation] about API +functions for an Erlang NIF library. + + f. Scheme interpreter + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmi_eval.erl[evaluator] + and + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmi_analyze.erl[syntactic + analyzer] + + g. Scheme + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmi_analyze_primitive.erl[primitive] + expressions + + h. Scheme + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scmi_analyze_derived.erl[derived] + expressions + + i. Scheme + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_control.erl#L124[control + features] base library + + j. Scheme + https://github.com/the-concurrent-schemer/scm/blob/dev/src/scml_base_exception.erl#L71[exceptions] + base library + + k. ... + +3. run xref ++ +[source,shell] +------ +make xref + +------ + +4. generate edocs ++ +[source,shell] +------ +make doc + +------ + +NOTE: Steps describing how to setup and to run Erlang's dialyzer will +be added later. == Submissions diff --git a/src/index.asciidoc b/src/index.asciidoc index f5c3e27..0ca0bc6 100644 --- a/src/index.asciidoc +++ b/src/index.asciidoc @@ -101,11 +101,10 @@ CSCM is aimed as an: This http://trac.sacrideo.us/wg/raw-attachment/wiki/WikiStart/overview.pdf[overview] -of the Scheme programming language download-able from the Scheme +paper of the Scheme programming language download-able from the Scheme Report\'s website is a good place to start. The complete Scheme R7RS -http://trac.sacrideo.us/wg/raw-attachment/wiki/WikiStart/r7rs-draft-9.pdf[draft -9] specification available from the same website is the best next -step. +http://trac.sacrideo.us/wg/raw-attachment/wiki/WikiStart/r7rs-draft-9.pdf[draft9] +specification available from the same website is the best next step. == Roadmap @@ -371,9 +370,9 @@ Roadmap. (define #Fun (+ #Scheme #Erlang)) If you are interested in Scheme, Erlang, Functional programming, or -otherwise, please -mailto:nortonATalum.mit.edu?subject=Inquiry%20about%20The%20Concurrent%20Schemer[contact -Joe N.] for more information. +otherwise, please check the +http://the-concurrent-schemer.github.io/scm-doc/contributors.html[Contributor's +Guide] for more information. == Copyright and License