forked from fredyouhanaie/etclface
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathetclface.w
234 lines (181 loc) · 8.45 KB
/
etclface.w
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
%% etclface-main.w
%% Main module of the etclface cweb files.
%% Copyright (c) 2013 Fred Youhanaie
%% All rights reserved.
%%
%% Redistribution and use in source and binary forms, with or without
%% modification, are permitted provided that the following conditions
%% are met:
%%
%% * Redistributions of source code must retain the above copyright
%% notice, this list of conditions and the following disclaimer.
%%
%% * Redistributions in binary form must reproduce the above copyright
%% notice, this list of conditions and the following disclaimer
%% in the documentation and/or other materials provided with the
%% distribution.
%%
%% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
%% "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
%% LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
%% A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
%% HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
%% SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
%% TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
%% PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
%% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
%% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
%% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\datethis
%%\pagewidth=6.5in % a4 width=8.5, less 2x1 in for margins
%%\pageheight=10in
%\fullpageheight=9in
%%\setpage
%%\parindent=0pt %% NOTE parindent messes up the code indentation
%%\parskip=1pt
\def\title{etclface - An Erlang/Tcl Interface}
\def\author{Fred Youhanaie}
\def\version{(Version 0.1)}
\ifx\pdfoutput\undefined\else
\pdfinfo{
/Title (\title)
/Author (\author)
}
\fi
@i boilerplate.w
%% \fig{file} will insert an eps/pdf picture file
\def\fig#1{
\medskip
\ifx\pdfoutput\undefined
\input epsf.tex \epsfbox{#1.eps}
\else
\pdfximage {#1.pdf}\pdfrefximage\pdflastximage
\fi
\medskip
}
%% \url will create the proper links for the PDF files.
\def\url#1{\ifx\pdfoutput\undefined\.{#1}\else\pdfURL{\.{#1}}{#1}\fi}
%% \bul provide bullet points
\def\bul{\hfil\item{\romannumeral\count255} \advance\count255 by 1}
%% the following needs to be repeated for each set of new bullet points
\count255=1
\def\etf{\.{etclface}\ }
\def\erliface{\.{erl\_interface}\ }
%% To a C programmer NULL is more familiar than Lambda.
@s NULL normal
%% Treat the various data types as reserved words when typesetting.
@s ClientData int
@s Tcl_Channel int
@s Tcl_Interp int
@s Tcl_ObjCmdProc int
@s Tcl_Obj int
@s ei_cnode int
@s ei_term int
@s ei_x_buff int
@s erlang_msg int
@s erlang_pid int
@s erlang_ref int
@s ErlConnect int
@s Erl_IpAddr int
@s EtclfaceCommand_s int
@s EtclfaceCommand_t int
@*Introduction.
\etf is a Tcl/Tk extension that exposes a minimal set of \erliface
functions. \erliface is part of the core Erlang/OTP distribution.
Just like Erlang, Tcl/Tk is a mature dynamic scripting language.
In fact both languages started over 25 years ago in the mid-eighties.
As a result of this there is a large body of applications written in the
two languages. Although there are similar applications written in both
languages, such as web servers, there are also other software that are
only available in one or the other language. \etf provides a conduit
between applications written in the two languages.
The purpose of this extension is twofold:
\count255=1
\bul To allow Erlang processes to communicate with software written in
Tcl/Tk, and
\bul to allow Tcl/Tk software to leverage the concurrent environment
provided by Erlang/OTP.
@*Implementation Notes.
There are two sets of communication modules within \erliface, the
old \.{erl\_*} ones and the newer \.{ei\_*} set. For \etf we are using the
latter.
@ {\bf \tt CWEB}. The programming language used in creating the extension is \.{CWEB},
which consists of standard \Cee\ code together with the annotations
describing the code segments. This is known as Literate Programming. The
web site \url{http://literateprogramming.com} is a good starting point
for those not familiar with the concept.
Literate Programming allows one to produce from a single source file
a typeset documentation (this note) as well as a compilable \Cee\
source code.
@ {\bf Error Handling}. All commands return \.{TCL\_OK} on success or
\.{TCL\_ERROR} on failure. Tcl scripts can use the \.{catch} command
to handle the error conditions. For all errors raised by \etf,
the \.{errorCode} variable will be set appropriately. In all cases,
\.{errorCode} will be made up of three element list, "\.{ETCLFACE\ {\it
code}\ {\it message}}". The first part distinguishes our errors from
other Tcl errors, all \etf errors will have this prefix. The second part
will be one of the error return codes from the \erliface library, such
as \.{ERL\_ERROR}, \.{ERL\_TIMEOUT} etc, but without the \.{ERL\_} prefix.
For example, if the \.{etclface::connect} command fails due to the
\.{ei\_connect\_tmo()} failing, the Tcl variable \.{errorCode} may contain
"\.{ETCLFACE\ ERROR\ \{[5]\ ei\_connect\_tmo\ failed\}}".
In addition to \.{errorCode}, the variable \.{errorInfo} may also be
set. This provides a more detailed explanation of the error condition
intended to be read by people.
More details can be found in the Tcl man pages for \.{tclvars} and \.{catch}.
@ {\bf Data Types and Data Structures}.
Tcl understands one data type only, character strings, although the
underlying commands can interpret the character strings in different ways,
and one way of combining basic types, lists.
Erlang, on the other hand, has several types, and the extension needs
to be able to convert between the types appropriately.
Here, we need to consider the data type representations within three
languages, Erlang, Tcl and \Cee\, since all conversions between Erlang
and Tcl types will be through \Cee.
Erlang lists and tuples are represented as lists in Tcl.
@ {\bf The Components}.
The basic interface is written in \Cee. The source code can be found at
the end of this document, see the section {\it The Source Code}.
There will also be an additional library written in Tcl that will provide
a higher level functionality, such as encoding and decoding of Erlang
terms to and from Tcl data types, such as lists and dictionaries.
@ {\bf Installation}. The software is available in source form and can be
downloaded, or cloned, from github, see
\url{https://github.com/fredyouhanaie/etclface}.
The build and installation is done using \.{cmake}, see
\url{http://cmake.org}.
@ {\bf Testing}. There are two sets of test scripts, one for tests initiated
from the Erlang side, and the other for tests run on the Tcl side.
The tests on the Tcl side are based on the \.{tcltest} package are located
in in the \.{Tests/} directory. The test cases are in individual Tcl
procs within the \.{etclface-testsuite.tcl} file. These tests are run via
the \.{run-testsuite.tcl} wrapper. The wrapper will run all the tests,
unless a pattern of test names is supplied on the command line.
@i etclface-code.w
@*Licensing of the Software.
\etf is free software, you can redistribute it and/or modify it
under the terms of the BSD License, see
\url{http://opensource.org/licenses/BSD-2-Clause}.
\medskip
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
\count255=1
\bul Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
\bul Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
\medskip
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS~IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@*Index.