UBF, a framework for Getting Erlang to talk to the outside world. +
UBF, a framework for Getting Erlang to talk to the outside world. This document and the corresponding open-source code repositories are based on Joe Armstrong’s original UBF site and code with an MIT license file added to the distribution. Since then, a large number of diff --git a/misc-codes/irc_plugin.con b/misc-codes/irc_plugin.con new file mode 100644 index 0000000..8c47112 --- /dev/null +++ b/misc-codes/irc_plugin.con @@ -0,0 +1,55 @@ ++NAME("irc"). + ++VSN("ubf1.0"). + ++TYPES +info() = info; +description() = description; +contract() = contract; + +ok() = ok; +bool() = true | false; +nick() = string(); +oldnick() = nick(); +newnick() = nick(); +group() = string(); +groups() = [group()]; + +logon() = logon; +proceed() = {ok, nick()}; +listGroups() = groups; +joinGroup() = {join, group()}; +leaveGroup() = {leave, group()}; +changeNick() = {nick, nick()}; +msg() = {msg, group(), string()}; + +msgEvent() = {msg, nick(), group(), string()}; +joinEvent() = {joins, nick(), group()}; +leaveEvent() = {leaves, nick(), group()}; +changeNameEvent() = {changesName, oldnick(), newnick(), group()}. + ++STATE start + logon() => proceed() & active. %% Nick randomly assigned + ++STATE active + listGroups() => groups() & active; + joinGroup() => ok() & active; + leaveGroup() => ok() & active; + changeNick() => bool() & active; + msg() => bool() & active; %% False if you have not joined a group + + EVENT => msgEvent(); %% Group sends me a message + EVENT => joinEvent(); %% Nick joins group + EVENT => leaveEvent(); %% Nick leaves group + EVENT => changeNameEvent(). %% Nick changes name + ++ANYSTATE + info() => string(); + description() => string(); + contract() => term(). + + + + + + diff --git a/ubf-user-guide.en.html b/ubf-user-guide.en.html index acda49a..2ec2225 100644 --- a/ubf-user-guide.en.html +++ b/ubf-user-guide.en.html @@ -1,6 +1,6 @@ -
Table of Contents
UBF, a framework for Getting Erlang to talk to the outside world. +
Table of Contents
UBF, a framework for Getting Erlang to talk to the outside world. This document and the corresponding open-source code repositories are based on Joe Armstrong’s original UBF site and code with an MIT license file added to the distribution. Since then, a large number of @@ -19,7 +19,7 @@ UBF(c) is a meta-level protocol used between a UBF client and a UBF server.
While the XML series of languages had the goal of having a human readable format the UBF languages take the opposite view and provide a -"machine friendly" format. UBF is designed to be easy to implement.
Figure 1. Programming By Contract
Central to UBF is the idea of a "Contract" which regulates the set of legal conversations that can take place between a client and a server. @@ -40,9 +40,7 @@ types of "glue" for making compound objects. The compound types are Tuple and List. Lastly, the operator $ (i.e. "end of object") signifies when objects are finished.
For example, the following UBF(a) object:
'person'>p # {p,"Joe",123} & {p, 'fred', 3~abc~} & $Represents the following UBF(b) term:
[{person, fred, <<"abc">>}, {person, "Joe", 123}].See Section 10.2.1, “UBF(a)” for a formal definition of the UBF(a) syntax.
Integers are sequences of bytes which could be described by the regular expression [-][0-9]+, that is an optional minus (to denote a -negative integer) and then a sequence of at least one digit. No -restrictions are made as to the precision of the integer, precision -issues will be dealt with in UBF(b).
Strings are written enclosed in double quotes. Within a string two +negative integer) and then a sequence of at least one digit.
Strings are written enclosed in double quotes. Within a string two quoting conventions are observed, " must be written \" and \ must be written \\ - no other quotings are allowed.
Uninterpreted blocks of binary data are encoded. First an integer, representing the length of the binary data is encoded, this is @@ -80,25 +78,145 @@ stack. For caching optimizations, subsequent reuse of the single character C means push register C onto the recognition stack.
See Section 10.2.2, “UBF(b)” for a formal definition of the UBF(b) syntax.
UBF(b) is a language independent type system and protocol description +language. The protocol description language allows one to specify +client server interaction in terms of a non-deterministic finite state +machine. The type system allows one to specify the asynchronous +events and synchronous request/response pairs that define transitions +of this finite state machine.
The type system and protocol description language together define the +basis of "Contracts" between clients and servers. All data sent by +both the client and the server is verified by the "Contract Manager" +(an Erlang process on the "server" side of the protocol). Any data +that violates the contract is rejected.
A UBF(b) contract is defined by 2 mandatory sections and 3 optional +sections. The mandatory sections are the "name" and the "version" of +the contract. The optional sections are the "types", the "states", +and the "anystates" of the contract.
For example, the following UBF(b) contract defines a simple IRC +(Internet Relay Chat) protocol between clients and a server:
+NAME("irc").
+
++VSN("ubf1.0").
+
++TYPES
+info() = info;
+description() = description;
+contract() = contract;
+
+ok() = ok;
+bool() = true | false;
+nick() = string();
+oldnick() = nick();
+newnick() = nick();
+group() = string();
+groups() = [group()];
+
+logon() = logon;
+proceed() = {ok, nick()};
+listGroups() = groups;
+joinGroup() = {join, group()};
+leaveGroup() = {leave, group()};
+changeNick() = {nick, nick()};
+msg() = {msg, group(), string()};
+
+msgEvent() = {msg, nick(), group(), string()};
+joinEvent() = {joins, nick(), group()};
+leaveEvent() = {leaves, nick(), group()};
+changeNameEvent() = {changesName, oldnick(), newnick(), group()}.
+
++STATE start
+ logon() => proceed() & active. %% Nick randomly assigned
+
++STATE active
+ listGroups() => groups() & active;
+ joinGroup() => ok() & active;
+ leaveGroup() => ok() & active;
+ changeNick() => bool() & active;
+ msg() => bool() & active; %% False if you have not joined a group
+
+ EVENT => msgEvent(); %% Group sends me a message
+ EVENT => joinEvent(); %% Nick joins group
+ EVENT => leaveEvent(); %% Nick leaves group
+ EVENT => changeNameEvent(). %% Nick changes name
+
++ANYSTATE
+ info() => string();
+ description() => string();
+ contract() => term().See Section 10.2.2, “UBF(b)” for a formal definition of the UBF(b) syntax.
The UBF(b) type system has user-defined types and predefined types. +User-defined types and predefined types are either primitive types or +complex types.
The primitive types are Integer, Range, Float, Binary, String, Atom, +and Reference. The complex types are Alternative, Tuple, Record, +Extended Record, and List. User-defined "complex types" are defined +recursively.
New types are defined by the notation:
X() = T
The name of the type is X and the type’s definition T is either a +user-defined type or a predefined type.
Postive and negative integer constants are expressed as in UBF(a). +Integer constants may also be expressed in other bases using Erlang +syntax.
Bounded, left unbounded, and right unbounded integer ranges are +supported.
Positive and negative float constants are supported for network +transports other than UBF(a).
Binary constants are expressed similiarly as strings in UBF(a) but +having two leading "less than brackets" and two following "greater +than brackets".
Atom constants are expressed as UBF(a) atoms. Atom constants starting +with lowercase letters do not require single quotes.
A type X is of type "T1 | T2" if X is of type T1 or if X is of type +T2.
A type {X1, X2, …, Xn} is of type "{T1, T2, …, Tn}" if X1 is of +type T1, X2 is of type T2, … and Xn is of type Tn.
A record type is syntactic sugar for a tuple of type "{name, T1, T2, +…, Tn}" where name, x, y, …, and z are atoms.
An extended record type is syntactic sugar for a tuple of type "{name, +T1, T2, …, Tn, $fields=[x,y,…,z], $extras=[T1, T2, …, Tn]}" +where name, x, y, …, and z are atoms.
Predefined types are referenced by the notation:
P()
or by the notation:
P(A1, A2, ..., An)
The name of the predefined type is P. Using the second notation, +attributes can be specified to make the predefined type more specific.
The following predefined types and optional attributes are supported:
- atom +
- +ascii
- +asciiprintable +
- +nonempty +
- +nonundefined +
- binary +
- +ascii
- +asciiprintable +
- +nonempty +
-
float
-
- +
- +no optional attributes are supported +
-
integer
-
- +
- +no optional attributes are supported +
-
list
-
- +
- +nonempty +
- proplist +
- +nonempty +
- +string +
- +ascii
- +asciiprintable +
- +nonempty +
- term +
- +nonempty
- +nonundefined +
- tuple +
- +nonempty
- +nonundefined +
- void -
[RFC5234] D. Crocker, Ed. Brandenburg, "Augmented BNF for Syntax Specifications: ABNF", RFC5234, January 2008. -
[UBF] Joe Armstrong, http://www.sics.se/~joe/ubf.html, March 2003.