/*, */, //
,
Prog, [, ]
,
Check
,
Bodied, Infix, Postfix, Prefix
,
IsBodied, IsInfix, IsPostfix, IsPrefix
,
OpPrecedence, OpLeftPrecedence, OpRightPrecedence
,
RightAssociative
,
LeftPrecedence, RightPrecedence
,
RuleBase
,
Rule
,
HoldArg
,
Retract
,
UnFence
,
HoldArgNr
,
RuleBaseArgList
,
MacroSet, MacroClear, MacroLocal, MacroRuleBase, MacroRule
,
Back-quoting
,
SetExtraInfo, GetExtraInfo
,
GarbageCollect
,
CurrentFile, CurrentLine
,
FindFunction
,
Secure
.
Programming
/*, */, //
|
comments |
Prog, [, ]
|
block of statements |
Check
|
report errors |
Bodied, Infix, Postfix, Prefix
|
define function syntax |
IsBodied, IsInfix, IsPostfix, IsPrefix
|
check for function syntax |
OpPrecedence, OpLeftPrecedence, OpRightPrecedence
|
get operator precedence |
RightAssociative
|
declare associativity |
LeftPrecedence, RightPrecedence
|
set operator precedence |
RuleBase
|
define function name |
Rule
|
define rule |
HoldArg
|
mark argument as not evaluated |
Retract
|
erase rules for a function |
UnFence
|
change local variable scope for a function |
HoldArgNr
|
specify argument as not evaluated |
RuleBaseArgList
|
obtain list of arguments |
MacroSet, MacroClear, MacroLocal, MacroRuleBase, MacroRule
|
manipulate symbols |
Back-quoting
|
Back-quoting, macro expansion |
SetExtraInfo, GetExtraInfo
|
Annotate objects with additional tag information |
GarbageCollect
|
Do garbage collection on unused memory |
CurrentFile, CurrentLine
|
Show current file and line of input |
FindFunction
|
Finding the file a function is defined in |
Secure
|
guard the host OS |
/*, */, // -- comments
Internal function
Calling format:
Description:
Introduce a comment block in a source file, similar to C++ comments.
// makes everything until the end of the line a comment, while /* and */ may delimit a multi-line comment.
Examples:
a+b; // get result
a + /* add them */ b;
|
Prog, [, ] -- block of statements
Internal function
Calling format:
Prog(statement1, statement2, ...)
[ statement1; statement2; ... ]
|
Parameters:
statement1, statement2 -- expressions
Description:
The Prog() and the [ ... ] constuct have the same effect: they evaluate all
arguments in order and return the result of the last evaluated expression.
Prog(a,b); is the same as typing [a;b;]; and is very useful for writing out
function bodies. The [...] construct is a syntactically nicer version of the
Prog() call; it is converted into Prog(...) during the parsing stage.
Check -- report errors
Internal function
Calling format:
Check(predicate,"error text")
|
Parameters:
predicate -- expression returning True or False
Description:
If predicate doesn't evaluate to True,
then current operation will be stopped, and execution
will jump right back to the command line, showing
error text. Use this to assure that some condition
is met during evaluation of expressions (guarding
against internal errors).
Bodied, Infix, Postfix, Prefix -- define function syntax
Internal function
Calling format:
Bodied("op", precedence)
Infix("op")
Infix("op", precedence)
Postfix("op")
Prefix("op")
Prefix("op", precedence)
|
Parameters:
"op" -- string, the name of a function
precedence -- nonnegative integer (evaluated)
Description:
Declares a function for the parser to understand as a bodied, infix, postfix, or prefix operator. Function name can be any string but meaningful usage would require it to be either made up entirely of letters or entirely of non-letter characters (such as "+", ":" etc.). Precedence can be specified (will be 0 by default).
Examples:
In> YY x := x+1;
CommandLine(1) : Error parsing expression
In> Prefix("YY", 2)
Out> True;
In> YY x := x+1;
Out> True;
In> YY YY 2*3
Out> 12;
In> Infix("##", 5)
Out> True;
In> a ## b ## c
Out> a##b##c;
|
See also:
IsBodied
,
OpPrecedence
.
IsBodied, IsInfix, IsPostfix, IsPrefix -- check for function syntax
Internal function
Calling format:
IsBodied("op")
IsInfix("op")
IsPostfix("op")
IsPrefix("op")
|
Parameters:
"op" -- string, the name of a function
Description:
Check whether the function with given name "op" has been declared as a "bodied", infix, postfix, or prefix operator, and return True or False.
Examples:
In> IsInfix("+");
Out> True;
In> IsBodied("While");
Out> True;
In> IsBodied("Sin");
Out> False;
|
See also:
Bodied
,
OpPrecedence
.
OpPrecedence, OpLeftPrecedence, OpRightPrecedence -- get operator precedence
Internal function
Calling format:
OpPrecedence("op")
OpLeftPrecedence("op")
OpRightPrecedence("op")
|
Parameters:
"op" -- string, the name of a function
Description:
Returns the precedence of the function named "op" which should have been declared as a bodied function or an infix, postfix, or prefix operator. Generates an error message if the string str does not represent a type of function that can have precedence.
For infix operators, right precedence can differ from left precedence. Bodied functions and prefix operators cannot have left precedence, while postfix operators cannot have right precedence; for these operators, there is only one value of precedence.
Examples:
In> OpPrecedence("+")
Out> 6;
In> OpLeftPrecedence("!")
Out> 0;
|
RightAssociative -- declare associativity
Internal function
Calling format:
Parameters:
"op" -- string, the name of a function
This makes the operator right-associative. Example:
would make multiplication right-associative. Take care not to abuse
this function, because the reverse, making an infix operator
left-associative, is not implemented.
See also:
OpPrecedence
.
LeftPrecedence, RightPrecedence -- set operator precedence
Internal function
Calling format:
LeftPrecedence("op",precedence)
RightPrecedence("op",precedence)
|
Parameters:
"op" -- string, the name of a function
precedence -- nonnegative integer
Description:
"op" should be an infix operator. This function call tells the
infix expression printer to bracket the left or right hand side of
the expression if its precedence is larger than precedence.
This functionality was required in order to display a-(b-c)
correctly. Thus, a+b+c is the same as a+(b+c), but a-(b-c) is not
the same as a-b-c.
RuleBase -- define function name
Internal function
Calling format:
RuleBase("operator",{params})
|
Description:
Define a new rules table entry for a
function "operator", with params as the parameter list.
Rule -- define rule
Calling format:
Rule("operator", arity,
precedence, predicate) body
|
Description:
Define a rule for the function "operator" with
"arity", "precedence", "predicate" and
"body". The "precedence" goes from low to high: rules with low precedence will be applied first.
The arity for a rules database equals the number of arguments. Different
rules data bases can be built for functions with the same name but with
a different number of arguments.
Rules with a low value will be tried before rules with a high value, so
a rule with precedence 0 will be tried before a rule with precedence 1.
HoldArg -- mark argument as not evaluated
Internal function
Calling format:
HoldArg("operator",parameter)
|
Parameters:
"operator" -- string, name of a function
parameter -- atom, symbolic name of parameter
Description:
Specify that parameter should
not be evaluated before used. This will be
declared for all arities of "operator", at the moment
this function is called, so it is best called
after all RuleBase calls for this operator.
The parameter must be an atom from the list of symbolic arguments used when calling RuleBase.
See also:
RuleBase
,
HoldArgNr
,
RuleBaseArgList
.
Retract -- erase rules for a function
Internal function
Calling format:
Retract("operator",arity)
Remove a rulebase with some specific arity,
if it exists at all.
UnFence -- change local variable scope for a function
Internal function
Calling format:
UnFence("operator",arity)
Description:
When applied to a user function, the bodies
defined for the rules for "operator" with given
arity can see the local variables from the calling
function. This is useful for defining macro-like
procedures (looping and the such). The standard library functions For and ForEach use UnFence().
HoldArgNr -- specify argument as not evaluated
Standard math library
Calling format:
HoldArgNr("function", arity, argNum)
|
Parameters:
"function" -- string, function name
arity, argNum -- positive integers
Description:
Declares the argument number argNum of the function named "function" with specified arity to be unevaluated. Useful if you don't know symbolic names of parameters, for instance, when the function was not declared using an explicit RuleBase call.
See also:
HoldArg
,
RuleBase
.
RuleBaseArgList -- obtain list of arguments
Internal function
Calling format:
RuleBaseArgList("operator", arity)
|
Parameters:
"operator" -- string, name of function
arity -- integer
Description:
Returns a list of atoms, symbolic parameters specified in the RuleBase() call for the function named "operator" with the specific arity.
See also:
RuleBase
,
HoldArgNr
,
HoldArg
.
MacroSet, MacroClear, MacroLocal, MacroRuleBase, MacroRule -- manipulate symbols
Same as their non-macro counterparts, except
that their arguments are evaluated before
the required action is performed. This is
useful in macro-like procedures.
Back-quoting -- Back-quoting, macro expansion
Internal function
Calling format:
Parameters:
expression - expression containing @var pairs to substitute the value of variable var
Description:
Back-quoting is a powerful mechanism where variables get expanded
inside an expression, and the expression then gets evaluated.
To invoke this functionality, a back-quote ` needs to be placed
in front of an expression. If the @var pair is in place of a function
the function is replaced.
One way to view back-quoting is to view it as a parametric expression
generator. @var pairs get substituted with the value of th variable
var.
This operation is relatively slow since a new expression is built
before it is evaluated, but it is a powerful mechanism nonetheless,
allowing for great simplifications.
Examples:
In> Decl(f1,f2) := \
In> `(@f1(x_IsNumber) <-- N(@f2(x)));
Out> True;
In> Decl(nSin,Sin)
Out> True;
In> Sin(1)
Out> Sin(1);
In> nSin(1)
Out> 0.8414709848;
|
The above example defines a function that automatically evaluates to a
number as soon as the argument is a number (a lot of functions
do this only when inside a N(...) section).
In> SetF(var,func,value) := \
In> `(Set(@var,@func(@value)));
Out> True;
In> SetF(a,Sin,x)
Out> True;
In> a
Out> Sin(x);
|
The above example assigns func(value) to variable var.
See also:
MacroSet
,
MacroLocal
,
MacroRuleBase
.
SetExtraInfo, GetExtraInfo -- Annotate objects with additional tag information
Internal function
Calling format:
SetExtraInfo(expression,tag)
GetExtraInfo(expression)
|
Parameters:
expression - expression to tag
tag - tag information
Description:
Sometimes it is useful to be able to add extra annotational tag information
to objects. The functions SetExtraInfo and GetExtraInfo enable this.
The function SetExtraInfo returns the tagged expression, leaving
the original expression alone. This means there is a common gotcha:
be sure to assign the returned value to a variable, or the tagged
expression is lost.
The original expression is left alone, and the tagged expression
returned, in order to keep the atomic objects small. To tag an
object, a new type of object is created from the old object, with
one added property: a tag.
No part of Yacas uses tags in a way that is visible to the outside
world, so for specific programs, a programmer can devise a format
to use for tagging information. Association lists are a natural fit
for this, but it is not required. The tag is free-form, although
using association lists is highly advised since it is most likely
to be the format used by other parts of the system, making the code
compatible with other parts.
Examples:
In> a:=2*b
Out> 2*b;
In> a:=SetExtraInfo(a,{{"type","integer"}})
Out> 2*b;
In> a
Out> 2*b;
In> GetExtraInfo(a)
Out> {{"type","integer"}};
In> GetExtraInfo(a)["type"]
Out> "integer";
In> c:=a
Out> 2*b;
In> GetExtraInfo(c)
Out> {{"type","integer"}};
In> c
Out> 2*b;
|
See also:
Assoc
.
GarbageCollect -- Do garbage collection on unused memory
Internal function
Calling format:
Parameters:
none
Description:
GarbageCollect() garbage-collects unused memory. The Yacas system
uses a reference counting system for most objects, so this call
is usually not necessary.
Reference counting refers to bookkeeping where in each object a
counter is held, keeping track of the number of parts in the system
using that object. When this count drops to zero, the object is
automatically removed. Reference counting is not the fastest way
of doing garbage collection, but it can be implemented in a very
clean way with very little code.
Among the most important objects that are not reference counted are
the strings. GarbageCollect() collects these and disposes of them
when they are not used any more.
GarbageCollect() is useful when doing a lot of text processing,
to clean up the text buffers. It is not highly needed, but it keeps
memory use low.
CurrentFile, CurrentLine -- Show current file and line of input
Internal function
Calling format:
CurrentFile()
CurrentLine()
|
Parameters:
none
Description:
The functions CurrentFile() and CurrentLine() return a string
with the file name of the current file, and the current line
of input respectively.
These functions are most useful in batch file calculations, where
there is a need to determine at which line an error occurred. It is
easy to define a function
tst() := Echo({CurrentFile(),CurrentLine()});
|
which can then be spread out over the input file at various places,
to see how far the interpreter reaches before an error occurs.
Examples:
See also:
Echo
.
FindFunction -- Finding the file a function is defined in
Internal function
Calling format:
Parameters:
function - a function name in string format
Description:
This function is useful for quickly finding the file a function is
defined in. It is likely to only be useful for developers. The
function FindFunction() scans the def files that were loaded at
start-up. This means that functions that were not defined in def
files, but were loaded directly, will not be found with
FindFunction().
Examples:
In> FindFunction("Sum")
Out> "sums.rep/code.ys";
In> FindFunction("Integrate")
Out> "integrate.rep/code.ys";
|
See also:
Vi
.
Secure -- guard the host OS
Internal function
Calling format:
Description:
Secure evaluates body in a safe environment, where file opening
and system calls are not allowed. This can protect the system
when an unsafe evaluation is done (Like a script sent over the
internet to be evaluated on a computer).