Sail configuration system

THIRD_PARTY_FILES.md

@@ -14,6 +14,13 @@ https://github.com/asciidoctor/asciidoctor
 | ------------ | ----------------------- | ----------- |
 | MIT          | doc/asciidoc/manual.css | Asciidoctor |
 
+The following files are from cJSON https://github.com/DaveGamble/cJSON
+
+| License      | Files                   | Source |
+| ------------ | ----------------------- | ------ |
+| MIT          | lib/json/cJSON.c       | cJSON  |
+| MIT          | lib/json/cJSON.h       | cJSON  |
+
 CIL
 ===
 
@@ -113,3 +120,28 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
+
+cJSON
+=====
+
+```
+Copyright (c) 2009-2017 Dave Gamble and cJSON contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

doc/asciidoc/Makefile

@@ -18,6 +18,8 @@ SAIL_DOCS += sail_doc/bitvector_and_generic.json
 SAIL_DOCS += sail_doc/struct.json
 SAIL_DOCS += sail_doc/enum.json
 SAIL_DOCS += sail_doc/union.json
+SAIL_DOCS += sail_doc/config.json
+SAIL_DOCS += sail_config/config.json
 SAIL_DOCS += sail_doc/type_syn.json
 SAIL_DOCS += sail_doc/type_syn_xlen.json
 SAIL_DOCS += sail_doc/abstract_xlen.json
@@ -38,6 +40,10 @@ sail_doc/%.json: ../examples/%.sail
 	mkdir -p sail_doc
 	sail --no-color -doc --doc-file $< --doc-embed plain --doc-bundle $(notdir $@) $< 2> $(basename $@).warning
 
+sail_config/%.json: ../examples/%.json
+	mkdir -p sail_config
+	cp $< $@
+
 sail_doc/%.error: ../examples/%.sail
 	mkdir -p sail_doc
 	-sail --no-color $< 2> $@

doc/asciidoc/configuration.adoc

@@ -0,0 +1,48 @@
+:conf: sail_doc/config.json
+
+Sail includes a configuration system that allows building
+specifications that can be configured at either runtime (if supported
+by the Sail backend in use) or statically at build-time using a set of
+options.
+
+From the perspective of the specification author, one uses the
+`config` construct to include a value in the specification, for
+example:
+
+sail::example1[from=conf,part=body,dedent]
+
+The configuration is some key-value store with dot-separated
+hierachical keys, so we access the value stored at `foo.bar` key as
+some string value. In practice, we use JSON to represent these
+configurations. In this example, the JSON might look something like:
+
+[source,json]
+----
+include::sail_config/config.json[]
+----
+
+Which when used will cause the specification to print `"Hello,
+World!"`. If we want to statically apply this configuration (and
+convert the Sail source to OCaml), we could run the following,
+assuming the configration file is called `file.json` and the Sail file
+containing the above code is `file.sail`.
+
+[source,sh]
+----
+sail --ocaml --config file.json file.sail
+----
+
+=== Runtime Configuration with Sail to C
+
+The runtime configuration functions are included in the
+`sail_config.h` header in the `lib/json` subdirectory of the Sail
+distribution.
+
+[source,c]
+----
+void sail_config_set_file(const char *path);
+
+void sail_config_cleanup(void);
+----
+
+=== Validating Configurations with JSON Schema

doc/asciidoc/manual.adoc

@@ -27,6 +27,10 @@ include::usage.adoc[]
 
 include::language.adoc[]
 
+== Model Configuration
+
+include::configuration.adoc[]
+
 == Modular Sail Specifications
 
 include::modules.adoc[]

doc/examples/config.json

@@ -0,0 +1,5 @@
+{
+    "foo" : {
+        "bar" : "Hello, World!"
+    }
+}

doc/examples/config.sail

@@ -0,0 +1,10 @@
+default Order dec
+
+$include <prelude.sail>
+
+val example1 : unit -> unit
+
+function example1() = {
+  let some_value : string = config foo.bar;
+  print_endline(some_value);
+}

editors/sail-mode.el

@@ -32,7 +32,7 @@
 
 (defconst sail-keywords
   '("val" "outcome" "function" "type" "struct" "union" "enum" "let" "var" "if" "then" "by"
-    "else" "match" "in" "return" "register" "ref" "forall" "operator" "effect"
+    "else" "match" "in" "return" "register" "ref" "forall" "operator" "effect" "config"
     "overload" "cast" "sizeof" "constant" "constraint" "default" "assert" "newtype" "from"
     "pure" "impure" "monadic" "infixl" "infixr" "infix" "scattered" "end" "try" "catch" "and" "to" "private"
     "throw" "clause" "as" "repeat" "until" "while" "do" "foreach" "bitfield"

language/jib.ott

@@ -196,6 +196,9 @@ ctyp :: 'CT_' ::=
   | poly kid                :: :: poly
 
   | memory_writes           :: :: memory_writes
+% Used for configuration, an immutable reference to some json data
+  | json                    :: :: json
+  | json_key                :: :: json_key
 
 clexp :: 'CL_' ::=
   | name : ctyp              :: :: id
@@ -221,12 +224,16 @@ creturn :: 'CR_' ::=
   | clexp                     :: :: one
   | ( clexp0 , ... , clexpn ) :: :: multi
 
+init :: 'Init_' ::=
+  | cval                             :: :: cval
+  | json_key string0 . ... . stringn :: :: json_key
+
 instr :: 'I_' ::=
   {{ aux _ iannot }}
 % The following are the minimal set of instructions output by
 % Jib_compile.ml.
   | ctyp name                                      :: :: decl
-  | ctyp name = cval                               :: :: init
+  | ctyp name = init                               :: :: init
   | jump ( cval ) string                           :: :: jump
   | goto string                                    :: :: goto
   | string :                                       :: :: label

language/sail.ott

@@ -455,8 +455,8 @@ grammar
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 loop :: loop ::= {{ phantom }}
-  | while ::   :: while
-  | until ::  :: until
+  | while :: :: while
+  | until :: :: until
 
 internal_loop_measure :: 'Measure_' ::=
   {{ com internal syntax for an optional termination measure for a loop }}
@@ -516,8 +516,10 @@ exp :: 'E_' ::=
     {{ com the value of $[[nexp]]$ at run time }}
 
   | return exp                                        :: :: return {{ com  return $[[exp]]$ from current function }}
-  | exit exp                                          :: :: exit
-    {{ com halt all current execution }}
+  | exit exp                                          :: :: exit {{ com halt all current execution }}
+
+  | config string1 . ... . stringn                    :: :: config {{ com model configuration value }}
+
   | ref id                                            :: :: ref
   | throw exp                                         :: :: throw
   | try exp catch { pexp1 , ... , pexpn }             :: :: try

lib/json/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2017 Dave Gamble and cJSON contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+