AToMPM/.manual/manual.tex

\documentclass{article}
\usepackage{indentfirst}
\usepackage{fullpage}
\usepackage{epsfig}
\usepackage{subfig}		%for more than one image per figure


%%to make table of contents entries links to corresponding text (http://tug.ctan.org/tex-archive/macros/latex/contrib/hyperref/doc/manual.pdf)
\usepackage{hyperref}
\hypersetup{colorlinks=false,pdfborder=0 0 0,breaklinks=true}

%%for well-numbered figures and equations...EX: an equation in section 4 will be numbered 4.*
\usepackage{amsmath}
\usepackage{amssymb}
\numberwithin{equation}{section}
\numberwithin{figure}{section}


%REF:: http://en.wikibooks.org/wiki/LaTeX/Customizing_LaTeX
\newcommand{\versiondate}{2016/08/31}
\newcommand{\version}{v0.20}
\newcommand{\TBC}{\textit{(To be completed) }}


\title{\textbf{AToMPM User's Manual\footnote{This file has version number \version. Last revision is dated \versiondate.}}}
\author{Rapha\"{e}l Mannadiar\\ (\texttt{raphael.mannadiar@mail.mcgill.ca}) \\ Simon Van Mierlo\\ (\texttt{simon.vanmierlo@uantwerpen.be})}
\date{\versiondate}


\begin{document}
\parindent=0cm
\renewcommand*\arraystretch{1.5}		%REF:: http://www.latex-community.org/forum/viewtopic.php?f=5&t=2708

\maketitle
\thispagestyle{empty}	%(no page number)
\newpage

\tableofcontents
\thispagestyle{empty}	%(no page number)
\newpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Client Overview}
This section gives an overview of how to interact with the client. Details about modelling, meta-modelling and model transformation activities are given in Sections~\ref{sec:m}, \ref{sec:mm} and \ref{sec:mt} respectively.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Launching the AToMPM Client}
Navigate to the URL of an instance of the AToMPM back-end such as \url{http://atompm.cs.mcgill.ca:8124/atompm} or \url{localhost:8124/atompm} (if you've installed AToMPM locally).



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The Interface Components}

\begin{figure}[h]
	\centering
	\includegraphics[scale=0.4]{figures/atompm}
	\caption{The AToMPM client, with the \textit{MainMenu} and \textit{TransformationController} button toolbars loaded.}
	\label{fig:atompm}
\end{figure}

Figure~\ref{fig:atompm} shows the AToMPM client interface. It has 5 components.\\

The \textit{Dock} (at the top) is where button and formalism toolbars reside. In Figure~\ref{fig:atompm}, two button toolbars, \textit{MainMenu} and \textit{TransformationController}, are loaded. These are respectively explored in Subsections~\ref{ssec:mainmenutb} and \ref{ssec:transfctrltb}.\\

The \textit{Canvas} (checkered area) is where models are created and edited.\\

The third and fourth components (at the lower right) are a username field and collaboration links. The former provides access to personal data stored in the cloud. The latter are used to send collaborative modelling invitations.\\

The final component is the \textit{Console} (at the bottom) which is used to provide the user with various messages and warnings. It can be shown and hidden at will. Means to do so vary from one browser to the next.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \textit{MainMenu} Toolbar} 
\label{ssec:mainmenutb}

\textbf{\#01} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_newTab} \hspace*{1cm}
Launch a new AToMPM client in a new tab.\\

\textbf{\#02} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_loadToolbar} \hspace*{1cm}
(Re-)load a button or formalism toolbar.\\

\textbf{\#03} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_dropToolbar} \hspace*{1cm}
Close a loaded toolbar.\\

\textbf{\#04} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_loadModel} \hspace*{1cm}
Load a model.\\

\textbf{\#05} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_insertModel} \hspace*{1cm}
Load a model alongside the current model.\\

\textbf{\#06} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_saveModel} \hspace*{1cm}
Save current model.\\

\textbf{\#07} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_saveModelAs} \hspace*{1cm}
Save current model as...\\

\textbf{\#08} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_undo} \hspace*{1cm}
Undo the last performed action.\\

\textbf{\#09} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_redo} \hspace*{1cm}
Redo the last undone action.\\

\textbf{\#10} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_copy} \hspace*{1cm}
Copy.\\

\textbf{\#11} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_paste} \hspace*{1cm}
Paste.\\

\textbf{\#12} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_validateM} \hspace*{1cm}
Verify abstract syntax validity constraints (if any) for all loaded formalisms.\\

\textbf{\#13} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_togglemm} \hspace*{1cm}
Choose formalisms whose entities should be made invisible.\\



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \textit{Utilities} Toolbar} 
\label{ssec:utilitiestb}
The \textit{Utilities} toolbar provides various utility features.\\

\textbf{\#01} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_exportSVG} \hspace*{1cm}
Download an SVG image representation of the current model\footnote{A temporary issue with this is that arrowheads are missing from output.}\footnote{Note that to make changes in InkScape, you must first Select All and Ungroup.}.\\

\textbf{\#02} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_cloudmgmt} \hspace*{1cm}
Load dialog for managing logged-in user's cloud data.\\

\textbf{\#03} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_download} \hspace*{1cm}
Download all of logged-in user's cloud data to local disk.\\

\textbf{\#04} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_editprefs} \hspace*{1cm}
Load dialog for customizing logged-in user's personal settings.\\




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The Canvas}	
\label{ssec:canvas}
Below is a list of various states the Canvas can be in along with lists of actions available in each state and their corresponding shortcut(s).\\

When in the \textbf{DEFAULT} state,\\

\begin{tabular}{| p{6cm}  p{10cm} |}
	\hline
	\textbf{Action} 				& \textbf{Shortcut(s)} \\ \hline \hline
	Choose an entity type to create	& Left-click on desired type from a loaded formalism toolbar. \\ 
	Create an entity				& Right-click anywhere on the Canvas. \\ 
	Select an entity				& Left-click any entity. This will also select the entity's contents, if any. To select a container without selecting its contents, SHIFT-Left-click it.\\ 
	Select one or more entity		& Left-press anywhere on Canvas, drag selection box around desired entity or entities and release. \\ 
	Connect entities				& Right-press an entity, drag to-be edge to target entity and release. \\ 
	Edit icon text					& SHIFT-Middle-click any text from any icon on the Canvas (this will display a very simple text editor).\\
	\hline
\end{tabular}
\vspace*{2em}


When in the \textbf{SOMETHING SELECTED} state (i.e., when one or more entity is selected),\\

\begin{tabular}{| p{6cm}  p{10cm} |}
	\hline
	\textbf{Action} 				& \textbf{Shortcut(s)} \\ \hline \hline
	Unselect selection				& Right-/Left-/Middle-click anywhere on the Canvas, or click ESC. \\ 
	Move selection					& Left-press selection, drag preview overlay to desired position and release. \\ 
	Delete selection				& Click DELETE. \\ 
	Edit first entity in selection	& Middle-click selection, or click INSERT, or click COMMAND (this will display the abstract attribute editor). \\ 
	Enter geometry editing mode		& Click CTRL (this will display geometry controls). \\
	Enter edge editing mode 		& Click SHIFT (this will display editable edge control points). \\
	Snap selection to nearest grid point	& Click TAB. \\
	\hline
\end{tabular}
\vspace*{2em}


When in the \textbf{DRAGGING SELECTION} state (i.e., when right-dragging one or more selected entity),\\

\begin{tabular}{| p{6cm}  p{10cm} |}
	\hline
	\textbf{Action} 				& \textbf{Shortcut(s)} \\ \hline \hline
	Insert selection into ...		& Right-release on top of the target entity. \\
	Un-insert selection from ...	& Right-release outside of current container. Containment relationships can also be deleted manually if visible. \\
	Confirm motion					& Right-release on the Canvas. \\
	Cancel motion 					& Click ESC. \\
	\hline
\end{tabular}
\vspace*{2em}


When in the \textbf{DRAWING EDGE} state (i.e., when dragging to-be edge from source to target entities),\\

\begin{tabular}{| p{6cm}  p{10cm} |}
	\hline
	\textbf{Action} 				& \textbf{Shortcut(s)} \\ \hline \hline
	Make current line horizontal/vertical	& Click TAB. \\
	Create control point 			& Left-click anywhere, or click CTRL. \\
	Delete last control point 		& Middle-click anywhere, or click ALT. \\
	Cancel current edge				& Left-release anywhere on the Canvas.\\
	\hline
\end{tabular}
\vspace*{2em}


When in the \textbf{EDGE EDITING} state,\\

\begin{tabular}{| p{6cm}  p{10cm} |}
	\hline
	\textbf{Action} 				& \textbf{Shortcut(s)} \\ \hline \hline
	Move control point 				& Left-press any control point, drag it to desired position and release. \\
	Vertically/Horizontally align control point to previous control point & Left-click any control point and click TAB. \\
	Clone control point 			& Right-click any control point. \\
	Delete control point 			& Middle-click any control point (extremities and the central control point are not removable). \\
	\hline
\end{tabular}
\vspace*{2em}


When in the \textbf{GEOMETRY EDITING} state,\\

\begin{tabular}{| p{6cm}  p{10cm} |}
	\hline
	\textbf{Action} 				& \textbf{Shortcut(s)} \\ \hline \hline
	Scale			 				& Mouse-wheel up/down on scale icon (\includegraphics[scale=0.25]{figures/geomctrl_resize}) until preview overlay reaches desired shape. \\
	Scale vertically only			& Mouse-wheel up/down on vertical scale icon (\includegraphics[scale=0.25]{figures/geomctrl_resizeH}) until preview overlay reaches desired shape. \\
	Scale horizontally only 		& Mouse-wheel up/down on horizontal scale icon (\includegraphics[scale=0.25]{figures/geomctrl_resizeW}) until preview overlay reaches desired shape. \\
	Rotate 							& Mouse-wheel up/down on rotation icon (\includegraphics[scale=0.25]{figures/geomctrl_rotate}) until preview overlay reaches desired shape. \\
	Cancel changes					& Right-/Left-/Middle-click anywhere on the Canvas, or click ESC. \\ 
	Confirm changes					& Left-click confirmation (\includegraphics[scale=0.25]{figures/geomctrl_ok}) icon. \\ 
	\hline
\end{tabular}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Collaboration}
AToMPM supports two modes of real-time distributed collaboration, namely, \textit{screenshare} and \textit{modelshare}. In the former, all collaborating developers share the same concrete and abstract syntax. This implies that if one developer moves an entity or cycles to another concrete syntax representation, the change will be replicated for all collaborators. In contrast, in the latter mode, only abstract syntax is shared. This means that all collaborators can have distinct concrete syntax representations and distinct layouts (provided layout and abstract syntax are not intricately related), and are only affected by others' abstract syntax changes (e.g., modifying abstract attribute values). 



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Tweaking Default Settings}
\label{ssec:prefs}
Several parameters can be tweaked for a more personalized user experience. Their meaning, range of possible values and defaults are detailed below:\\

\begin{tabular}{| p{4cm}  p{11cm} |}
	\hline
	\textbf{Preference Key} 		& \textbf{Meaning} \\ \hline \hline
	\texttt{autosave-delay}			& The number of seconds between current model backups, or -1 to disable time-intervalled backups. \\
	\texttt{autosave-mode}			& When set to \textit{overwrite}, automatic saving overwrites the current model on disk (i.e., has the same effect as if you'd clicked the save button from the MainMenu toolbar). When set to \textit{backup}, automatic saving saves the current model into a temporary file and does \emph{not} overwrite the current model on disk. \\
	\texttt{confirm-exit}			& When set to \textit{true}, exiting or logging out while the current model contains unsaved changes pops up a warning. \\
	\texttt{default-mt-dcl}			& The default programming language for all code in model transformation rules. \\
	\texttt{autoloaded-toolbars}	& Toolbars to load when starting a new AToMPM client. \\
	\texttt{autoloaded-model}		& Model to load when starting a new AToMPM client. \\
	\hline
\end{tabular}
\vspace*{2em}


\begin{tabular}{| p{4cm}  p{6cm} p{4.56cm} |}
	\hline
	\textbf{Preference Key} 		& \textbf{Type} 			& \textbf{Default} \\ \hline \hline
	\texttt{autosave-delay}			& integer 					& 15\\
	\texttt{autosave-mode}			& ENUM(overwrite, backup) 	& backup \\
	\texttt{confirm-exit}			& boolean 					& \textit{true} \\
	\texttt{default-mt-dcl}			& ENUM(JAVASCRIPT, PYTHON)	& PYTHON \\
	\texttt{autoloaded-toolbars}	& list of toolbar paths		& [] \\
	\texttt{autoloaded-model}		& model path 				& '' \\
	\hline
\end{tabular}





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Modelling} 
\label{sec:m}
To create a new model, load one or more formalism toolbars (via button \#2 from Subsection~\ref{ssec:mainmenutb}), and create, edit [and connect] entities (via the actions outlined in Subsection~\ref{ssec:canvas}). You can also load an existing model (via buttons \#4-5 from Subsection~\ref{ssec:mainmenutb}). Note that you do not need to pre-load formalisms to load models: all required formalisms are loaded automatically.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Creating Button Toolbar Models}
Button toolbar models are a special kind of model in the sense that they can be loaded as models \emph{and} as toolbars. Example button models are provided under \texttt{/Toolbars/}. Figure~\ref{fig:mainmenum} shows the model that defines the MainMenu button toolbar. Each entity of the \texttt{Button} type has three attributes: \texttt{name}, \texttt{tooltip} and \texttt{code}. \texttt{name} is displayed in concrete syntax and is used to resolve the file name of the button's associated toolbar icon: given \texttt{name} $n$, there should be an icon named $n.icon.png$ in the same folder as the model. \texttt{tooltip} becomes the icon's tooltip, i.e., hovering the mouse cursor over a button's toolbar icon displays the value of its \texttt{tooltip} attribute. \texttt{code} is a code snippet that is evaluated when the toolbar icon is clicked. This code must be valid JavaScript and can make use of the AToMPM Client API, detailed in the following Subsection. Finally, the layout of \texttt{Button} entities dictates their order in the toolbar: higher and leftmost buttons are shown first.\\

\begin{figure}[h]
	\centering
	\includegraphics[scale=0.4]{figures/mainmenum}
	\caption{The model that defines the MainMenu button toolbar.}
	\label{fig:mainmenum}
\end{figure}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client API}
The following functions can be accessed from within the \texttt{code} attribute of \texttt{Button} entities in button toolbar models and from the Console. Note that several button toolbar models which make exhaustive use of these functions are provided under \texttt{/Toolbars/}.

\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_compileToASMM(fname)}}
\begin{center}	{\large \texttt{function \_compileToASMM(fname)}} \end{center}

Compile a model, specified by its full path (relative to the current user's trunk), into an abstract syntax meta-model. An error message will be produced if the specified model is not a model of a formalism's abstract syntax. As of now, such models may only be expressed in the bundled \texttt{SimpleClassDiagram} or \texttt{EntityRelationship} formalisms. Also, note that a recommended (but not enforced) naming convention is that models of formalism abstract syntax be named ``$FormalismName$MM.model''.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_compileToCSMM(fname)}}
\begin{center}	{\large \texttt{function \_compileToCSMM(fname)}} \end{center}

Compile a model, specified by its full path (relative to the current user's trunk), into a concrete syntax (or icon definition) meta-model. An error message will be produced if the specified model is not a model of a formalism's concrete syntax. As of now, such models may only be expressed in the bundled \texttt{ConcreteSyntax} formalism. Note that enforced naming conventions are that models of formalism concrete syntax must be named ``$FormalismName$.$description$Icons.model'', and that exactly one concrete syntax definition should be named ``$FormalismName$.defaultIcons.model''.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_compileToPatternMM(fname)}}
\begin{center}	{\large \texttt{function \_compileToPatternMM(fname)}} \end{center}

Produce pattern abstract and concrete syntax meta-models\footnote{Pattern meta-models are discussed in Section~\ref{sec:mt}.} given an abstract syntax meta-model, specified by its full path (relative to the current user's trunk). An error message will be produced if the specified meta-model is not an abstract syntax meta-model.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_copy()}}
\begin{center}	{\large \texttt{function \_copy()}} \end{center}

Copy selected entities (if any). Note that it is impossible to copy edges if any of their extremities aren't also selected.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_exportSVG(fname)}}
\begin{center}	{\large \texttt{function \_exportSVG(fname)}} \end{center}

Prompt the user to download an SVG image representation of the current model and save it under the given filename. When \texttt{fname} is omitted, target filename defaults to ``model.svg''.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_getUserPreferences(callback[,subset])}}
\begin{center}	{\large \texttt{function \_getUserPreferences(callback[,subset])}} \end{center}

Call \texttt{callback} with the contents of the logged in user's preferences file (see Section \ref{ssec:prefs}), or a subset of it. When \texttt{subset} is defined, it should be an array of desired user's preference keys.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_httpReq(method,url,params,onresponse[,sync])}}
\begin{center}	{\large \texttt{function \_httpReq(method,url,params,onresponse[,sync])}} \end{center}

Perform a synchronous or asynchronous HTTP request given an HTTP method (GET, PUT, POST or DELETE), a URL, a key-value dictionary of parameters, and a function that should handle the request's response. The \texttt{onresponse} function should expect 2 parameters: \texttt{statusCode} and \texttt{responseData}.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_insertModel(fname)}}
\begin{center}	{\large \texttt{function \_insertModel(fname)}} \end{center}

Load a model, specified by its full path (relative to the current user's trunk), alongside the current model.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_loadModel(fname)}}
\begin{center}	{\large \texttt{function \_loadModel(fname)}} \end{center}

Load a model, specified by its full path (relative to the current user's trunk), overwriting the current model, if any.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_loadToolbar(fname)}}
\begin{center}	{\large \texttt{function \_loadToolbar(fname)}} \end{center}

(Re-)Load one or more button or formalism toolbars, specified by their full path (relative to the current user's trunk).\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_openDialog(type,args,callback)}}
\begin{center}	{\large \texttt{function \_openDialog(type,args,callback)}} \end{center}

Pop-up a dialog box for user interaction. Valid values for the \texttt{type} parameter are \texttt{\_CLOUD\_DATA\_MANAGER}, \texttt{\_DICTIONARY\_EDITOR}, \texttt{\_ENTITY\_EDITOR}, \texttt{\_ERROR}, \texttt{\_FILE\_BROWSER}, \texttt{\_LEGAL\_CONNECTIONS}, \texttt{\_LOADED\_TOOLBARS} and \texttt{\_CUSTOM}. Each type requires its own set of arguments encoded in the \texttt{args} parameter. As for the \texttt{callback} parameter, it is a one-argument function called with the sum of the user's input when and if the user ``OK''es the dialog.\\

The \texttt{\_CLOUD\_DATA\_MANAGER} dialog is used to manage user data stored within the user's personal cloud space. Its \texttt{args} parameter should be a key-value dictionary with the following optional keys: ``extensions'', ``readonly'' and ``title''. Values for the ``extensions'' key should be arrays of regular expressions describing allowed file names. When omitted, all file names are allowed. Values for the ``readonly'' key should be booleans denoting  whether or not the provided dialog should allow cloud data modifications. When omitted, modifications are allowed. Finally, the ``title'' argument is a string that denotes the dialog's title.\\

The \texttt{\_DICTIONARY\_EDITOR} dialog is used to read and edit arbitrary \textit{typed} dictionaries\footnote{See Section~\ref{ssec:types} for an example of a \textit{typed} dictionary.}. Its \texttt{args} parameter should be a key-value dictionary of the form:
\begin{verbatim}
    {
        data  	       : ``< a typed dictionary >'',
        ignoreKey      : ``< a function that takes 2 parameters, a key and a value, and 
                             returns true if they should be shown in the editing dialog >'',
        keepEverything : ``< a function that returns false if only updated key-value pairs 
                             should be remembered by the editing dialog >'',
        title          : ``< an optional dialog's title >		                             
    }
\end{verbatim}

The \texttt{\_ENTITY\_EDITOR} dialog is used to read and edit abstract entity attributes. Its \texttt{args} parameter should be a key-value dictionary of the form:
\begin{verbatim}
    {
        uri  :  ``< some entity URI >''
    }
\end{verbatim}

The \texttt{\_ERROR} dialog is used to report an error (e.g., attempting to connect elements that can not be connected) to the user. Its \texttt{args} parameter should be a string of text describing the error.\\

The \texttt{\_FILE\_BROWSER} dialog is used to browse and select files stored within the user's personal cloud space. Its \texttt{args} parameter should be a key-value dictionary with the following optional keys: ``extensions'', ``multipleChoice'', ``manualInput'' and ``title''. Values for the ``extensions'' key should be arrays of regular expressions describing allowed file names. When omitted, all file names are allowed. Values for the ``multipleChoice'' key should be booleans denoting whether or not several files can be selected simultaneously. When omitted, only one file can be selected at a time. Values for the ``manualInput'' key should be booleans denoting  whether or not manual file name entry should be permitted. When omitted, manual file name entry is disabled. Finally, the ``title'' argument is a string that denotes the dialog's title.\\

The \texttt{\_LEGAL\_CONNECTIONS} dialog is used to provide the user with a choice of legal connection types between entities he/she is trying to connect when more than one such connection type is available. Its \texttt{args} parameter should be a key-value dictionary of the form:
\begin{verbatim}
    {
        uri1          :  ``< source entity URI >'', 
        uri2          :  ``< target entity URI >'', 
        ctype         :  ``containment'' | ``visual'',
        forceCallback : true | false
    }
\end{verbatim}
The \texttt{forceCallback} argument indicates whether or not the dialog callback function should be called in the event where no legal connections are available. When unset, the default behaviour is to pop up an error.\\

The \texttt{\_LOADED\_TOOLBARS} dialog is used to select loaded button and formalism toolbars. Its \texttt{args} parameter should be a key-value dictionary with the following keys: ``multipleChoice'', ``type'' and ``title''. Values for the ``multipleChoice'' key should be booleans denoting whether or not several toolbars can be selected simultaneously. Values for the ``type'' key should be \texttt{``metamodels''}, \texttt{``buttons''} or \texttt{undefined}. Finally, the optional ``title'' argument is a string that denotes the dialog's title.\\


Last but not least, the \texttt{\_CUSTOM} dialog enables entirely user-specified dialogs. Its \texttt{args} parameter should be a key-value dictionary of the form:
\begin{verbatim}
    {
        widgets  :  [ < ..., widgetDescription_i, ... > ]
        title    : ``< an optional dialog's title >		                             
    }
\end{verbatim}
where $widgetDescription\_i$s have the form
\begin{verbatim}
    {
        id       :  ``< widgetId >'',
        type     :  ``input'',
        label    :  ``< input label >'',
        default  :  ``< default value in input field >''
    }
\end{verbatim}
for input fields, and
\begin{verbatim}
    {
        id              :  ``< widgetId >'',
        type            :  ``select'',
        choices         :  [ < ..., ``< choice_i >'', ... > ],
        multipleChoice  :  true | false
    }
\end{verbatim}
for lists of choices.
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_paste()}}
\begin{center}	{\large \texttt{function \_paste()}} \end{center}

Paste copied entities (if any). Note that copied entities may originate from another AToMPM client.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_redo()}}
\begin{center}	{\large \texttt{function \_redo()}} \end{center}

Redo the last undone action.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_saveModel([fname,backup])}}
\begin{center}	{\large \texttt{function \_saveModel([fname,backup])}} \end{center}

Persist a model, specified by its full path (relative to the current user's trunk), to the user's personal cloud space. If the \texttt{backup} flag is set, the provided filename will not be set as the current filename, and the window title will not be altered to indicate that changes have been saved. \\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_setInvisibleMetamodels(mms)}}
\begin{center}	{\large \texttt{function \_setInvisibleMetamodels(mms)}} \end{center}

Make all entities from the given formalisms, specified via their full paths (relative to the current user's trunk), invisible.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_setUserPreferences(prefs[,callback])}}
\begin{center}	{\large \texttt{function \_setUserPreferences(prefs[,callback])}} \end{center}

Update the logged in user's preferences file (see Section \ref{ssec:prefs}). \texttt{prefs} should be a key-value dictionary. Note that \texttt{prefs} need not contain keys and values for all existing user preference keys: missing keys will retain their current value.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_setTypeToCreate(fulltype)}}
\begin{center}	{\large \texttt{function \_setTypeToCreate(fulltype)}} \end{center}

Set the type of entities that will be created when the user creates new entities on the Canvas.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_spawnClient(fname,callbackURL)}}
\begin{center}	{\large \texttt{function \_spawnClient(fname,callbackURL)}} \end{center}

Spawn a new instance of AToMPM. If a model is specified via the \texttt{fname} parameter, it is loaded into the new instance. If a callback url is specified via the \texttt{callbackURL} parameter, critical information about the new instance is POSTed to it upon its creation.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_spawnHeadlessClient(context,onready,onchlog)}}
\begin{center}	{\large \texttt{function \_spawnHeadlessClient(context,onready,onchlog)}} \end{center}

\TBC.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_undo()}}
\begin{center}	{\large \texttt{function \_undo()}} \end{center}

Undo the last performed action.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_unloadToolbar(tb)}}
\begin{center}	{\large \texttt{function \_unloadToolbar(tb)}} \end{center}

Close one or more of the loaded button and formalism toolbars, specified via their full paths (relative to the current user's trunk).\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_validate()}}
\begin{center}	{\large \texttt{function \_validate()}} \end{center}

Verify abstract syntax validity constraints (if any) for all loaded formalisms.\\



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Remote API}
AToMPM also supports a limited ``Remote API'' that can be used to edit and animate models remotely, e.g., from third-party or synthesized applications. This is achieved by forwarding specially formatted HTTP queries targeted at the back-end to the client. The said queries must have the form:
\begin{verbatim}
    method  :  ``PUT''
    url     :  ``< backendURL >/GET/console?wid=< aswid >''
    data    :  {``text'': ``CLIENT_BDAPI :: < func >''}
\end{verbatim}
where $aswid$ is an identifier for the client's associated back-end abstract syntax thread (retrievable by typing \texttt{\_\_aswid} in the client Console), and $func$ is a string representation of a key-value dictionary of the form:
\begin{verbatim}
    {
        func    :  ``< Remote API function name >'',
        args  :  { < ..., < arg_i : value_i >, ... > }
    }
\end{verbatim}

The methods accessible via the Remote API are detailed below.\\

\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_highlight(args)}}
\begin{center}	{\large \texttt{function \_highlight(args)}} \end{center}
\begin{verbatim}
  args = 
    {
        asid                       :  ``< abstract syntax entity identifier >'',
        followCrossFormalismLinks  :  undefined | ``*'' | ``DOWN'' | ``UP'',
        timeout                    :  undefined | < timeout >
    }
\end{verbatim}

Highlight the given entity, specified via its abstract syntax identifier, and un-highlight any highlighted nodes. The \texttt{followCrossFormalismLinks} parameter indicates whether or not (and which) neighbours along cross-formalism links should also be highlighted. The \texttt{timeout} parameter, if specified, indicates the duration of the highlight (in milliseconds).\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_loadModelInNewWindow(args)}}
\begin{center}	{\large \texttt{function \_loadModelInNewWindow(args)}} \end{center}
\begin{verbatim}
  args = 
    {
        fname         :  ``< model file name >'',
        callback-url  :  ``< callback URL >''
    }
\end{verbatim}

A Remote API wrapper around the Client API \texttt{\_spawnClient()} function.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_tag(args)}}
\begin{center}	{\large \texttt{function \_tag(args)}} \end{center}
\begin{verbatim}
  args = 
    {
        asid     :  ``< abstract syntax entity identifier >'',
        text     :  ``< text to display >'',
        style    :  { < ..., ``< key_i : value_i >'', ...> },
        append   :  true | false,                
        timeout  :  undefined | < timeout >
        
    }
\end{verbatim}

Tag the given entity, specified via its abstract syntax identifier, with appropriately styled text \TBC, appending or overwriting existing tags. The \texttt{timeout} parameter, if specified, indicates how long the tag should be displayed (in milliseconds).\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function \_updateAttr(args)}}
\begin{center}	{\large \texttt{function \_updateAttr(args)}} \end{center}
\begin{verbatim}
  args = 
    {
        asid       :  ``< abstract syntax entity identifier >'',
        attr       :  ``< abstract attribute name >'',
        val        :  < new abstract attribute value >,
        highlight  :  true | false        
    }
\end{verbatim}

Update an attribute of the given entity, specified via its abstract syntax identifier, possibly briefly highlighting the entity to draw attention to the change.\\





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Specifying and Compiling Formalism Syntax Models} 
\label{sec:mm}
Defining new formalisms in AToMPM is a three step process. First, one must define and compile a model of the new formalism's abstract syntax. Then, one must define and compile at least one model of the new formalism's concrete syntax. Finally, one should define the new formalism's semantics, or its meaning. The first two steps are explored in this section while the third is explored in the next\footnote{Note that formalism semantics can technically be defined without model transformations (e.g., via elaborate code residing within toolbar buttons) but this is often discouraged by the Model-Driven Engineering community.}.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Defining Abstract Syntax}
AToMPM currently supports (and is bundled with) two meta-meta-models: \texttt{EntityRelationship} and \texttt{SimpleClassDiagram}. Instance models expressed in these formalisms can be compiled (via button \#2 from Subsection~\ref{ssec:compiletb}) into abstract syntax meta-models.\\

How to define a formalism's abstract syntax in terms of a [connected] collection of \texttt{Class} or \texttt{Entity} instances is beyond the scope of this manual. Refer to the meta-modelling literature or to the many abstract syntax models bundled with AToMPM. AToMPM's only particularity is the API it supports for meta-modelling constraints and actions, which is detailed in Subsection~\ref{ssec:mmmkapi}.\\

Note that, when saving models of formalism abstract syntax, a recommended (but not enforced) naming convention is that they be named ``$FormalismName$MM.model''.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Types}
%merge this in with rest of text
%. Discuss all types in types.js\\
%. Show example of \textit{typed} dictionary
\TBC



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Defining Concrete Syntax}
\begin{figure}
	\centering			
	\subfloat[]{\label{fig:forestMM}	\includegraphics[scale=0.5]{figures/forestMM}}\\
	\subfloat[]{\label{fig:forestCSMM1}	\includegraphics[scale=0.4]{figures/forestCSMM1}} 
	\subfloat[]{\label{fig:forestCSMM2}	\includegraphics[scale=0.4]{figures/forestCSMM2}}	
	\caption{(a) A very simple abstract syntax model and (b-c) two associated concrete syntax (or icon definition) models.}
	\label{fig:forestMM+CSMMs}
\end{figure}

An abstract syntax meta-model is not sufficient to load a formalism toolbar. Concrete syntax (or icons) must first be associated to the types introduced in the said meta-model. In AToMPM, this is accomplished by defining an instance model of the \texttt{ConcreteSyntax} formalism and compiling it (via button \#1 from Subsection~\ref{ssec:compiletb}) into a concrete syntax (or icon definition) meta-model that can in turn be loaded as a formalism toolbar.\\

In a formalism's concrete syntax model, each connector type $C$ (from the to-be formalism) must have an associated \texttt{ConcreteSyntax.Link} instance with its \texttt{typename} attribute set to ``$C$Link''. This \texttt{ConcreteSyntax.Link} describes the style \TBC of edges of its associated type and can define an icon (as a combination of styled \TBC primitive shapes) that will be placed at the center of the said edges. Furthermore, non-connector types $T$ (from the to-be formalism) may or may not have an associated \texttt{ConcreteSyntax.Icon} instance with its \texttt{typename} attribute set to $C$Icon. Figure~\ref{fig:forestMM+CSMMs} gives a very simple example of an abstract syntax model and two associated concrete syntax (or icon definition) models. Numerous more complex examples are bundled with AToMPM.\\

The combinations of shapes that make up edge center-pieces or entity icons can be further parametrized via \texttt{ConcreteSyntax.Icon/Link} and shape \texttt{mapper} and \texttt{parser} code attributes. The former enable icons and their contained shapes to be altered in response to changes to abstract syntax attribute values. The latter enable changes to icons and/or their contained shapes to effect changes to abstract syntax attribute values. The code stored within the \texttt{mapper} and \texttt{parser} attributes must be valid JavaScript and can make use of the AToMPM Meta-modelling API, detailed in the following Subsection.\\

Note that, when saving models of formalism concrete syntax, two naming conventions are enforced. First, they must be named ``$FormalismName$.$description$Icons.model''. Second, exactly one of them must be named ``$FormalismName$.defaultIcons.model''.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Meta-Modelling API}
\label{ssec:mmmkapi}
The following functions can be accessed from within the \texttt{mapper} and \texttt{parser} attributes of \texttt{ConcreteSyntax} entities, as well as from within abstract syntax constraints and actions (specified within \texttt{EntityRelationship} or \texttt{SimpleClassDiagram} entities).\\

For functions with \texttt{\_id} parameters, if the \texttt{\_id} parameter is omitted, the abstract syntax identifier of the entity that ``owns'' the current constraint, action, mapper, or parser, if applicable, is used. Note that in the case of abstract syntax validity constraints, there is no ``owning'' entity and an appropriate value must always be specified for the \texttt{\_id} parameter. If an invalid \texttt{\_id} parameter is ever specified, the current constraint, action, mapper, or parser is immediately interrupted and an error is presented to the user.\\


\addcontentsline{toc}{subsubsection}{\quad \texttt{function getAttr(\_attr[,\_id])}}
\begin{center}	{\large \texttt{function getAttr(\_attr[,\_id])}} \end{center}

Return the value of the given attribute from the given entity, specified via its abstract syntax identifier. If no such attribute exists, the current constraint, action, mapper, or parser is immediately interrupted and an error is presented to the user.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function getAttrNames(\_id)}}
\begin{center}	{\large \texttt{function getAttrNames(\_id)}} \end{center}

Return all attribute names of the given entity, specified via its abstract syntax identifier.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function getAllNodes([\_fulltypes])}}
\begin{center}	{\large \texttt{function getAllNodes([\_fulltypes])}} \end{center}

Return the abstract syntax identifiers of all entities whose types are contained within the \texttt{\_fulltypes} array. If it is omitted, return the abstract syntax identifiers of all entities. The notion of \textit{full types} is best explained by example: the full type of a \texttt{SimpleClassDiagram.Class} entity is ``/Formalisms/\_\_LanguageSyn\-tax\_\_/SimpleClassDiagram/SimpleClassDiagram/Class''.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function getNeighbors(\_dir[,\_type,\_id])}}
\begin{center}	{\large \texttt{function getNeighbors(\_dir[,\_type,\_id])}} \end{center}

Return neighbours of the given entity, specified via its abstract syntax identifier. The \texttt{\_dir} parameter can take on three values: ``$<$'' implies that only inbound neighbours should be returned, ``$>$'' implies that only outbound neighbours should be returned, ``*'' implies that neighbours in either direction should be returned. Finally, the \texttt{\_type} parameter can be set to indicate that only neighbours of the given \textit{full type} should be returned. The notion of \textit{full types} is best explained by example: the full type of a \texttt{SimpleClassDiagram.Class} entity is ``/Formalisms/\_\_LanguageSyntax\_\_/SimpleClassDiagram/SimpleClassDiagram/Class''.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function hasAttr(\_attr[,\_id])}}
\begin{center}	{\large \texttt{function hasAttr(\_attr[,\_id])}} \end{center}

Return \textit{true} if the given entity, specified via its abstract syntax identifier, has an attribute named \texttt{\_attr}, \textit{false} otherwise.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function print(str)}}
\begin{center}	{\large \texttt{function print(str)}} \end{center}

Print the given string to the console that launched the AToMPM back-end.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function setAttr(\_attr,\_val[,\_id])}}
\begin{center}	{\large \texttt{function setAttr(\_attr,\_val[,\_id])}} \end{center}

Update the given attribute of the given entity, specified via its abstract syntax identifier, to the given value. Note that this function is only available from within meta-modelling actions. Also, beware the fact that calls to \texttt{setAttr()} are not treated like normal model updates, i.e., they do not trigger pre-editing constraints and post-editing actions.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \textit{CompileMenu} Toolbar}
\label{ssec:compiletb}
\textbf{\#1} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_compileToCSMM} \hspace*{1cm}
Compile current model into a concrete syntax (or icon definition) meta-model).\\

\textbf{\#2} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_compileToASMM} \hspace*{1cm}
Compile current model into an abstract syntax meta-model.\\

\textbf{\#3} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_compileToPatternMM} \hspace*{1cm}
Compile an abstract syntax meta-model (and its associated icon definition meta-\hspace*{3.7cm}models) into a pattern meta-model.





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Specifying and Executing Model Transformations}
\label{sec:mt}
In AToMPM, model transformations and model transformation rules are ordinary models. The former conform to the \texttt{Transformation} meta-model, detailed in Subsection~\ref{ssec:tmm}. The latter conform to the \texttt{TransformationRule} meta-model, detailed in Subsection~\ref{ssec:trmm}.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Specifying Transformation Rule Models}
\label{ssec:trmm}
Transformation rules in AToMPM are instance models of the \texttt{TransformationRule} formalism. They are composed of one Right-Hand Side (RHS) pattern, one Left-Hand Side (LHS) pattern and zero or more Negative Application Condition (NAC) patterns. The contents of these patterns must conform to \textit{pattern meta-models}. Pattern meta-models are slightly altered versions of normal meta-models. Noteworthy alterations are:
\begin{itemize}
	\item Entities (and their icons) are augmented with \texttt{\_\_pLabel} and \texttt{\_\_pMatchSubtypes} attributes; \TBC
	\item Abstract entities are made instantiable and provided with default icons;
	\item All entity attributes other than the newly added attributes mentioned above become coded attributes: their values become matching conditions or rewriting actions \TBC. They should be valid Python or JavaScript and can make use of the AToMPM Transformation Rule API, detailed in  Subsection~\ref{ssec:trapi}.	
\end{itemize}

Note that, when saving models of model transformation rules, an enforced naming convention is that their name begin with ``R\_''.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Specifying Transformation Models}
\label{ssec:tmm}
Transformations in AToMPM are instance models of the \texttt{Transformation} formalism. They are used to specify how rules and/or transformations should be sequenced together. They are collections of connected transformation steps, where available steps are \texttt{Transformation.Rule}s, \texttt{Transformation.Transformation}s, \texttt{Transformation.Exhaust}s and \texttt{Transformation.ExhaustRandom}s.\\

\texttt{Transformation.Rule} entities ``point'' to a single rule and represent the execution of that single rule.\\

\texttt{Transformation.Transformation} entities point to a single transformation and represent the execution of all the transformations and/or rules contained within it.\\

\texttt{Transformation.Exhaust} entities point to an arbitrary number of rules and/or transformations and their execution is only considered completed when none of them are applicable, with priority given to the top-most (within the list of pointed-to rules and/or transformations) rule or transformation at each execution step.\\

\texttt{Transformation.ExhaustRandom} entities point to an arbitrary number of rules and/or transformations and their execution is only considered completed when none of them are applicable. Unlike, \texttt{Transformation.Exhaust}s, the choice of the next rule or transformation (within the list of pointed-to rules and/or transformations) is non-deterministic.\\

Transformation steps can be connected to each other via three association types: \texttt{OnSuccess}, \texttt{OnNotApplicable} and \texttt{OnFailure}. The meaning of steps $S_1$ and $S_2$ being connected by an \texttt{On***} association is that, during transformation execution, the flow of control will pass from $S_1$ to $S_2$ if the outcome of $S_1$ is \texttt{***}. For \texttt{Transformation.Rule}s, a \texttt{Success} outcome means the rule was successfully applied, a \texttt{Failure} outcome means an error occurred during rule application, and a \texttt{NotApplicable} outcome means the rule pre-condition could not be satisfied. For the three other step types, a \texttt{NotApplicable} outcome means that all contained/pointed-to rules and/or transformations completed with outcome \texttt{NotApplicable}, a \texttt{Failure} outcome means that the last executed contained/pointed-to rule or transformation completed with outcome \texttt{Failure}, and a \texttt{Success} outcome is produced otherwise.\\

Note that, when saving models of model transformations, an enforced naming convention is that their name begin with ``T\_''.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Transformation Rule API}
\label{ssec:trapi}
The following functions can be accessed from within LHS and NAC condition code, from within RHS action code, and from within attribute condition and action code. Note that this code can be specified in either Python or JavaScript\footnote{JavaScript support requires additional back-end modules. See the README file located in the source trunk or contact the maintainer of the AToMPM back-end you're using.}. The default language is specified in your preferences file (see Section~\ref{ssec:prefs}). To use an alternate language, the first line of the relevant body of code should be ``\texttt{"[<LANGUAGE>]"}'' (e.g., ``\texttt{"[PYTHON]"}''). A final difference is that while JavaScript code needs only evaluate to the desired value (e.g., \textit{true} for a condition), Python code needs to store its return value in a variable named \texttt{result} (e.g., \texttt{result = true}, as the final line of a condition).\\

\addcontentsline{toc}{subsubsection}{\quad \texttt{function getAttr(\_attr[,\_id])}}
\begin{center}	{\large \texttt{function getAttr(\_attr[,\_id])}} \end{center}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function getAllNodes([\_fulltypes])}}
\begin{center}	{\large \texttt{function getAllNodes([\_fulltypes])}} \end{center}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function getNeighbors(\_dir[,\_type,\_id])}}
\begin{center}	{\large \texttt{function getNeighbors(\_dir[,\_type,\_id])}} \end{center}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function hasAttr(\_attr[,\_id])}}
\begin{center}	{\large \texttt{function hasAttr(\_attr[,\_id])}} \end{center}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function print(str)}}
\begin{center}	{\large \texttt{function print(str)}} \end{center}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function setAttr(\_attr,\_val[,\_id])}}
\begin{center}	{\large \texttt{function setAttr(\_attr,\_val[,\_id])}} \end{center}
All of the above functions operate exactly like the functions of the same name presented in Subsection~\ref{ssec:mmmkapi} with the exception that entities may be specified via their \texttt{\_\_pLabel} as well as via their abstract syntax identifier.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function httpReq(method,host,url,data)}}
\begin{center}	{\large \texttt{function httpReq(method,host,url,data)}} \end{center}
Perform a synchronous HTTP request given an HTTP method (GET, PUT, POST or DELETE), a URL and a key-value dictionary of parameters. If \texttt{host} is undefined, the request is automatically routed to the AToMPM backend. This can be useful to make use of the Remote API from within rule code.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function isConnectionType(\_id)}}
\begin{center}	{\large \texttt{function isConnectionType(\_id)}} \end{center}

Return \textit{true} if the given entity, specified via its abstract syntx identifier or its \texttt{\_\_pLabel}, is a connection type, \textit{false} otherwise.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function session\_get(\_key)}}
\begin{center}	{\large \texttt{function session\_get(\_key)}} \end{center}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function session\_put(\_key,\_val)}}
\begin{center}	{\large \texttt{function session\_put(\_key,\_val)}} \end{center}

The \textit{Transformation Session} is a sandbox of sorts that enables miscellaneous user data to be easily accessed and stored across several rule and transformation executions. It is only ever cleared when a transformation is (re-)loaded (via button \#1 from Subsection~\ref{ssec:transfctrltb}). The above methods respectively enable retrieving and setting/updating a stored value.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function sys\_call(\_args)}}
\begin{center}	{\large \texttt{function sys\_call(\_args)}} \end{center}

Perform a system call on the machine hosting the AToMPM back-end. An example value for the \texttt{\_args} parameter is [``ls'', ``-l'']\footnote{Note that this function can be a tremendous security hazard if the AToMPM back-end is launched from a user account with unchecked privileges.}.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function sys\_mkdir(\_path)}}
\begin{center}	{\large \texttt{function sys\_mkdir(\_path)}} \end{center}

Create the given directory (or directories).\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function sys\_readf(\_path)}}
\begin{center}	{\large \texttt{function sys\_readf(\_path)}} \end{center}

Return the contents of the given file.\\
\vspace*{1em}


\addcontentsline{toc}{subsubsection}{\quad \texttt{function sys\_writef(\_path,\_content[,\_append])}}
\begin{center}	{\large \texttt{function sys\_writef(\_path,\_content[,\_append])}} \end{center}

Write \texttt{\_content} to the given file, overwriting its contents if the \texttt{\_append} attribute is set to \textit{false}.





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \textit{TransformationController} Toolbar}
\label{ssec:transfctrltb}
The \textit{TransformationController} toolbar should be used to control transformation execution.\\

\textbf{\#1} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_load} \hspace*{1cm}
Choose transformation to run.\\

\textbf{\#2} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_play} \hspace*{1cm}
Run transformation in continuous mode.\\

\textbf{\#3} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_step} \hspace*{1cm}
Run a single rule (the next rule to be run given transformation specification).\\

\textbf{\#2} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_pause} \hspace*{1cm}
Pause transformation (after currently executing rule, if any, completes).\\

\textbf{\#3} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_stop} \hspace*{1cm}
Stop transformation.\\

\textbf{\#3} \hspace*{1cm}
\includegraphics[scale=0.5]{figures/icon_toggledebug} \hspace*{1cm}
Toggle between transformation debugging on and off. \TBC




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Extending AToMPM \TBC}
how to develop plugins\\
when to use them\\

until completed, see \texttt{/<username>/\_\_Examples\_\_/Toolbars/} and \texttt{/plugins}





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\appendix
\section{Setting up the AToMPM back-end}
This section is only useful if you want to install your own copy of the AToMPM back-end locally. This, as opposed to using an online version such as the one hosted by McGill University's Modelling and Simulation Lab at \url{http://atompm.cs.mcgill.ca:8124/atompm}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installation}
For installation instructions, see the README file located in the source trunk.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Launch}
To start the AToMPM back-end, you must launch two processes from the source trunk:
\begin{enumerate}
	\item \texttt{node httpwsd.js}, and
	\item \texttt{python mt/main.py}.\\
\end{enumerate}

If you want to expose your instance of the AToMPM back-end beyond the host machine, you must allow network traffic on port 8124.
\end{document}