welcome: please sign in

The following 563 words could not be found in the dictionary of 7 words (including 7 LocalSpellingWords) and are highlighted below:
abbreviation   able   about   above   abstraction   Abstraction   account   accurate   across   Action   action   Actions   actions   actual   add   affect   after   afterward   again   all   allow   allowed   allows   also   alterations   ambient   an   And   and   any   Any   Application   application   applications   approach   appropriate   arbitrary   are   aren   argument   arguments   as   As   associating   assuming   at   automatic   base   be   been   before   belong   below   between   binding   bindings   blocks   body   bool   both   Building   building   built   but   By   by   call   called   can   capital   case   certain   changes   check   checked   checker   checking   class   code   complete   composition   compositional   compositionality   Conditional   configurable   configuration   configure   consistent   consists   constant   constructs   contain   Contents   context   Context   contexts   controlled   controlling   convenient   conventions   core   course   create   current   daemons   decisions   declaration   Declarations   declarations   Declare   declared   declares   default   Define   define   defined   definition   delimiters   dependent   depth   describe   describes   Description   detail   different   directive   do   documentation   Documentation   doesn   Dom   dom   domain   domains   domtool   don   double   Ds   E1   E2   E3   each   easy   Effect   effect   effectful   Effects   effects   Ei   either   else   empty   Empty   enclosed   end   enforcement   enough   environment   Environment   erasing   error   evaluates   exactly   example   expects   explicit   Expression   expression   expressions   Expressions   Extern   extern   family   features   few   file   files   first   First   flavor   flexible   follow   followed   following   For   for   form   forms   found   from   function   Function   functional   functionality   functions   future   G1   G2   generation   get   give   given   gives   global   globally   good   grammar   grammars   grammatical   grm   Grouping   Guide   hand   handlers   has   Haskell   haskell   have   hcoop   helper   here   Here   highly   hold   host   how   html   http   Identical   Identifier   if   If   implement   Implementation   implementation   implementers   implies   in   In   included   including   inconsistent   index   infer   inferred   informal   information   inherits   inject   input   inside   instance   Instead   int   Int   Integer   into   invariant   invocation   is   it   It   its   just   juxtaposition   language   languages   larger   last   lead   left   let   letter   level   lex   lexer   lexical   library   like   Like   List   Local   local   locally   lowercase   maintain   maintains   make   many   mark   match   matches   matter   may   mean   Meaning   meanings   Meanings   meant   members   merges   might   modifying   module   monad   more   Most   must   Name   names   naming   necessarily   Nested   nested   net   never   new   No   no   non   none   normal   Not   not   observably   obtained   obtaining   occur   occurrences   Of   of   On   on   once   Only   only   operations   optional   options   or   org   other   ought   output   outside   own   P1   P2   page   pain   parser   particular   passing   Pedia   performed   play   playing   Plugin   plugin   plugins   policies   potentially   precise   predicate   predicates   Predicates   prefer   presentation   primitive   Primitive   probably   problem   program   programming   proper   provides   pure   Purely   purely   purposes   quotes   rationale   read   real   really   refinement   Register   registered   Registering   rejects   related   remains   represent   represented   required   requires   returns   rich   Root   run   Same   same   satisfies   satisfy   satisified   scope   second   Second   section   security   See   see   semicolon   separate   sequence   Sequencing   sequencing   session   sessions   set   settings   should   shows   signal   similar   simplifications   since   single   slightly   sml   so   solution   Some   some   something   Sometimes   Source   source   specific   specification   specifications   src   stack   Standard   standard   start   starting   starts   statements   static   statically   strict   string   String   strings   subroutine   subroutines   subsection   substituting   subtype   Such   suffix   Suffixes   supposed   Symbol   Symbol1   Symbol2   symbols   synonym   syntactically   Syntax   T1   T2   table   Table   take   taking   tend   terminal   terminated   terms   text   that   That   the   The   their   then   there   these   These   they   They   this   This   those   time   to   together   token   Token   Tool   top   trailing   treated   try   tweak   two   tycheck   type   typed   types   Types   typing   Typing   unfolded   until   up   us   use   used   user   User   users   uses   using   usually   val   validation   value   values   Variable   variable   variables   versa   vhost   vice   virtual   want   was   we   web   well   what   when   where   which   while   whose   Wiki   will   with   Within   within   won   work   world   would   write   writes   You   you   your  

Clear message
Page Locked

DomTool / LanguageReference

This page gives an in-depth specification of the DomTool language. Most members would probably prefer the more informal presentation in DomTool/UserGuide.

1. Source code

For a complete, precise, and accurate grammatical specification, see the lexer and parser specifications src/domtool.lex and src/domtool.grm in the DomTool source code. See src/tycheck.sml for the type-checker implementation. DomTool/Building has information on obtaining the source.

2. Token conventions

In the grammars that follow, we use these lexical token class names:

Name

Description

Int

Integer constant

String

String constant (enclosed in double quotes)

Symbol

Identifier starting with a lowercase letter

CSymbol

Identifier starting with a capital letter

3. Predicates

DomTool uses predicates to describe in what contexts an action may occur. For instance, web-related actions should only occur inside the scope of a virtual host directive. Predicates are built up following the grammar in the table below, using the letter P as the non-terminal for predicates.

Meanings are given as statements that must hold about the context where an action is found. The context is represented as a stack of context IDs which have been declared with context declarations.

Syntax

Description

Meaning

Root

Root

The stack is empty.

CSymbol

Context ID

CSymbol is on the top of the stack.

^P

Suffixes

Some (not necessarily strict) suffix of the stack matches P.

!P

Not

The stack doesn't match P.

P1 & P2

And

The stack matches both P1 and P2.

(P)

Grouping

Identical to P

4. Types

Types describe expressions. As is standard in statically-typed programming languages, they are used only for validation purposes and have no real effect on the "output" of a program. The following table gives the grammar of types T. The section on expressions will give the meanings of types in terms of which expressions have which types.

Syntax

Description

Symbol

Extern type

[T]

List of Ts

T1 -> T2

Function from T1 to T2

[P]

Action allowed only when P is satisified; requires no environment variables on input and writes none of its own

[P] {CSymbol1 : T1, ..., CSymbolN : TN}

Action that requires environment variables CSymbol1, ..., CSymbolN to have the given types when run

[P] {CSymbol1_1 : T1_1, ..., CSymbol1_N : T1_N} => {CSymbol2_1 : T2_1, ..., CSymbol2_M : T2_M}

Like the last case, but the second set of typed environment variables describes what the action will write

P => T

A nested action that requires that its nested configuration satisfy P; T should be some action type

(T)

Grouping

5. Expressions

Here is the grammar of expressions E. As is standard in ML-family languages and Haskell, juxtaposition is used to represent function application, with application associating to the left.

Syntax

Description

Typing

Int

Integer constant

G |- Int : int

String

String constant

G |- String : string

[E1, ..., EN]

List

If G |- Ei : T for each Ei, then G |- [E1, ..., EN] : [T].

Symbol

Variable

G1Symbol : T, G2 |- Symbol : T.

E1 E2

Application

If G |- E1 : T1 -> T2 and G |- E2 : T1, then G |- E1 E2 : T2.

Symbol -> E

Abstraction (inferred domain type)

If G, Symbol : T1 |- E : T2, then G |- \ Symbol -> E : T1 -> T2.

Symbol : (T1) -> E

Abstraction (explicit domain type)

If G, Symbol : T1 |- E : T2, then G |- \ Symbol : (T1) -> E : T1 -> T2.

CSymbol = E

Environment variable set

See subsection on actions

Symbol <- CSymbol; E

Environment variable get

See subsection on actions

E1E2

Sequencing

See subsection on actions

E1 where E2 end

Local bindings

See subsection on actions

let E1 in E2 end

Local bindings

See subsection on actions

E1 with E2 end

Nested action

See subsection on actions

E1 with end

Empty nested action

See subsection on actions

E1 where E2 with E3 end

Nested action with local bindings

See subsection on actions

E1 where E2 with end

Empty nested action with local bindings

See subsection on actions

\\ Symbol : P -> E

Nested action abstraction

See subsection on actions

(E)

Grouping

Same as E

if E then E1 else E2 end

Conditional

G |- E : bool; G |- E1 : T1; G |- E2 : T2; T1 is a subtype of T2 or vice-versa

5.1. Actions

The DomTool language is purely functional. Like Haskell, it uses a monad to inject effectful operations into its pure core. For DomTool, this is the action monad. This monad merges two potentially separate features that tend to occur together.

First, actions are used to run code that will affect the outside world and lead to changes in the configuration of real daemons. Primitive actions like domain and vhost are the building-blocks here. They are defined by plugins. The other action forms in the table above are there just to allow the proper composition and sequencing of applications of primitive actions, which do the real work. See DomTool/Implementation for how the code to run for a particular primitive action is registered with the implementation.

Second, the action monad provides the functionality of environment variables. These are similar to UNIX environment variables, but DomTool maintains its own environment where each variable has a static type. The rationale for including environment variables in the language is that, while many actions are highly configurable, you usually only want to tweak a few of their options at a time. DomTool allows an ambient environment of default variable settings, and it provides language constructs for modifying certain variables both globally and locally.

5.1.1. Effects of the action expressions on the environment

Syntax

Effect

CSymbol = E

Environment variable CSymbol is set to the value of E, with E's type.

Symbol <- CSymbol; E

Environment variable CSymbol is read into normal variable Symbol, which inherits its type/value.

E1E2

The effect of E1 followed by the effect of E2

E1 where E2 end

The effect of E2 followed by E1, afterward erasing any environment variable alterations by E2

let E1 in E2 end

Same as E2 where E1 end

E1 with E2 end

The effect of E1 followed by E2

E1 with end

Same as E1

E1 where E2 with E3 end

The effect of E2 followed by E1 followed by E3, afterward erasing any environment variable alterations by E2

E1 where E2 with end

The effect of E2 followed by E1, afterward erasing any environment variable alterations by E2

\\ Symbol : P -> E

No effect until called

E1 with E2 end, when E1 is a nested abstraction function

The effect of E1 followed by E2 followed by the effect of the action obtained by substituting the value of E2 in the body of the abstraction to which E1 evaluates.

5.1.2. Nested action functions

Sometimes it is convenient to be able to write new nested actions that call primitive nested actions as subroutines. For instance, the dom helper function uses domain as a subroutine. Standard functions aren't good enough for these purposes, since they don't allow us to take into account the different environment effects that different nested action arguments might have. The nested function type P => T is the solution to this problem.

You can define a nested action function with the \\ Symbol : P -> E form. Such a function has type P => T when assuming that Symbol has type [P] implies that E has type T. Any call to this function will be typed taking into account that we play the argument action's effect before playing the effect of the function's body.

5.2. Extern types

Extern types (which are also used to implement "primitive types" like int and string) have something of the flavor of dependent types or refinement types. Registering appropriate handlers from a plugin can create an extern type whose values are controlled by an arbitrary predicate. Plugin implementers are supposed to maintain the invariant that the predicate controlling an extern type is never observably inconsistent in the course of a single type-checking session. That is, it never once declares a value to belong to type T and also declares it not to belong to T in the same type-checker invocation. A good example is the your_domain type, which consists of those strings naming domains that the current user is allowed to configure. Within a single type-checking, the user remains constant, and so your_domain's predicate returns consistent decisions. On the other hand, across different sessions by different users, the predicate will of course make different decisions. This approach allows extern types to be used for flexible type-level enforcement of security policies.

It would be a pain for users to have to mark exactly which extern type a certain expression is meant to belong to. Instead, the DomTool language implementation uses slightly non-compositional type-checking to make use of rich extern types more convenient. By "non-compositional", I mean that the value of an expression, not just its type, may matter in type-checking a larger expression that it is found within. This non-compositionality is only used to infer when a value was given a base type like string when it really ought to have been given some rich extern type. For instance, when a function is called that expects an argument of type your_domain, the argument is first type-checked. If its inferred type is your_domain, then all is well. If not, then we try again, passing the actual argument expression to your_domain's controlling predicate. Only if that predicate also rejects the expression do we signal a type error. No simplifications are performed on an expression before checking its form; for instance, a global variable's definition won't be unfolded to check if the value satisfies a required predicate.

6. Declarations

Declarations D add new symbols to the typing environment.

Syntax

Description

Effect on typing environment

extern type Symbol

Extern type

Register Symbol as a new extern type that is either defined in a plugin or treated purely syntactically.

extern val Symbol : T

Extern value

Register Symbol as a new variable that is either defined in a plugin or treated purely syntactically.

val Symbol = E

Expression synonym

Define Symbol as an abbreviation for E; a specific type for the binding is inferred and used at future occurrences.

val Symbol : T = E

Expression synonym

Define Symbol as an abbreviation for E of type T.

context CSymbol

Context ID

Declare a new context ID CSymbol.

7. Source files

A source file is an optional documentation string, followed by a sequence of semicolon-terminated declarations with optional trailing documentation strings, followed by an optional expression. A documentation string is any text between {{ and }} delimiters and may contain HTML.

Documentation strings are used in automatic HTML documentation generation. A documentation string that starts a file is used to describe that file in the module index, and it's also included at the start of that file's page. A documentation string after a declaration is used to describe it in the detail section of its file's page. The standard library documentation shows an example output.

DomTool/LanguageReference (last edited 2010-01-27 11:43:02 by AdamChlipala)