CSCM

The Concurrent Schemer

(define #Fun (+ #Scheme #Erlang))

Contributors

Logo

The primary call for help is to review, implement (in Erlang), and test the Scheme R7RS standard libraries. A secondary call for help is to identify, to fix, and to resolve key issues posted to CSCM’s issue tracker. A little bit of Scheme and/or Erlang programming experience is helpful but not absolutely necessary.

section 2.1 CSCM Issue #2
Development/Test
done
Review
needs peer review
section 4.3 Macros
Development/Test
beta done
Review
needs peer review
section 5.4 Syntax definitions
Development/Test
beta done
Review
needs peer review
section 5.5 Record-type definitions
Development/Test
not yet started
Review
n/a
section 6.1 Equivalence predicates
Development/Test
done
Review
needs peer review
section 6.2 Numbers
Development/Test
not yet started
Review
n/a
section 6.3 Booleans
Development/Test
done
Review
needs peer review
section 6.4 Pairs and lists
Development/Test
done
Review
needs peer review
section 6.5 Symbols
Development/Test
done
Review
needs peer review
section 6.6 Characters
Development/Test
done
Review
needs peer review
section 6.7 Strings
Development/Test
done
Review
needs peer review
section 6.8 Vectors
Development/Test
done
Review
needs peer review
section 6.9 Bytevectors
Development/Test
done
Review
needs peer review
section 6.10 Control features
Development/Test
done
Review
needs peer review
section 6.11 Exceptions
Development/Test
done
Review
needs peer review
section 6.13 Input and output
Development/Test
done
Review
needs peer review
section 6.14 System interface
Development/Test
done
Review
needs peer review
appendix A Case-Lambda Library
Development/Test
not yet started
Review
n/a
appendix A Char Library
Development/Test
not yet started
Review
n/a
appendix A Complex Library
Development/Test
not yet started
Review
n/a
appendix A CxR Library
Development/Test
not yet started
Review
n/a
appendix A Eval Library
Development/Test
not yet started
Review
n/a
appendix A File Library
Development/Test
not yet started
Review
n/a
appendix A Inexact Library
Development/Test
not yet started
Review
n/a
appendix A Lazy Library
Development/Test
not yet started
Review
n/a
appendix A Load Library
Development/Test
not yet started
Review
n/a
appendix A Process-Context Library
Development/Test
not yet started
Review
n/a
appendix A Read Library
Development/Test
not yet started
Review
n/a
appendix A Repl Library
Development/Test
not yet started
Review
n/a
appendix A Time Library
Development/Test
not yet started
Review
n/a
appendix A Write Library
Development/Test
not yet started
Review
n/a
appendix A R5RS Library
Development/Test
not yet started
Review
n/a

Caution Please stay tuned for CSCM updates. The specification, documentation, and software are under construction.

Miscellaneous TODO Items

  • pending R7RS draft 10 changes
    • Remove extra exponent markers from formal syntax

Getting Started

An incomplete list of steps for "Getting Started".

Mandatory

  1. read the Scheme overview paper
  2. download and build 
    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 
    (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.

    1. Start the Erlang shell. 
      erl -pa ./deps/parse-tools/ebin -pa ebin
    2. Save the "hello word" program as an Erlang string. 
      Str = "(define hello-world (lambda () (display \"Hello World!\")))".
    3. Create an empty Scheme environment. 
      Env = scmi_env:the_empty().
    4. 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. 
      False = {boolean,undefined,false}.
Proc = {nipv, 0, fun(Args) -> io:format("~p~n", [Args]), False end}.
scmi_env:define_variable('display', Proc, Env).
    5. Parse and evaluate the "hello world" program. 
      {ok, Exp} = scmd_parse:string(Str).
scmi_eval:eval(Exp, Env).
    6. Call the Scheme "hello-world" procedure and show the Scheme return value in the Erlang shell. 
      R = scmi_eval:eval(['hello-world'], Env).
R.

Optional (but helpful)

  1. read the final Scheme R7RS small report specification and errata
  2. review and understand
    1. the layout of the scm git repository

      Tip Filename prefixes have meaning ⇒ scmd_ is "datum", scmi_ is "interpreter", scmc_ is "compiler", scml_ is "library", and xfm_ is "Erlang parse transform".

    2. the CSCM datum model
    3. Scheme datum and number (base 2, base 8, base 10, and base 16) tokenizers
    4. Scheme datum and number parsers
    5. Scheme environment resource wrapper and NIF

      Tip If helpful, review Erlang’s documentation about API functions for an Erlang NIF library.

    6. Scheme interpreter evaluator and syntactic analyzer
    7. Scheme primitive expressions
    8. Scheme derived expressions
    9. Scheme macro expressions
    10. Scheme control features base library
    11. Scheme exceptions base library
    12. …
  3. run xref 
    make xref
  4. generate edocs 
    make doc

Note Steps describing how to setup and to run Erlang’s dialyzer will be added later.

Lines Of Code

Scheme datum

~1,200 Erlang LOC implements a Scheme datum tokenizer and parser.

 $ cloc src/scmd_*
       12 text files.
       12 unique files.
        0 files ignored.

 http://cloc.sourceforge.net v 1.58  T=0.5 s (24.0 files/s, 3856.0 lines/s)
 -------------------------------------------------------------------------------
 Language                     files          blank        comment           code
 -------------------------------------------------------------------------------
 Erlang (yecc)                    2            108             79            471
 Erlang (leex)                    5            192            264            332
 Erlang                           5             46            124            312
 -------------------------------------------------------------------------------
 SUM:                            12            346            467           1115
 -------------------------------------------------------------------------------

Scheme interpreter

~600 C/C++ LOC and ~3,200 Erlang LOC implements all Scheme primitive, derived, program, and macro expressions.

 $ cloc src/scmi_* c_src
       23 text files.
       23 unique files.
        0 files ignored.

 http://cloc.sourceforge.net v 1.58  T=0.5 s (46.0 files/s, 10914.0 lines/s)
 -------------------------------------------------------------------------------
 Language                     files          blank        comment           code
 -------------------------------------------------------------------------------
 Erlang                          15            669            659           3157
 C++                              4            140            105            541
 C/C++ Header                     4             26             88             72
 -------------------------------------------------------------------------------
 SUM:                            23            835            852           3770
 -------------------------------------------------------------------------------

Scheme library

~400 Erlang LOC implements Scheme exceptions, continuations, dynamic-wind, and other control procedures.

 $ cloc src/scml_base_control.erl src/scml_base_exception.erl
        2 text files.
        2 unique files.
        0 files ignored.

 http://cloc.sourceforge.net v 1.58  T=0.5 s (4.0 files/s, 1238.0 lines/s)
 -------------------------------------------------------------------------------
 Language                     files          blank        comment           code
 -------------------------------------------------------------------------------
 Erlang                           2             67            187            365
 -------------------------------------------------------------------------------
 SUM:                             2             67            187            365
 -------------------------------------------------------------------------------

Note The above measurements were taken on a snapshot of CSCM after v0.5.0 with a modified version of cloc for detecting Erlang leex/yecc files.

Submissions

This process is a DRAFT.

Please review and follow these guidelines for contribution submissions.

  • Try to keep all submissions simple, clear, and concise
    • remove all unused or unnecessary code
    • remove unnecessary whitespace
    • fix all compiler warnings, run xref, and run dialyzer on each submission
    • use @TODO comment markers when helpful
  • Create a topic branch off the dev branch for each pull request
  • Create a single commit for each pull request and try to focus each commit on a single topic or a set of related topics ⇒ help make it easier for others to review and to test
  • Update the Edoc @author tag of each module where you are considered a primary author
  • Ensure the the copyright and license shown below is included in all submissions
  • As much as "practically" possible, follow the CSCM roadmap and notify Joe N. in advance of your plans to minimize the duplication efforts
  • Most importantly there is no rush and have fun!

Note For the near term, only documentation and code submissions will be accepted in an attempt to keep the layout and contents of the scm repository simple, clear and concise. Testing such as unit, regression, compatibility, and performance testing will be addressed later.

Software Requirements

Erlang/OTP (Mandatory)
  • Erlang - http://www.erlang.org/
    • 17 or newer, 17 has been tested most recently
    • required for development ++ TIP: If you need to build and to install Erlang on your own, kerl is highly recommended
Git (Mandatory)
  • Git - http://git-scm.com/
    • Git 1.5.4 or newer, Git 1.9.3 has been tested most recently
    • required for GitHub
  • GitHub - https://github.com
    • Anonymous read-only access using the GIT protocol is default.
    • Team members having read-write access should add his/her ssh public key under your GitHub account.
Python (Optional)
  • Python - http://www.python.org
    • Python 2.4 or newer, Python 2.7.6 has been tested most recently (CAUTION: Python 3.x might be too new)
    • required for AsciiDoc
AsciiDoc (Optional)

Resources

Emacs

An editor (just like a programming language) is a creature of choice. An editor should also be a creature of comfort. If Emacs happens to be your favorite creature for editing, I highly recommend the following packages:

These packages are very helpful (and comforting) for Erlang development.