\PARA{Main Constructs.}
\label{sec:structure}

%\subsection{General Structure}
%\input{scrib-endpoints}

%\BR\NI
The top-level grammar of a {\scribble} 
description comprises:
\begin{ITEMLL}
\item[(1)] At most one {\em preamble}, which consists of one or more
  \name{import} statements: in the {\tt GreetWorld} protocol
  we have just seen,
  %(Fig.~\ref{scrib:helloworld}) 
  this is Line 1, importing a
  message type called \name{Message}.

\item[(2)] A single {\em protocol definition} (Lines 3--6 in the
  \name{GreetWorld} protocol), which consists of the keyword
  \keyword{protocol}, the name of the protocol
  (e.g.~\name{GreetWorld}), and the main part -- the {\em protocol
    body} -- enclosed by curly braces.
\end{ITEMLL}
The protocol body consists of one or more {\em role
  declarations} followed by {\em interaction description}.  
%We illustrate these concepts below.
%%%
Roles are placeholders for %%%distinct
participating endpoints. 
%% in a given protocol.
%Each role designates a distinct endpoint in a conversation scenario
%specified in the protocol.  
When a protocol is instantiated to a concrete conversation,
each role, say \name{You}, is {\em bound} to a principal,
making the latter a participant in that
conversation.  The behaviour of this participant should
follow that of \name{You} prescribed in the protocol.  In
the {\tt GreetWorld} protocol,
%% (Listing~\ref{scrib:helloworld}),
Line 4 gives {\em role declarations}, which specifies that
the protocol description includes two endpoints,
\name{You} and \name{World}. The grammar of the role
declaration is:
\begin{lstlisting}[numbers=none]
  role role1, ..., roleN;
\end{lstlisting}
where \name{roleNamei} is a role name. This is equivalent to:
\begin{lstlisting}[numbers=none]
  role role1;
  ...
  role roleN;
\end{lstlisting}
All role names should be distinct and the order does not
matter.
%\rm \BR
 
The {\em interaction description} is the main part of the
protocol description. There is at most one such
description in a protocol specification. It specifies one
or more interactions, which belong to a syntactic category
called {\em interaction sentence}.

The grammar of interaction sentences has several forms.  Below we describe
a few basic types that appear in the current version of  {\scribble}:

\PARA{(1) Interaction,} of the form:
\begin{lstlisting}[numbers=none]
  msgType from role1 to role2;
\end{lstlisting}
\noindent which defines an {\em interaction signature} (often simply {\em
  interaction}), and reads:

\begin{quote}
  A participant playing the role \name{role1} sends a
  message of type \name{msgType} to a participant playing
  the role \name{role2} and the latter eventually receives
  the message.
\end{quote}

% In general an interaction has the following syntax:
% \begin{lstlisting}[numbers=none]
%  ValType from RoleName1 to RoleName2;
% \end{lstlisting}
% where \name{RoleName1} and \name{RoleName2} are role names
% defined in one of the enclosing protocols (see Section
% \ref{sec:nesting} for nested protocols). This line depicts
% abstractly the following situation:
% \begin{itemize}
% \item[(1)] \name{Role1} asynchronously sends a message whose value
% is of type \name{ValType}.
% \item[(2)] this message will asynchronously travel through a network and
%   is eventually received by \name{Role2}.
% \end{itemize}
%Above a {\em value type} is a type of a message value. 

\NI Above the message type \name{msgType} is imported in an enclosing
environment, and can be a base or a composite type. Base type can be a
primitive type common to many programming languages, such as
\name{int}, \name{bool}, or a user-defined type. In the current
syntax, composite message types are restricted to an operator name
applied to (possibly empty) sequence of base message
types:
%%% anyway not much detail is explained...
% \footnote{In our current language specification, we treat
%   message format logically, without determining implementation
%   details.}
\name{\small OpName(ValType1, .., ValTypeN)}. Operator
names give clarity to interaction signatures, just as object methods
determine its interaction signature in object-oriented programming.


%The following alternative syntax allows a value type to be specified
%directly with an operator name.
% or 
% \begin{lstlisting}[numbers=none]
%     invoice(Integer, Date) from Buyer to Seller;
% \end{lstlisting}
% This form is useful especially when a vector of values should be
% communicated.

% Operators play a more prominent role when we introduce the choice
% syntax.

%(it appeared in Line 5 of \name{GreetWorld}). 

%\begin{lstlisting}[numbers=none]
%    ValType from RoleName1 to RoleName2;
%\end{lstlisting}
%This will be introduced in Section \ref{sec:interaction}.

\PARA{(2) Sequencing,} of the form:
\begin{lstlisting}[numbers=none]
  I1; I2; ...; In
\end{lstlisting}
\noindent represents an interaction sentence, where if the
{\em same role name} appears in both $\mathtt{Ii}$ and
$\mathtt{I(i+k)}$, then the interaction actions of that
participant take place under a temporal order
(thus if none of the role names overlap between
$\mathtt{I1}$ and $\mathtt{In}$, then no order is
specified). This interpretation is faithful to the
asynchronous semantics of communications (formally
treated in \cite{HYC08}). For example, in:

\begin{lstlisting} 
  order(Goods) from Buyer to Seller;
  deliver(Shipment) from Seller to Supplier;
  confirm(Invoice) from Seller to Buyer;
\end{lstlisting}

\NI \name{Seller} sends an invoice to \name{Buyer} (Line 3)
only after it receives an order from \name{Buyer} and sends
a shipment order to Supplier (Lines 1, 2). \name{Buyer}
expects an invoice from \name{Seller} after it sends an
order to \name{Seller}.

%This will be introduced in Section \ref{sec:sequencing}.
\PARA{(3) Unordered} (also called {\em\bf Parallel}), of the form:
\begin{lstlisting}[numbers=none]
  I1 & I2 & ... In
\end{lstlisting}

\noindent represents interleaved interactions that may be observed in any order.
%%%
We write:
\begin{lstlisting}[numbers=none]
    msgType from role1 to role2,.., roleK;
\end{lstlisting}
for a shorthand of:
\begin{lstlisting}[numbers=none]
    msgType from role1 to role2 & .. & msgType from role1 to roleK;
\end{lstlisting}


%This will be introduced in Section \ref{sec:sequencing}.
\PARA{(4) Directed Choice,} of the form:
\begin{lstlisting}[numbers=none]
  choice from role1 to role2,.., roleK { 
    msgType1: I1 
    .. 
    msgTypen: In 
  }
\end{lstlisting}
\noindent represents interaction flow branching, where role1 makes a choice
\name{msgTypej} to continue interaction following scenario in
\name{Ij}. For example, in :
\begin{lstlisting}
  order(Goods) from Buyer to Seller;
  choice from Seller to Buyer {
    accept(Invoice): 
      payment(CardDetails) from Buyer to Seller; 
    decline(): 
      end;
  }
\end{lstlisting}

\NI After Buyer sends an order to \name{Seller}, \name{Seller} makes a
choice whether to accepts it or not. If it decides the former,
\name{Seller} returns an invoice to \name{Buyer} and subsequently waits
for a payment in return from him.

%This will be introduced in Section \ref{sec:choice}.
% \item {\em Repetition}, of the form:
% \begin{lstlisting}[numbers=none]
%   repeat @ RoleName { I };
% \end{lstlisting}
% This will be introduced in Section \ref{sec:repeat}.

\PARA{(5) Recursion,} of the form:
\begin{lstlisting}[numbers=none]
 rec BlockName { I }
\end{lstlisting}
where $\#$\name{BlockName} appears inside \name{I}
at least once, 
signifying a repetition of the whole block
%%  up to the point, where
when $\#$\name{BlockName} is encountered.
For example, in
\begin{lstlisting}
rec X {
  order(Goods) from Buyer to Seller;
  choice from Seller to Buyer {
    accept():
      ..
      #X;
    decline():
      end;
  }
}
\end{lstlisting}

\noindent \name{Seller} can
continuously accept orders from \name{Buyer}, until it decides to
decline one. When \name{Seller} declines an order, the repetition
stops.

%This will be introduced in Section \ref{sec:recur}.
\PARA{(6) Nested protocol,} of the form:
\begin{lstlisting}[numbers=none]
  run Protocol(param1,.., paramk, roleInChild1=roleInParent1,.., roleInChildn=roleInParentn);
\end{lstlisting}

\noindent represents protocol nesting. When \name{run} directive is encountered
in the interaction flow of a conversation, a new conversation is
instantiated and followed as prescribed by the nested \name{Protocol}. The
\name{Protocol} may require positional arguments, as well as role
keyword arguments, by which the roles in the \name{Protocol} are
instantiated with the roles of the enclosing protocol.

%This will be introduced in Section \ref{sec:run}.
% \item {\em Global escape}, of the form:
% \begin{lstlisting}[numbers=none]
%   try { I } catch ( Msgs ) { I1 } catch ( Msgs ) { I2 } .. catch (Msgs) { In };
% \end{lstlisting}
% This will be introduced in Section \ref{sec:escape}.

\smallskip 

{\scribble} includes other forms of interaction sentences (global
escape, delegation, repetition, etc), which we omit for brevity of
this presentation, see \cite{ScribbleDevelopmentToolSite}.



% \subsection{Type Annotations for Role Names (future extension)}

% In future we may allow a type (class) elaboration of a role
%   name declaration, writing:
% \begin{lstlisting}[numbers=none]
%   role Buyer:Bank;
% \end{lstlisting}
% which says that a participant in a conversation designated by role name
% Buyer should be a Bank.
% \begin{lstlisting}[numbers=none]
%   role roleName1:Class1, ..., roleNameN:ClassN;
% \end{lstlisting}
% which says that a principal should belong to Classi when
% it tries to participate as roleNamei.

% \subsection{Literals and Keywords} 

% \rm \BR The role names and other
%   names need be {\em literals}. A literal should start from an
%   alphabet and can contain a combination of alphabets, underscores,
%   and numerals. Capital and non-capital letters are
%   distinguished. Among the literals, {\scribble} reserve a collection
%   of keywords. The keywords treated in this document are:
%   \begin{quote}  
%     \keyword{import}, 
%     \keyword{protocol}, 
%     \keyword{role}, 
%     \keyword{from}, 
%     \keyword{to}, 
%     \keyword{seq}, 
%     \keyword{par}, 
%     \keyword{choice}, 
%     \keyword{repeat},  
%     \keyword{recur},  
%     \keyword{run}, 
%     \keyword{include} 
%   \end{quote}
%   The remaining keywords are listed in future versions.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "main"
%%% End: 
