% ==========================================
\subsection{The commands}
% ==========================================
-In the sequel the commands entered by the user will be preceded by a prompt \textgreater){\bbStudio}.
+In the sequel the commands entered by the user will be preceded by a prompt (\texttt{>}).
To get started, type in the \texttt{Command} area:
\begin{verbatim}
> help
At start the interpreter does not know any black box.
If you type \texttt{'help packages'}, which is
-the third form of the \texttt{help} command, you get :
+the third form of the \texttt{help} command, you get:
\begin{verbatim}
> help packages
user
workspace
\end{verbatim}
-which means that the interpretor only knows one package
+which means that the interpreter only knows one package
(library of black boxes) called \texttt{user}
and which contains a black box called \texttt{workspace}.
The \texttt{user} package is an internal package of the interpreter,
\ref{bbi-writing-scripts} and
\ref{bbi-command-line-app}).
-If you type \texttt{'help workspace'}, you get :
+If you type \texttt{'help workspace'}, you get:
\begin{verbatim}
> help workspace
Complex Black Box <user::workspace>
> help Add
\end{verbatim}
-{\bbStudions} displays the appropriate html page in the 'Help' part (see figure : \ref{HelpAdd}), and the following text in the 'Message' part :
+{\bbStudions} displays the appropriate html page in the 'Help' part (see figure : \ref{HelpAdd}), and the following text in the 'Message' part:
\begin{verbatim}
Black Box <std::Add>
Adds its inputs
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 :
+After the creation of the box \texttt{a}, type:
\begin{verbatim}
> help workspace
\end{verbatim}
\end{verbatim}
This means that \bbi workspace now contains a black box named \texttt{a},
-of type \texttt{std::Add}. You can set the input \texttt{In1}
+of type \texttt{std::Add}. If you type:
+\begin{verbatim}
+> help workspace
+\end{verbatim}
+
+You get information about the actual instance \texttt{a} of the box type \texttt{std::Add}. It gives something like this:
+\begin{verbatim}
+> help a
+ Black Box 'a' <std::Add>
+ * Inputs :
+ 'BoxExecute' = '? (no adaptor found)' [Modified]
+ 'BoxProcessMode' = 'Pipeline' [Modified]
+ 'In1' = '0' [Modified]
+ 'In2' = '0' [Modified]
+ * Outputs :
+ 'BoxChange' = '? (no adaptor found)' [Out-of-date]
+ 'Out' = '0' [Out-of-date]
+\end{verbatim}
+Note that the inputs appear as \texttt{[Modified]}, since the code defining the box type includes an initialization of the inputs. On the other hand, the outputs appear as \texttt{[Out-of-date]}, as the box has not yet been executed and therefore its outputs have not been updated. See the second part of this section to learn more about the updating. For a moment, just note that one way to process the box \texttt{a} is to use the command:
+\begin{verbatim}
+> exec a
+\end{verbatim}
+
+This command does not display anything (except if the
+box itself displays something in its processing).
+It just processes the box if needed. In our case, the result can be seen as follows:
+\begin{verbatim}
+> exec a
+> help a
+ Black Box 'a' <std::Add>
+ * Inputs :
+ 'BoxExecute' = '? (no adaptor found)' [Up-to-date]
+ 'BoxProcessMode' = 'Pipeline' [Up-to-date]
+ 'In1' = '0' [Up-to-date]
+ 'In2' = '0' [Up-to-date]
+ * Outputs :
+ 'BoxChange' = '? (no adaptor found)' [Up-to-date]
+ 'Out' = '0' [Up-to-date]
+\end{verbatim}
+Note the change of status of all the inputs and outputs (\texttt{[Up-to-date]}).
+In practice, the command \texttt{exec} is useful to execute boxes that do not have any output,
+such as boxes that write something to a file or, display a
+graphical interface, and so on.
+
+Now, let us set the input \texttt{In1}
of the \texttt{Add} box \texttt{a} to the value $3.5$
by the command:
\begin{verbatim}
In the string passed to the \texttt{print} command,
each substring enclosed between a couple of \$ is considered
as the name of an output of a box.
-To process this special substrings, the interpretor :
+To process these special substrings, the interpreter:
\begin{enumerate}
\item Processes the box if needed (see below)
\item Converts the output of the box to a string if possible
%\paragraph
-Box processing is needed if :
+Box processing is needed if:
\begin{itemize}
-\item either at least input has changed since last processing
+\item either at least one input has changed since last processing
\item or the input \texttt{'BoxProcessMode'} of the box is set to
\texttt{'Always'}, which forces box reprocessing.
\end{itemize}
-Note that all boxes have an input named \texttt{'BoxProcessMode'}.
-
-Another way to process the box \texttt{a} is to issue the command :
-\begin{verbatim}
-> exec a
-\end{verbatim}
-
-however this command does not display anything (except if the
-box itself displays something in its processing).
-It just processes the box if needed.
-This command is used to execute boxes that do not have any output,
-such as boxes that write something to a file or, display a
-graphical interface, and so on. \newline
+Note that all boxes have an input named \texttt{'BoxProcessMode'}. \newline
%To exit \bbi, type :
%\begin{verbatim}
\paragraph{Summary}
%\hrule
\begin{itemize}
-\item The \texttt{include} command allows to load a package, and the complex black boxes that come with it..
-\item \texttt{help} gives help on :
+\item The \texttt{include} command allows to load a package, and the complex black boxes that come with it.
+\item \texttt{help} gives help on:
\begin{itemize}
\item Available commands if you just type \texttt{help}.
\item A particular command if you type \texttt{help <command-name>}.
\item All available packages and their boxes (without description) if you type \texttt{help packages}.
\item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
\item A particular black box type (with full description) if you type \texttt{help <box-type-name>}. In particular, \texttt{help workspace} displays information on the content of the \texttt{'workspace'} black box, which stores the boxes created by the user (by \texttt{new}).
+\item A particular black box instance (with full description, as well as the values and the status of the inputs/outputs) if you type \texttt{help <box-name>}.
\end{itemize}
%\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
\item \texttt{new}: creates an instance of a black box.
Read section \ref{bbi-deep-box} to get
more information on pipeline processing.
-First start \bbStudio and load the package \texttt{std}, typing :
+First start \bbStudio and load the package \texttt{std}, i.e. type in the 'Command' part the following command:
\begin{verbatim}
> include std
\end{verbatim}
-in the 'Command' part.
-Assume you want to compute $1+2+3$. You can do it by
+Assume you want to compute a sum of three numbers (e.g. $1+2+3$). You can do it by
chaining two \texttt{Add} boxes, as shown in figure
\ref{bbi-fig-connecting-black-boxes-1}.
\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 \texttt{b} black box output. 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.
+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.
The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
\texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
chains of boxes (see \ref{bbi-deep-box}
for details).
-
-Lets' consider an other, more image oriented, example :
+Let us consider another, more image-oriented, example :
\begin{verbatim}
> include vtk
> exec viewer
\end{verbatim}
-Some explainations : the \texttt{include} instructions load the necessary packages. \\
-
-\texttt{FileSelector} will pop a File Selector, at run time, that will out the user chosen file name. \\
-\texttt{Slider} will pop a Slider, at run time, that will out an integer, used later as a slice number.\\
-\texttt{ImageReader} will read any itk readable file, whose name is passed as a std::string, and return a pointer on an itk image.\\
-\texttt{Viewer2D} displays a plane, whose number is specified by an integer.\\
-\\
-\texttt{connect fileDialog.Out reader.In} plugs the output of the File Selector (a std::string) to the input of the reader (a std::string, too).\\
-\texttt{connect reader.Out viewer.In} plugs the output of the reader (an bbtk::any<bbitk::ImagePointer> which is a type defined by the
-itk package which can hold any itk image pointer) to the input of the Viewer (a vtkImageData *)\\
-\texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an int) to an other output (named Slide) of the viewer.\\
-\texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer that it must re process itself any time the slider is modified.\\
-\\
-\texttt{exec viewer} processes the viewer.
-
+Some explanations:
+\begin{itemize}
+ \item The \texttt{include} instructions load the necessary packages.
+ \item \texttt{FileSelector} will pop, at run time, a File Selector dialog box that will output the user-selected file name.
+ \item \texttt{ImageReader} will read any itk readable file, the name of which is passed as a std::string, and return a pointer on an itk image.
+ \item \texttt{Slider} will pop, at run time, a Slider widget that will output an integer number, used later as a slice number.
+ \item \texttt{Viewer2D} displays a plane, the number of which is specified by an integer.
+ \item \texttt{connect fileDialog.Out reader.In} plugs the output of the File Selector (a \texttt{std::string}) to the input of the reader (a \texttt{std::string}, too).
+ \item \texttt{connect reader.Out viewer.In} plugs the output of the reader \\(a \texttt{bbtk::any<bbitk::ImagePointer>} which is a type defined by the
+itk package, and which can hold any itk image pointer) to the input of the Viewer (a \texttt{vtkImageData *})
+\item \texttt{connect slider.Out viewer.Slice} plugs the output of the slider (an \texttt{int}) to an other output (named Slide) of the viewer.
+ \item \texttt{connect slider.BoxChange viewer.BoxExecute} says the viewer that it must re process itself any time the slider is modified.
+\item \texttt{exec viewer} processes the viewer.
+\end{itemize}
This would correspond to the graph in figure \ref{bbi-simplegraph}
\end{figure}
Of course, to be able to connect two boxes,
-the output and the input must be compatibles.
+the output and the input must be compatible.
You can always connect an output to an input of the \emph{same} type,
but you can do more, thanks to particular (hidden) black boxes called {\bf adaptors}.
-An adaptor is a black box which has at least one input, called \texttt{In},
-and at least one ouput called \texttt{Out} and whose role is to convert
+An adaptor is a black box that has at least one input, called \texttt{In},
+and at least one output called \texttt{Out} and the role of which is to convert
a data of the type of \texttt{In}
into a data of the type of \texttt{Out} (other inputs or outputs may serve
-to parameter the adaptor or retreive other useful information).
+to parameter the adaptor or retrieve other useful information).
Under \bbStudions, if you type :
\begin{verbatim}
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 / blobdiff