a \texttt{C} code declares a variable of type \texttt{int}, the
name of which is \texttt{i}.
Of course, like in \texttt{C} Language, you can declare multiple boxes of the
-same type in \bbi.
+same type in \bbs.
After the creation of the box \texttt{a}, type:
\begin{verbatim}
\label{bbi-fig-connecting-black-boxes-1}
\end{figure}
-The \bbi instructions to create and execute this pipeline are :
+The \bbs instructions to create and execute this pipeline are :
\begin{verbatim}
> new Add a
> new Add b
> print $b.Out$
\end{verbatim}
-You will see the (very expected) result :
-\begin{verbatim}
-6
-\end{verbatim}
-
The first three commands build the pipeline,
the next three set \texttt{a} and \texttt{b} black boxes' inputs and the last one
prints the output of the black box \texttt{b}. The pipeline is executed before printing, because the interpreter 'knows' that the box \texttt{b}, the output of which is requested, is not up to date.
Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
Basic useful black boxes
Black boxes :
- ...
+ ASCII : ascii codes sequence to string - ...
+ Add : Adds its inputs
BoolToString [DA] : Converts a Bool (bool) into a string
- CastBoolToChar [DA] : Static cast from Bool (bool) to Char (signed c...
- CastBoolToDouble [DA] : Static cast from Bool (bool) to Double (double...
+ CastBoolToChar [DA] : Static cast from Bool (bool) to ...
+ CastBoolToDouble [DA] : Static cast from Bool (bool) to ...
...
- CastBoolToUChar [DA] : Static cast from Bool (bool) to UChar (unsigne...
- CastBoolToUInt [DA] : Static cast from Bool (bool) to UInt (unsigned...
+ CastBoolToUChar [DA] : Static cast from Bool (bool) to ...
+ CastBoolToUInt [DA] : Static cast from Bool (bool) to ...
...
- CastUIntToBool [DA] : Static cast from UInt (unsigned int) to Bool (...
- CastUIntToChar [DA] : Static cast from UInt (unsigned int) to Char (...
- CastUIntToDouble [DA] : Static cast from UInt (unsigned int) to Double...
+ CastUIntToBool [DA] : Static cast from UInt (unsigned ...
+ CastUIntToChar [DA] : Static cast from UInt (unsigned ...
+ CastUIntToDouble [DA] : Static cast from UInt (unsigned ...
...
\end{verbatim}
-\texttt{[DA]} stands for \emph{default adaptor}.
+In this long list you find many items marked \texttt{[DA]}, which stands for \emph{default adaptor}.
Once you have loaded the package \texttt{std}, you can
plug an output of type \texttt{char} into an input of type \texttt{double}.
it looks for an adequate \emph{adaptor} in the loaded packages.
In our case, as the package \texttt{std} provides the
\texttt{CastUCharToDouble} adaptor, the interpreter automatically creates an
-instance of this adaptor and place it \emph{between}
+instance of this adaptor and places it \emph{between}
the output and the input you want to connect
(however this adaptor is hidden to you,
it is embedded into the created connection and does not appear
would simply cast the value of the \texttt{char} into a \texttt{double},
however arbitrarily complex type conversion may be done.\\
\texttt{WARNING}: these adaptors are \texttt{C++ static cast}, i.e., there is, right now,
- no 'intelligent' conversion (only truncation) e.g. think to \texttt{CastDoubleToUChar}!
+ no 'intelligent' conversion (only truncation) e.g. think of \texttt{CastDoubleToUChar}!
%\begin{verbatim}
%Question (for info-dev):
\item There is an adaptor black box in the packages loaded which
converts data of the output type into data of the input type
\end{itemize}
-\item \texttt{help <package name>} does not display the adaptors of the package. To see them use : \texttt{help <package name> all}.
-including adaptors
+\item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}
+including adaptors.
\end{itemize}
\hrule
% ==========================================
\label{bbi-complex-black-boxes}
% ==========================================
-Remember the pipeline of figure
+Remind the pipeline of figure
\ref{bbi-fig-connecting-black-boxes-1}, which
computed the sum of three doubles.
You can consider it as a whole and define
\end{center}
\end{figure}
-The \bbi commands to define this complex black box are
-the following :
+The \bbs commands to define this complex black box are
+the following:
\begin{verbatim}
> load std
->
> define Add3
->
> new Add a
> new Add b
> connect a.Out b.In1
->
> author "myself"
> description "adds 3 doubles"
> input x a.In1 "first double to add"
> input y a.In2 "second double to add"
> input z b.In2 "third double to add"
> output result b.Out "output"
->
> endefine
\end{verbatim}
-Explanations :
-
-As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
-
-The command \texttt{define} then starts the definition
-of the complex box type, which will be called \texttt{Add3}.
-
-The next three lines define the pipeline,
-exactly in the same way than outside a complex box definition.
-
-The commands \texttt{author}, \texttt{description}, \texttt{input}
-and \texttt{output} are commands specific to complex boxes definition :
-
-\texttt{author} and \texttt{description} are used for the documentation
+Explanations:
+\begin{itemize}
+ \item As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in the first line.
+ \item The command \texttt{define} then starts the definition
+of the complex box type that will be called \texttt{Add3}.
+ \item The next three lines define the pipeline,
+exactly in the same way as outside a complex box definition.
+ \item The commands \texttt{author}, \texttt{description}, \texttt{input}
+and \texttt{output} are specific to complex boxes definition:
+ \begin{itemize}
+ \item \texttt{author} and \texttt{description} are used for the documentation
of the new box. You can provide multiple \texttt{author} or
\texttt{description} commands, the arguments of the commands will
be concatenated to produce the final author and description strings.
-
-\texttt{input} and \texttt{output} are used to define the inputs and outputs
-of the new complex box.
-Their syntax is the same : for each new input/output you need to say
+ \item \texttt{input} and \texttt{output} are used to define the inputs and outputs
+of the new complex box. Their syntax is the same: for each new input/output you need to say
to which internal input/output it corresponds and to provide
a help string documenting the input/output.
In our example, we define that the box \texttt{Add3} has
-three inputs : \texttt{x}, \texttt{y} and \texttt{z}.
+three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
The input \texttt{x} corresponds to the input \texttt{In1} of the
internal box \texttt{a}.
In the same way, the external input \texttt{y}
The figure \ref{bbi-fig-complex-black-box-1}
illustrates the external to internal
input/output correspondence.
-
-Finally, the \texttt{endefine} command ends the definition of the
+ \end{itemize}
+ \item Finally, the \texttt{endefine} command ends the definition of the
new box type.
+\end{itemize}
After this definition, if you ask for help
-on packages, you get :
+on packages, you get:
\begin{verbatim}
> help packages
std
\end{verbatim}
The \texttt{user} package now contains a new black box type, called
-\texttt{Add3}. If you ask for help on this type of box, you get :
+\texttt{Add3}. If you ask for help on this type of box, you get:
\begin{verbatim}
> help Add3
Complex Black Box <user::Add3>
adds 3 doubles
By : myself
* Inputs :
- 'x' <double> : first double to add
- 'y' <double> : second double to add
- 'z' <double> : third double to add
+ 'x' <double> [] : first double to add
+ 'y' <double> [] : second double to add
+ 'z' <double> [] : third double to add
* Outputs :
- 'result' <double> : output
+ 'result' <double> [] : output
* Boxes :
'a' <std::Add>
'b' <std::Add>
\end{verbatim}
-and you can use it like any other box, for example type :
+and you can use it like any other box, for example:
\begin{verbatim}
> new Add3 a
6
\end{verbatim}
-
As a side note, we can say that, for consistency reasons, it would have been better to name
-\texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3},
-since all the 'natural entry' of a box is named \texttt{In}, or \texttt{In}\emph{x} if there are more than one 'natural
-entry'
-.
+\texttt{In1}, \texttt{In2} and \texttt{In3} the inputs of the black box \texttt{Add3}. Indeed,
+by convention all the 'natural entries' of a box are named \texttt{In}, or \texttt{In}\emph{x} if there is more than one 'natural entry'.
\newline
% ==========================================
\hrule
\paragraph{Summary}
%\hrule
\begin{itemize}
-\item The \texttt{define/endefine} commands allows to define complex black box types, i.e. types of black boxes made up of other black boxes.
+\item The \texttt{define/endefine} commands allow to define complex black box types, i.e. types of black boxes made up of other black boxes.
Inside a \texttt{define/endefine} block :
\begin{itemize}
\item The \texttt{author} and \texttt{description} commands allow to document the new type of box
For consistency reasons, you are requested to prepend \texttt{bb} to the name.
For example, the \texttt{Add3} complex box we previously worked on
-can be defined in the \texttt{bbAdd3.bbs} file :
+can be defined in the \texttt{bbAdd3.bbs} file:
\begin{file}{bbAdd3.bbs}
\begin{verbatim}
adds 3 doubles
By : myself
* Inputs :
- 'x' <double> : first double to add
- 'y' <double> : second double to add
- 'z' <double> : third double to add
+ 'x' <double> [] : first double to add
+ 'y' <double> [] : second double to add
+ 'z' <double> [] : third double to add
* Outputs :
- 'result' <double> : output
+ 'result' <double> [] : output
* Boxes :
'a' <std::Add>
'b' <std::Add>
->
-and so on ...
\end{verbatim}
-If the file has the \texttt{bbs} extension, you can ommit it and just type :
+If the file has the \texttt{bbs} extension, you can omit it and just type:
\begin{verbatim}
> include Add3
\end{verbatim}
+provided that {\bbStudions} knows the path to the desired \texttt{bbs} file.
+See the section \ref{The_configuration_file} to learn about the configuration file and the way to add a new path to it. Note that, if you modify the configuration file, you will have to close {\bbStudions} and run it again, so that the new configuration be taken into account.
\subsection{Creating complex black boxes that use complex black boxes}
\label{bbi-complex-complex-black-boxes}
Of course, you can include script files in other script files,
-like in the following example :
+like in the following example:
\begin{file}{bbAdd4.bbs}
\begin{verbatim}
description "adds 4 doubles"
new Add3 a
new Add b
- connect a.Out b.In1
- input In1 a.In1 "first double to add
- input In2 a.In2 "second double to add
- input In3 a.In3 "third double to add"
+ connect a.result b.In1
+ input In1 a.x "first double to add
+ input In2 a.y "second double to add
+ input In3 a.z "third double to add"
input In4 b.In2 "fourth double to add"
output Out b.Out "output"
endefine
\end{verbatim}
\end{file}
-
-The inner boxes have they own entries (In1, In2, In3 for box a, In1, In2 for box b )\\
-Only the inputs In1, In2, In3 of box a and the input In2 of box b is of interest for the end user, but he does not want to have to
-care neither about the inner boxes name, nor about the names of their Inputs.\\
-The writer of the complex box has the ability to give these inputs a meaningful name !
-\begin{verbatim}
- input In3 a.In3 "third double to add"
- input In4 b.In2 "fourth double to add"
-\end{verbatim}
-
+Here we kept the \texttt{bbAdd3.bbs} file unchanged, so the inner box of type \texttt{Add3} \texttt{a} has the entries \texttt{x, y, z}, while the entries of the inner box \texttt{b} of type \texttt{Add} are \texttt{In1, In2}.\\
+Only the inputs \texttt{x, y, z} of box the \texttt{a} and the input \texttt{In2} of the box \texttt{b} are of interest for the end user, but he/she does not need to care neither about the inner boxes name, nor about the names of their inputs.\\
+The author of the complex box has the ability to give these inputs meaningful names (here \texttt{In1, In2, In3, In4}) and to properly document them.
\subsection{Naming Conventions}
\label{bbi-Naming Conventions}
git://git.creatis.insa-lyon.fr / bbtk.git / commitdiff