Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 150 lines (109 sloc) 5.77 kB
fccc685 Initial open-source release
MLstate authored
1 * General informations
2
3 To know how to write programs in the DSL take a look at the example files present
4 in the directory (*.proto).
5 To translate them into ocaml modules you first need to compile protocols/genproto.ml
6 and call it as described at the end of this file.
7 This will produce a trx file and an OCaml file/module which you will use afterward
8 in your applications.
9 There are a few examples of minimalistic applications using the generated ocaml
10 module for the moment, you might want to take a look at them, they're placed in
11 libnet and libnet/test.
12
13 * More info about the DSL itself
14
15 ** The symbol "+" :
16
17 It's used to define the entering node of the automata. (there can only be one)
18
19 ** The symbol "-!-" :
20
21 It's used to close the connection (it *must* be used in the terminal nodes)
22
23 ** The commentaries
24
25 They're introduced by at least one % and continue 'til the end of the line.
26
27 ** The -generate rule
28
29 The -generate must be put in all your proto files, she takes one argument :
30 either "client" or "server". She'll be used by genproto to know what
31 to generate.
32
33 ** A word about -include, -open, -import, -set, -type and -define
34
35 -include takes a (quoted) string corresponding to a filepath, reads and
36 parse the content of the file and concat the result with the parsing of
37 the current file.
38
39 -open Open a caml module (will be placed on top of the caml generated file)
40
41 -type introduces a new type definition.
42
43 -import will add a value to the signature of the module used as a parameter
44 for the functor (when you use at least one -import, the generated module becomes
45 a functor)
46
47 -set let you define a constant.
48
49 -define is used to specifie the "form" of a message. All the definition we'll
50 be used first to define the algebraic datatype named « msg ». The default
51 parameter's type is "string" but any other simple type can be specified (option
52 type and even lists might appear later), you can also use ! as you would do
53 with teerex.
54 A function "string_of_msg" will also be generated by these defines (it will be
55 automaticaly used when you use the keword send).
56 And finally, a teerex grammar will be extracted.
57
58 For more information about how to use those keywords take a look at the few
59 example files included in the directory.
60
61 /!\ There is no reordering with these definitions, that is particulary important
62 for the teerex grammar which will be generated, a general pattern like :
63 -define RawInput str = str
64 should be put *after* any other pattern. If you don't some pattern will never
65 even be tested and it will produce some unintended results.
66
67 ** About the states :
68
69 Here the order doesn't matter, you can write them in any order you want.
70 The reordering is done automaticaly before translating into OCaml.
71
72 In a state, there are a limited numbers of constructions you can use :
73 - send: It sends a message (after serialising it) to a connection.
74 Everything that comes after a send is encapsulated in a continuation.
75
76 - send_all: Sends a list of messages. The behavior being the same than
77 with send.
78
79 - receive: It pops a message out of the queue and try to match it with
80 the different patterns specified.
81 The pattern matching behave as in caml, the only difference being,
82 when you want to introduce a guard, you must put the conditional expression
83 in verbatim (between {{ }} that is, see below).
84
85 Note: when the queue is empty it reads on the connection, encapsulate
86 everything into a continuation and parse the messages it has read with
87 trx before pushing them into the queue.
88
89 It can be extended with two optionnal construction : "catch"
90 which allow you to catch the network errors (Connection_closed, Timeout, ...)
91 defined in weblib/net.ml
92 The second one is after, which let you specify a timeout.
93
94 This extensions must be used like this :
95 receive
96 | _ -> ...
97 catch
98 | _ -> ...
99 after X -> ...
100
101 - listen({{ port_spec }},state_name): sets up the state as a listener for the
102 given Network.port_spec.
103
104 - let cnt_buff = readconn(conn,blocksize);
105 Low-level read from connection conn with blocksize:int and returning
106 (cnt:int,buff:string).
107
108 - writeconn(conn,str);
109 Write string str to connection conn.
110
111 - let conn = connect(port_spec);
112 Return a connection to port_spec.
113
114 - [[ ... ]] it's used to introduce verbatim ocaml code.
115 - {{ ... }} it's used to introduce ocaml_parser parsed ocaml code.
116 - << ... >> do the same but will be rewritten in CPS, for example :
117 let a = << foo >>
118 bar
119 will produce :
120 foo (fun a -> bar)
121 - if ... then ... else ... is kinda obvious. Notice however that
122 the condition must be put between brackets.
123 - begin ... end, introduce a block (it should soon be redondant with
124 parenthesis). It should be used in pair with the condition block if
125 you want to send something or change state inside the condition.
126 - match {{ ocaml_expr }} with | ocaml_pat -> DSL_code ;
127 Ocaml-style match. Note the ';' is obligatory.
128
129 * Example
130
131 There are two ways to generate the ml(i) and trx files from a .proto. The
132 easiest is let bld do the job for you, by calling it like this (from
133 opageneral) :
134
135 % ./bld path/to/yourFile.ml
136
137 Which will generate you yourFile.ml and yourFile_parse.trx from p/t/yourFile.proto
138 The second way is to manually use genproto, here is how :
139
140 % genproto path/to/foo.proto path/to/opageneral destination/path ml_file_name trx_file_name
141
142 This line will generate you to files : destination/path/ml_file_name.ml and
143 destination/path/trx_file_name.trx
144
145 * Complementary notes
146
147 The DSL and the Erlang language have many syntactic structures in common, you might
148 wanna use the erlang-mode (or :set filetype=erlang) when writing files using the
149 DSL.
Something went wrong with that request. Please try again.