#LyX 1.1 created this file. For more info see http://www.lyx.org/ \lyxformat 218 \textclass article \language english \inputencoding latin1 \fontscheme times \graphics default \float_placement h \paperfontsize default \spacing single \papersize Default \paperpackage a4 \use_geometry 0 \use_amsmath 0 \paperorientation portrait \secnumdepth 3 \tocdepth 3 \paragraph_separation skip \defskip medskip \quotes_language english \quotes_times 2 \papercolumns 2 \papersides 1 \paperpagestyle fancy \layout Title \size huge Rascal \size default \newline the Advanced Scientific CALculator \newline \latex latex \backslash vspace{.5cm} \latex default Internal Moduleguide \latex latex \backslash vspace{.5cm} \layout Author Sebastian Ritterbusch \layout Section Introduction \layout Standard Rascal was designed with modularity in mind. Existing C or C++ code should be easy to add to the system and then be accessible and usable through Rascal. This guide will explain how to add new modules to Rascal. \layout Section Concept \layout Standard Rascal offers a parser together with basic datatypes. Functions are defined on these datatypes and provide the basic functionality. Modules can add new datatypes or new functions or just overload existing functions, even with different resulting type if necessary. Modules should provide documentation which will be included into the user manual. Modules should just depend on the generic datatypes so they can combined arbitrarily. \layout Standard Modules are registered in the file \emph on value.in \emph toggle , which is the top-level \emph on in \emph toggle -file. In the directory \emph on modules \emph toggle there are the \emph on in \emph toggle -files for the different modules along with all other files necessary for the different modules. The \emph on in \emph toggle -files specify which other files are needed for this module, define new datatypes and functions for them or basic types. Based on these files \emph on parsevalue \emph toggle generates a C++ class \emph on value \emph toggle in \emph on value.out \emph toggle that incorporates all different datatypes, along with \emph on value.cpp \emph toggle that has the necessary static functions. Besides that the documentation is prepared in \emph on value.tex \emph toggle as well as the files \emph on value.fn* \emph toggle which are used to export function definitions to the parser. \layout Standard In general the class \emph on value \emph toggle should behave like all the datatypes included into the class, thus in general you won't have to change existing code. But there are some small things that are different: The comparism-operators do not return \emph on integer \emph toggle or \emph on bool \emph toggle but \emph on value \emph toggle which you currently have to cast to \emph on integer \emph toggle using the \emph on asINTEGER() \emph toggle member method. \layout Standard The parser which is defined in \emph on hoc.y \emph toggle and \emph on scan.l \emph toggle is completely separated from the modules and along with the symbol-table which is defined in the \emph on symtab \emph toggle -files this is the core structure of Rascal. \layout Section Creating a new Module \layout Standard The minimal requirement for a new module is just an \emph on in \emph toggle -file as shown in figure \begin_float wide-fig \layout LyX-Code TYPES \layout LyX-Code MINI int \layout LyX-Code END \layout LyX-Code \layout LyX-Code UNARYFUNCTIONS \layout LyX-Code mini MINI INTEGER a \layout LyX-Code output STRING MINI a?string("1"):string("0") \layout LyX-Code END \layout LyX-Code \layout LyX-Code BINARYFUNCTIONS \layout LyX-Code and MINI MINI MINI a&b \layout LyX-Code or MINI MINI MINI a|b \layout LyX-Code END \layout LyX-Code \layout LyX-Code PROCEDURES \layout LyX-Code one MINI 1 \layout LyX-Code END \layout Caption A minimalistic Module \begin_inset LatexCommand \label{Abb:Minimalistic Module} \end_inset \end_float \begin_inset LatexCommand \ref{Abb:Minimalistic Module} \end_inset , but generally a module will consist of each a \emph on cpp \emph toggle , \emph on hpp \emph toggle , \emph on in \emph toggle and \emph on tex \emph toggle -file; as an example an \emph on in \emph toggle -file for a Taylor arithmetic is in figure \begin_float wide-fig \layout LyX-Code CPP modules/valuetaylor.cpp \layout LyX-Code HPP modules/valuetaylor.hpp \layout LyX-Code TEX modules/valuetaylor.tex \layout LyX-Code \layout LyX-Code TYPES \layout LyX-Code TAYLOR valuetaylor \layout LyX-Code END \layout LyX-Code \layout LyX-Code UNARYFUNCTIONS \layout LyX-Code taylor TAYLOR MATRIX (matrixtotaylor(a)) \layout LyX-Code output STRING TAYLOR (output(a)) \layout LyX-Code END \layout LyX-Code \layout LyX-Code BINARYFUNCTIONS \layout LyX-Code add TAYLOR TAYLOR TAYLOR (a+b) \layout LyX-Code add TAYLOR * TAYLOR (va+b) \layout LyX-Code sub TAYLOR TAYLOR * (a+vb) \layout LyX-Code sub TAYLOR TAYLOR TAYLOR (a-b) \layout LyX-Code sub TAYLOR * TAYLOR (va-b) \layout LyX-Code sub TAYLOR TAYLOR * (a-vb) \layout LyX-Code mul TAYLOR TAYLOR TAYLOR (a*b) \layout LyX-Code mul TAYLOR * TAYLOR (va*b) \layout LyX-Code mul TAYLOR TAYLOR * (a*vb) \layout LyX-Code div TAYLOR TAYLOR TAYLOR (a/b) \layout LyX-Code div TAYLOR * TAYLOR (va/b) \layout LyX-Code div TAYLOR TAYLOR * (a/vb) \layout LyX-Code cell VALUE TAYLOR INTEGER (b<=a.dim()&&b>0)?a(b-1):value() \layout LyX-Code END \layout Caption Example for an \emph on in \emph toggle -file of a Taylor Arithmetic \begin_inset LatexCommand \label{Abb:TaylorModule} \end_inset \end_float \begin_inset LatexCommand \ref{Abb:TaylorModule} \end_inset . The \emph on in \emph toggle -files are split into sections, which don't have to be in a specific order, but it might be useful to have the newly defined types and corresponding files in the top of the file. Some Sections are lists others have just one parameter. \layout Subsection The Type Section \layout Standard This list defines new datatypes; first the internal name which should be in capitals by convention, the second word specifies the representation in C++. Non of the two words may contain spaces and it is advisable to generally typecast templates to single words, like \emph on valuetaylor \emph toggle is nothing else as \emph on taylor \emph toggle , this should be done in the corresponding \emph on hpp \emph toggle -file. If any other \emph on #include \emph toggle s are needed, these should also be \emph on #include \emph toggle d in the \emph on hpp \emph toggle -file. In case you just want to add a C++ function on existing datatypes, you might not need this section. \layout Subsection CPP-, HPP-, TEX-Section \layout Standard Here you can specify the corresponding files. These are optional like all other sections and again there mustn't be any spaces in the paths. The \emph on hpp \emph toggle -file should contain necessary \emph on #include \emph toggle s and \emph on typedef \emph toggle s, the \emph on cpp \emph toggle -file additional necessary functions. The \emph on tex \emph toggle -file should contain user-documentation and will be linked to all other documentation. Therefore the \emph on tex \emph toggle -file should start with a new \emph on \backslash subsection{Modulename} \emph toggle and explain how the module works along with examples. The command \emph on make doc \emph toggle will update the user guide. \layout Subsection Unary Functions \layout Standard There are four kinds of unary functions: \layout Itemize Constructors, to create expressions of the new type using existing types \layout Itemize Unary operators (like \begin_inset Quotes eld \end_inset negative \begin_inset Quotes erd \end_inset \emph on operator- \emph toggle or \begin_inset Quotes eld \end_inset logical not \begin_inset Quotes erd \end_inset \emph on operator! \emph toggle ); be aware that C++ uses the exclamation mark \begin_inset Quotes eld \end_inset ! \begin_inset Quotes erd \end_inset where Rascal uses the tilde \begin_inset Quotes eld \end_inset \i \~{ } \begin_inset Quotes erd \end_inset as the exclamation mark is used for factorials (for which Rascal calls the unary function \emph on fac \emph toggle ). \layout Itemize Usual functions that compute something and will be available in Rascal \layout Itemize The output function, which is needed to define how the new type can be printed \layout Standard Each line consists of a function, the first word is the name of the function, the second the return type, the third the type of the operand and the fourth defines the code that does the work. Again no spaces are allowed within words, thus complicated functions should be in the corresponding \emph on cpp \emph toggle -file, which are called here. The result and operand-type have to be defined before and in the C++ part the value of the operand is in the variable \emph on a \emph toggle , which is of corresponding C++ type of the operand type. Instead of a type-name a wildcard \begin_inset Quotes eld \end_inset * \begin_inset Quotes erd \end_inset as an operand type. Then this overload will be used if there is no other overload fits better. Then the C++ code mustn't use the variable \emph on a \emph toggle , which type would be undefined, but the variable \emph on va \emph toggle of the C++ type \emph on value \emph toggle . \layout Standard If a function is defined a second time with the same type in the argument, the last one will be used; thus as an example all generic methods can be overridden. An example for this is in the \emph on ifraction \emph toggle -module, where the division between two \emph on integer \emph toggle s was overridden to have a constructor for \emph on ifraction \emph toggle s. \layout Subsubsection Implemented operators and predence \layout Standard The following table shows the predence of the operators and on which C++ functions they are mapped to. \layout Standard \added_space_top 0.3cm \added_space_bottom 0.3cm \align center \begin_inset Tabular \begin_inset Text \layout Standard Operator \end_inset \begin_inset Text \layout Standard C++-Function \end_inset \begin_inset Text \layout Standard = \end_inset \begin_inset Text \layout Standard \end_inset \begin_inset Text \layout Standard ?: \end_inset \begin_inset Text \layout Standard \end_inset \begin_inset Text \layout Standard <,<=,>,>= \end_inset \begin_inset Text \layout Standard less, lesseq, \end_inset \begin_inset Text \layout Standard \end_inset \begin_inset Text \layout Standard greater, greatereq \end_inset \begin_inset Text \layout Standard ==,!= \end_inset \begin_inset Text \layout Standard eq,neq \end_inset \begin_inset Text \layout Standard & \end_inset \begin_inset Text \layout Standard And \end_inset \begin_inset Text \layout Standard | \end_inset \begin_inset Text \layout Standard Or \end_inset \begin_inset Text \layout Standard +,- \end_inset \begin_inset Text \layout Standard add, sub \end_inset \begin_inset Text \layout Standard - \end_inset \begin_inset Text \layout Standard neg \end_inset \begin_inset Text \layout Standard *,/,% \end_inset \begin_inset Text \layout Standard mul, div, mod \end_inset \begin_inset Text \layout Standard \i \^{ } ,',!,\i \~{ } \end_inset \begin_inset Text \layout Standard pow, transpose, fac, Not \end_inset \begin_inset Text \layout Standard \begin_inset Formula \( \cdot (\cdot ) \) \end_inset \end_inset \begin_inset Text \layout Standard cell \end_inset \end_inset \layout Standard To simplify the use of the \emph on value \emph toggle -class, the usual operators will be defined as front-ends to these functions where possible. Thus you may add two \emph on value \emph toggle -variables as \begin_inset Formula \( a+b \) \end_inset and this will invoke the corresponding add( \begin_inset Formula \( a \) \end_inset , \begin_inset Formula \( b \) \end_inset ). Note that some functions are upper case when the lower case version is a key-word in C++. \layout Subsection Binary Functions \layout Standard Here binary functions and binary operators can be defined. To this section the same rules apply like for unary functions, only that there are now two operands that follow the result-type. A special function is the \emph on cell \emph toggle --function which is being invoked when a user applies the parentheses to an expression of this type. If the user invokes \emph on cell \emph toggle two-dimensionally, like \begin_inset Formula \( A(1,2) \) \end_inset then this is being mapped to \begin_inset Formula \( cell(cell(A,1),2) \) \end_inset . \layout Subsection Implicit Casts \layout Standard It would be a bit tedious and sometimes even impossible to define all functions for all datatypes, but p.e. one expects that fractions can be used with intervals, even if both modules don't know of each other. This can be achieved if rascal gets informations on how to convert datatypes into each other. In above example the best would be to define how fractions can be converted to doubles. But it has to be said that casts take time and for the common cases specialized functions should be defined. Reasonable implicit casts for the \emph on ifraction \emph toggle -module are shown in figure \begin_float wide-fig \layout LyX-Code IMPLICITCAST \layout LyX-Code IFRAC INTEGER (ifraction(a)) \layout LyX-Code DOUBLE IFRAC (double(a.num)/a.den) \layout LyX-Code END \layout Caption Implicit cast section of \emph on ifraction.in \begin_inset LatexCommand \label{fig: ImplicitCastExample} \end_inset \end_float \begin_inset LatexCommand \ref{fig: ImplicitCastExample} \end_inset . As a source object also a wildcard may be used, but this may lead to unexpected results. Generally casts that are defined later are being preferred, thus you might need to redefine casts you are not planning to override. \layout Subsection Procedures \layout Standard Procedures are functions that return a value but do not take any arguments. This concept is helpful for help messages or internal status reports. \layout Subsection Special Functions \layout Standard Besides the operators there are other special named functions that can be overidden: \layout Subsubsection \family typewriter parseInteger VALUE STRING \layout Standard As soon the scanner identifies an Integer, this function is being called with the string of the number as argument. If the default conversion to integers does not suit your needs, override this function with a suitable method taking a string and returning a value. \layout Subsubsection \family typewriter parseDouble VALUE STRING \layout Standard This function should convert a string that was identified as a floating point number into a value. If the standard conversion to double does not satisfy you, override this function. \layout Section Questions? \layout Standard Please send questions, ideas, hints, critics and congratulations to \emph on rascal@ritterbusch.de \emph toggle . \the_end