Preliminary CAMlog User Guide Contents 1. Invocation Of CAMlog 2. The Interactive CAMlog Command Line Interface 3. Separate Compliation Of An Evaluation Context 4. CAMlog Command Line Options 5. Fine Control Of The Interpretation Process 6. Calling CAMlog From Java 7. Resources Other Papers - A White Paper on CAMlog - A Gentle Introduction To CAMlog - CAMlog Language Description (NOT YET) - CAMlog Scripting API documentation (NOT YET) - CAMlog Quick Reference (NOT YET) Preface This paper describes invocation and interfacing of the CAMlog compiler / interpreter system. The document can only be of a preliminary nature, because the system surface currently is designed more for testing and experiments rather than production. 1. Invocation Of CAMlog The CAMlog system perfoms these tasks: (1) compilation: analyze CAMlog source code and translate it to CAM operational code, (2) execution: run the operational code in a CAM-model virtual machine. The system can be invoked through the following Java application calls: - CAMlog [-options] [source [output]] Compiles a single programs from a file (or stdin) and executes it. Listings and the result are written to a file (or stdout). Also, serialized operational code can also be writen to a (binary) file. - CAMlogVM [-options] [binary [output]] Loads binary operational code from a file, executes it and writes the result to a file. - CAMlogCLI [-options] [context_source [context_listing]] First, a 'context' source is compiled and loaded, i.e. a module containing some definitions. Then in an interactive read-evaluate-print loop, CAMlog source code entered at a command line prompt is compiled and evaluated in the given context, listing information and results are displayed. Invocation may take place on the command line in the format above or in Java by the method call 'CAMlog[...].main(input,output,options)'. The system is available in two archives: - CAMlog.jar contains the whole system, and has 'CAMlog' as it's main class - CAMlogVM.jar is a runtime version with main class 'CAMlogVM' To run the compiler, the ANTLR parser generator must always be in the classpath. 2. The Interactive CAMlog Command Line Interface In a development or prototyping process, mainly the Hugs-like interactive compiler/interpreter will be used. For convenience, CAMlogCLI can be invoked though the command camlog [-options] [context_source [context_listing]] which properly sets the classpath and runs java. In the current rather rudimentary version the context is loaded once and for all at the beginning, the read-evaluate-print loop is infinite and only the evaluation results will be displayed. Future versions will have commands for control and display. 3. Separate Compliation Of An Evaluation Context Instead of a dedicated module concept the CAMlog system provides a simple but rather general means of splitting programs into parts for separate editing, storing and compilation. This mechanism is also used within the interactive programming interface. An 'evaluation context' behaves like a CAMlog term with 'hole' (meta-variable) for which some other term (the main program) can be substituted. Generally the context will contain some definitions, which will then be made available to the substituted term. The evaluation context is given by a CAMlog source file with the special form '(context)' at the place of the hole and is required to evaluate to it; to evaluate the main program in that context, i.e. to substitute for the hole, it must be compiled with the option '-context='. It is possible to enchain two or more evaluation contexts and a main program, but there is no such thing as multiple imports; a term can have only one context. There are no special namespace rules in connection with evaluation contexts, but the common block-structure visibility rules may be used to obtain private names. Note: Currently an evaluation context cannot be precompiled into a binary, but must be available in CAMlog source code format when the main program is compiled. Here is a simple example: file 'list_context.clg' contains definitions for some higher order list functions def (//) < [x] op > x . (//) < [x|xs] op > x `op` xs // op . to < n m : n <= m , [ n | n+1 `to` m ] ; [] . in (context) This is imported in the following main program option '-context=../tests/clg/list_context.clg' def product < xs > xs // * . factorial < n : product < 1 `to` n . in factorial < 6 4. CAMlog Command Line Options The compiler/interpreter system is controlled by a number of options, which may either occur in the command line, or as a directive in the source code, before any type definitions command line: CAMlog - - ... source code: option '- - ...' Options are processed sequentially, later values override earlier ones. The source code directives override the command line options. An option can be a flag (on/off) or a value, and it takes the forms - flag option is selected, equivalently -=on -=off flag option is deselected -= value option assigned These options are available in CAMlog and CAMlogCLI (a) import options -res=:...: load builtin operations from resource -ctx= evaluate in context of source (b) compilation options -typ infer pricipal type by the Hindley/Milner algorithm -myc= maximum number of iterations in typing recursive def-terms -bktrk compile the whole program in backtracking mode -ccc interpret combinator code denotationally -cam generate cam operational code -name= symbolic program name (c) binary generation options -bin= write bytecode to .CAM -binc= write combinator bytecode to .CCC (d) execution options -arg=,..., pass argument string tuple to executable program -run= on run CAMlog executable program dbg debug mode cam execution all run CAMlog executable program backtracking to all results -det deterministically reproducible run -dmp dump cam register contents after execution (e) listing options -pp prettyprint lambda and combinator code -lst=,... print listings of intermediate code, with these options ast list abstract syntax tree (lambda term code) tast list abstract syntax tree with typings ccc list categorical combinator code asm list CAM assembly language code The defaults are -typ -myc=16 -bktrk=off -ccc -cam -name=PROGRAM -run -dbg=off -all=off -det=off -dmp=off -pp=off -lst=ast,ccc These options are available in the runtime version: -arg -dbg -dmp -det 5. Fine Control Of The Interpretation Process The compilation/evaluation process consists of the following steps: (1) The parser perform syntactical analysis of the source code and generates the abstract syntax tree (AST) as an internal representation. (2) An evaluation context (possibly empty) is set (option -ctx=). (3) Resource classes containing built-ins (name bindings and type definitions) are loaded (option -res=:...:); the bindings become part of the context. (4) Type definitions are compiled, constructor and selector functions become part of the context. (5) Variable names are resolved, i.e. occurrences are linked to their definitions. (6) The principal type of the program is infered according to the Hindley / Milner / Mycroft algorithm (option -typ). (7) Variables are eliminated from the AST to obtain the categorical combinator code (CCC). (8) The combinator code is closed over the context environment and thus becomes an executable program. (9) This program can be written to a binary file (option -binc=). (10) Actual parameters for the program (option -arg=a1,...,aN) are retrieved. (11) The program can be evaluated by an implementation of the combinator code denotational semantics (option -ccc). NOTE: The CCC interpreter does not support backtracking. (12) The CCC combinator code obtained in step (7) is compiled and assembled to operational code for the categorical abstract machine (option -cam). (13) Analogous to (8), the CAM code is closed over. (14) The executable program can be written to a file (option -bin=). (15) The executable program can be evaluated to normal mode (option -run) or debug mode (option -dbg) to yield it's first result or backtracked to all results (option -all) The interpreter for the CCC format is part of this version of the CAMlog system for the sake of prototyping and testing compiler features. It is rather inefficient, in particular w.r.t. space, and supports only a subset of the language. The CCC interpreter might be abandoned in the future. Observe that there is a sublte branching in the above procedure: The executable program refered to in (14) and (15) may be either CCC or CAM code, depending on whether the '-cam' option is set. Steps (9) and (11) provide an additional option for CCC code binary generation and evaluation (options '-binc=' and '-ccc'), so that both formats can be used. 6. Calling CAMlog From Java To call the CAMlog compiler from Java and take control of the compilation process the system designer should study the main application 'CAMlog.java' and the compilation control package 'com.florianhaber.camlog.cst'. We shall now give a more detailed description for the simple case of running a precompiled binary from Java: (1) Import from these packages com.florianhaber.camlog.cam.DOM java.util.zip.* java.io.* (2) Load the CAMlog program from a file DOM.Applicable program = (DOM.Applicable) new ObjectInputStream( new GZIPInputStream( new FileInputStream("/path/to/your/binary.CAM") )) .readObject(); (3) Let the CAM virtual machine evaluate the program Object result = program.invoke( DOM.tuple(new Object[]{,...,}) ); For more information on CAMlog's representation for structured data the programmer is refered to the inner classes of com.florianhaber.camlog.cam.DOM. 7. Resources