Command-line help for the black box scripting language \bbs (see section \ref{Scripting}) can be obtained in this zone. \par
As mentioned above, the command (or button) \texttt{help} permits to print in the \texttt{Message} zone the list of all recognized commands, while the command \texttt{help} \emph{command\_name} displays in this zone the help about the selected command.\par
The command \texttt{help} \emph{package\_name} displays in the \texttt{Message} zone a short information about the selected package, provided that this package was previously loaded (Note that you can know which packages were loaded by executing the command \texttt{help packages}). Furthermore, it simultaneously displays in the right zone (\texttt{Help}) the corresponding full html help available.\par
-In a similar way, one can obtain the information about any box from the loaded packages, by executing the command \texttt{help} \emph{box\_name}. Note that some boxes may be unavailable if the command \texttt{load} was used to load the package, since this command only loads the boxes in binary. Some boxes are defined in script files. To be sure that all the boxes from the package are loaded the command \texttt{include} is to be preferred.\par
-You can also get the list of the objects currently present in the workspace, by executing the command \texttt{help workspace}.
+In a similar way, one can obtain the information about any box from the loaded packages, by executing the command \texttt{help} \emph{box\_name}. Note that some boxes may be unavailable if the command \texttt{load} was used to load the package, since this command only loads the boxes defined in binary files (dynamic libraries). Some boxes are defined in script files. To be sure that all the boxes from the package are loaded the command \texttt{include} is to be preferred.\par
+
+It is important to note that the black boxes are implemented and have to be used according to the {\bf\emph{object-oriented}} programming principles. This means that you have to make difference between a black box {\bf\emph{type}} and an {\bf\emph{instance}} of the given black box type. The former defines a ``pattern'' (a mold), according to which are formed the actual objects. If you query for help on a black box type, you learn about its purpose, its author, the boxes it contains (if it is a complex black box) and the types of its inputs/outputs. The user-defined black box types belong to the package \texttt{user} and can be listed by use of the command \texttt{help user}. If you query for help on a black box instance, you learn about the values and the state of its inputs/outputs. The currently existing black box instances belong to the complex black box \texttt{workspace} and can be listed by use of the command \texttt{help workspace}.
% ==========================================
\subsubsection{Guides}
\item\texttt{misc}: Miscellaneous...
\end {itemize}
Remark that the list of categories is 'auto-extensible': each time a new box is created which belongs to a new category and the boxes list is regenerated, the new category appears in the list, holding the new box. The above list only contains the categories used in the packages provided with current \bbtk release.
- \item {\bf\emph{ List of adaptors}}: The adaptors are a special type of black boxes that are used internally to perform type conversions. Although they are not end user intended, you may see their list. Adaptors belong to the \texttt{adaptor} category.
+ \item {\bf\emph{List of adaptors}}: The adaptors are a special type of black boxes that are used internally to perform type conversions. Although they are not end user intended, you may see their list. Adaptors belong to the \texttt{adaptor} category.
\end {itemize}
For each box, the html \texttt{Help} provides the informations necessary to use it: its name, its purpose, the descriptions of its inputs/outputs and the name of the package (or script file) that is to be loaded. Note that for a given box only the inputs/outputs listed in white cells are of actual interest. The remaining ones, grouped after them in colored cells, are standard (have the same names and purpose) in all atomic boxes. Additionally, for all boxes but the atomic ones (i.e. for all boxes defined in \bbs script language), the corresponding script is available via [\texttt{source}] link. Actually, by clicking on this link, one loads the script into the \texttt{Files} area where it can be analyzed, edited and executed.
% ==========================================
-\subsection{Creating and executing black boxes}
+\subsection{Creating and executing black box instances}
% ==========================================
At start the interpreter does not know any black box.
which is a special type of black box,
called complex black box, the purpose of which is
to store other black boxes.
-Any black box you create in \bbStudio is stored
+Any black box instance you create in \bbStudio is stored
in \texttt{workspace}
(see also section \ref{bbi-command-line-app}).
In order to let the interpreter know of some black boxes,
you must load another package.
The \texttt{std} package is the ``standard'' package,
-which contains basic useful black boxes.
+which contains basic useful black box types.
To load it, type:
\begin{verbatim}
workspace
\end{verbatim}
-Now the interpreter knows the package \texttt{std} and the black boxes it provides,
+Now the interpreter knows the package \texttt{std} and the black box types it provides,
such as the \texttt{Add} box, the \texttt{ConcatStrings} box, and so on. Remark that the
content of \texttt{std} may vary from one version to another
-as new black boxes might be added to it. Note that you will get a more detailed information about the package loaded (here \texttt{std}) if you type:
+as new black box types might be added to it. Note that you will get a more detailed information about the package loaded (here \texttt{std}) if you type:
\begin{verbatim}
> help std
\end{verbatim}
Here \texttt{'a'} is the \emph{name} of the instance,
which will be used to reference it later.
-It is important to distinguish a box \emph{type}
+Remind that it is important to distinguish a box \emph{type}
and an \emph{instance} of a box type.
The \texttt{Add} box of the package \texttt{std} is actually
a \emph{box type}, like \texttt{int} is a data type
Of course, like in \texttt{C} Language, you can declare multiple boxes of the
same type in \bbs.
-After the creation of the box \texttt{a}, type:
+After the creation of the box instance \texttt{a} the command:
\begin{verbatim}
> help workspace
\end{verbatim}
-you get :
+gives the following result:
\begin{verbatim}
Complex Black Box <user::workspace>
User's workspace
\end{itemize}
If you type the command \texttt{include bbAdd3} and then you ask for help
-on the contens of the \texttt{user} package, you get:
+on the contents of the \texttt{user} package, you get:
\begin{verbatim}
> help user
Command-line applications are those that can be executed by typing, in a console, the name of the application and the values of its parameters. The Linux users are very familiar with this way of working, while the Windows users are not, since they are used to execute the applications by clicking on the corresponding icons. Nevertheless, the command-line execution of the applications is feasible (although not very useful) in Windows. You just need to invoke the black ``console'' available either via \texttt{Start > Execute > cmd}, or via \texttt{Start > Programs > Accessories > Invoke commands}. Furthermore, command-line execution of applications is very useful in both environments in such cases as batches.
-So, you already know how to write script files that define complex black boxes
-(with \texttt{define/endefine}), and how to include them in (more) complex black boxes. You can imagine these definitions as though they were a kind of ``functions'' that can be ``called'' by a program (actually, these are rather ``classes'' that can be instanciated, according to the object-oriented programming concepts). The question now is how to write the ``main program'' to be executed directly from the console by typing:
+You already know how to write script files that define stand-alone pipeline applications.
+In fact, these applications \emph{can} be executed directly from the console by typing:
\begin{verbatim}
> bbi <application-name>
\end{verbatim}
Note that this execution mode invokes the interpreter \texttt{bbi} and passes the name of the application to the interpreter.
-Let us think back of the \texttt{workspace} object.
+So, what more do you need to know? A command-line application may need some inputs. In order to define them, you need to use the (already known) command \texttt{input}.
+
+To understand the underlying mechanism let us think back of the \texttt{workspace} object.
Remember that it is also
a \texttt{complex black box}.
Actually, when you write \bbs commands
git://git.creatis.insa-lyon.fr / bbtk.git / commitdiff