/usr/share/doc/yacas-doc/html/essayschapter6.html

<html>
<head>
  <title>Designing modules in the Yacas scripting language</title>
  <link rel="stylesheet" href="yacas.css" TYPE="text/css" MEDIA="screen">
</head>
<body>
<a name="c6">

</a>
<h1>
6. Designing modules in the Yacas scripting language
</h1>
<p> </p>
<a name="c6s1">

</a>
<h2>
<hr>6.1 Introduction
</h2>
For any software project where the source code grows to
a substantial amount of different modules, there needs to be
a way to define interfaces between the modules, and a way
to make sure the modules don't interact with the environment
in an unintended way. 


<p>
One hallmark of a mature programming language is that it 
supports modules, and a way to define its interface while
hiding the internals of the module. This section describes
the mechanisms for doing so in the Yacas scripting language.


<p>

<a name="c6s2">

</a>
<h2>
<hr>6.2 Demonstration of the problem
</h2>
Unintentional interactions between two modules typically happen 
when the two modules accidentally share a common "global"
resource, and there should be a mechanism to guarantee that this
will not happen.


<p>
The following piece of code is a little example that demonstrates
the problem:


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
SetExpand(fn_IsString) &lt;-- [expand:=fn;];
ram(x_IsList)_(expand != "") &lt;-- ramlocal(x);
expand:="";
ramlocal(x) := Map(expand,{x});
</pre></tr>
</table>


<p>
This little bit of code defines a function <b><tt>ram</tt></b> that calls the
function <b><tt>Map</tt></b>, passing the argument passed if it is a string, and
if the function to be mapped was set with the <b><tt>SetExpand</tt></b> function.
It contains the following flaws:


<p>
<ul><li></li><b><tt>expand</tt></b> is a global variable with a rather generic name, one
that another module might decide to use.
<li></li><b><tt>ramlocal</tt></b> was intended to be used from within this module only, and
doesn't check for correctness of arguments (a small speed up optimization
that can be used for routines that get called often). As it is, it can be
called from other parts, or even the command line.
<li>the function </li><b><tt>ramlocal</tt></b> has one parameter, named <b><tt>x</tt></b>, which is also
generic (and might be used in the expression passed in to the function),
and <b><tt>ramlocal</tt></b> calls <b><tt>Map</tt></b>, which calls <b><tt>Eval</tt></b> on the arguments. 
</ul>

<p>
The above code can be entered into a file and loaded from the command
line at leisure. Now, consider the following command line interaction
after loading the file with the above code in it:


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
In&gt; ramlocal(a)         
In function "Length" : 
bad argument number 1 (counting from 1)
Argument matrix[1] evaluated to a
In function call  Length(a)
CommandLine(1) : Argument is not a list
</pre></tr>
</table>


<p>
We called <b><tt>ramlocal</tt></b> here, which should not have been allowed.


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
In&gt; ram(a)
Out&gt; ram(a);
</pre></tr>
</table>


<p>
The function <b><tt>ram</tt></b> checks that the correct arguments are passed in
and that <b><tt>SetExpand</tt></b> was called, so it will not evaluate if these
requirements are not met. 


<p>
Here are some lines showing the functionality of this code as
it was intended to be used:


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
In&gt; SetExpand("Sin")
Out&gt; "Sin";
In&gt; ram({1,2,3})
Out&gt; {Sin(1),Sin(2),Sin(3)};
</pre></tr>
</table>


<p>
The following piece of code forces the functionality to break
by passing in an expression containing the variable <b><tt>x</tt></b>, which
is also used as a parameter name to <b><tt>ramlocal</tt></b>.


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
In&gt; ram({a,b,c})
Out&gt; {Sin(a),Sin(b),Sin(c)};
In&gt; ram({x,y,z})
Out&gt; {{Sin(x),Sin(y),Sin(z)},Sin(y),Sin(z)};
</pre></tr>
</table>


<p>
This result is obviously wrong, comparing it to the call above.
The following shows that the global variable <b><tt>expand</tt></b> is exposed
to its environment:


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
In&gt; expand
Out&gt; "Sin";
</pre></tr>
</table>


<p>

<a name="c6s3">

</a>
<h2>
<hr>6.3 Declaring resources to be local to the module
</h2>
The solution to the problem is <b><tt>LocalSymbols</tt></b>, which changes every
symbol with a specified name to a unique name that could never
be entered by the user on the command line and guarantees that it
can never interact with the rest of the system. The following code
snippet is the same as the above, with the correct use of <b><tt>LocalSymbols</tt></b>:


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
LocalSymbols(x,expand,ramlocal) [
  SetExpand(fn_IsString) &lt;-- [expand:=fn;];
  ram(x_IsList)_(expand != "") &lt;-- ramlocal(x);
  expand:="";
  ramlocal(x) := Map(expand,{x});
];
</pre></tr>
</table>


<p>
This version of the same code declares the symbols <b><tt>x</tt></b>, <b><tt>expand</tt></b>
and <b><tt>ramlocal</tt></b> to be local to this module.


<p>
With this the interaction becomes a little bit more predictable:


<p>
<table cellpadding="0" width="100%">
<tr><td width=100% bgcolor="#DDDDEE"><pre>
In&gt; ramlocal(a)
Out&gt; ramlocal(a);
In&gt; ram(a)
Out&gt; ram(a);
In&gt; SetExpand("Sin")
Out&gt; "Sin";
In&gt; ram({1,2,3})
Out&gt; {Sin(1),Sin(2),Sin(3)};
In&gt; ram({a,b,c})
Out&gt; {Sin(a),Sin(b),Sin(c)};
In&gt; ram({x,y,z})
Out&gt; {Sin(x),Sin(y),Sin(z)};
In&gt; expand
Out&gt; expand;
</pre></tr>
</table>


<p>

<a name="c6s4">

</a>
<h2>
<hr>6.4 When to use and when not to use <b><tt>LocalSymbols</tt></b>
</h2>
The <b><tt>LocalSymbols</tt></b> should ideally be used for every global variable,
for functions that can only be useful within the module and thus
should not be used by other parts of the system, 
and for local variables that run the risk of being passed into 
functions like <b><tt>Eval</tt></b>, <b><tt>Apply</tt></b>, <b><tt>Map</tt></b>, etc. (functions that
re-evaluate expressions).


<p>
A rigorous solution to this is to make all parameters to functions
and global variables local symbols by default, but this might cause
problems when this is not required, or even wanted, behaviour.


<p>
The system will never be able to second-guess which function
calls can be exposed to the outside world, and which ones should
stay local to the system. It also goes against a design rule of Yacas:
everything is possible, but not obligatory. This is important 
at moments when functionality is not wanted, as it can be hard 
to disable functionality when the system does it automatically.


<p>
There are more caveats: if a local variable is made unique with 
<b><tt>LocalSymbols</tt></b>, other routines can not reach it by using the 
<b><tt>UnFence</tt></b> construct. This means that <b><tt>LocalSymbols</tt></b> is not always 
wanted. 


<p>
Also, the entire expression on which the <b><tt>LocalSymbols</tt></b> command works
is copied and modified before being evaluated, making loading
time a little slower. This is not a big problem, because the 
speed hit is usually during calculations, not during loading, but
it is best to keep this in mind and keep the code passed to 
<b><tt>LocalSymbols</tt></b> concise.


<p>


<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-2425144-1";
urchinTracker();
</script>
</body>

</html>
yacas-doc 1.3.3-2 / usr / share / doc / yacas-doc / html / essayschapter6.html
