Sysquake Pro – Table of Contents
Sysquake for LaTeX – Table of Contents
Programming Constructs
Programming constructs are the backbone of any LME program. Except for the variable assignment, all of them use reserved keywords which may not be used to name variables or functions. In addition to the constructs described below, the following keywords are reserved for future use:
|
|
break
Terminate loop immediately.
Syntax
break
Description
When a break statement is executed in the scope of a loop construct (while, repeat or for), the loop is terminated. Execution continues at the statement which follows end. Only the innermost loop where break is located is terminated.
The loop must be in the same function as break. It is an error to execute break outside any loop.
See also
while, repeat, for, continue, return
case
Conditional execution of statements depending on a number or a string.
See also
catch
Error recovery.
See also
continue
Continue loop from beginning.
Syntax
continue
Description
When a continue statement is executed in the scope of a loop construct (while, repeat or for), statements following continue are ignored and a new loop is performed if the loop termination criterion is not fulfilled.
The loop must be in the same function as continue. It is an error to execute continue outside any loop.
See also
define
Definition of a constant.
Syntax
define c = expr define c = expr;
Description
define c=expr assign permanently expression expr to c. It is equivalent to
function y = c y = expr;
Since c does not have any input argument, the expression is usually constant. A semicolon may follow the definition, but it does not have any effect. define must be the first element of the line (spaces and comments are skipped).
Examples
define e = exp(1); define g = 9.81; define c = 299792458; define G = 6.672659e-11;
See also
for
Loop controlled by a variable which takes successively the value of the elements of a vector or a list.
Syntax
for v = vect
s1
...
end
for v = list
s1
...
end
Description
The statements between the for statement and the corresponding end are executed repeatedly with the control variable v taking successively every column of vect or every element of list list. Typically, vect is a row vector defined with the range operator.
You can change the value of the control variable in the loop; however, next time the loop is repeated, that value is discarded and the next column of vect is fetched.
Examples
for i = 1:3; i, end
i =
1
i =
2
i =
3
for i = (1:3)'; i, end
i =
1
2
3
for i = 1:2:5; end; i
i =
5
for i = 1:3; break; end; i
i =
1
for el = {1,'abc',{2,5}}; el, end
el =
1
el =
abc
el =
{2,5}
See also
while, repeat, break, continue, variable assignment
function endfunction
Definition of a function, operator, or method.
Syntax
function f statements function f(x1, x2, ...) statements function f(x1, x2 = expr2, ...) statements function y = f(x1, x2, ...) statements function (y1,y2,...) = f(x1,x2,...) statements function ... class::method ... statements function ... statements endfunction
Description
New functions can be written to extend the capabilities of LME. They begin with a line containing the keyword function, followed by the list of output arguments (if any), the function name, and the list of input arguments between parenthesis (if any). The output arguments must be enclosed between parenthesis or square brackets if they are several. One or more variable can be shared in the list of input and output arguments. When the execution of the function terminates (either after the last statement or because of the command return), the current value of the output arguments, as set by the function's statements, is given back to the caller. All variables used in the function's statements are local; their value is undefined before the first assignment (and it is illegal to use them in an expression), and is not shared with variables in other functions or with recursive calls of the same function. Different kinds of variables can be declared explicitly with global and persistent.
When multiple functions are defined in the same code source (for instance in a library), the body of a function spans from its header to the next function or until the endfunction keyword, whichever comes first. Function definitions cannot be nested. endfunction is required only when the function definition is followed by code to be executed outside the scope of any function. This includes mixed code and function definitions entered in one large entry in a command-line interface, or applications where code is mainly provided as statements, but where function definitions can help and separate libraries are not wished (note that libraries cannot contain code outside function definitions; they do not require endfunction). Both function and endfunction appear usually at the beginning of a line, but are also permitted after a semicolon or a comma.
Variable number of arguments
Not all of the input and output arguments are necessarily specified by the caller. The caller fixes the number of input and output arguments, which can be obtained by the called function with nargin and nargout, respectively. Unspecified input arguments (from nargin+1 to the last one) are undefined, unless a default value is provided in the function definition: with the definition function f(x,y=2), y is 2 when f is called with a single input argument. Unused output arguments (from nargout+1 to the last one) do not have to be set, but may be.
Functions which accept an unspecified number of input and/or output arguments can use the special variables varargin and varargout, which are lists of values corresponding to remaining input and output arguments, respectively.
Named arguments
The caller can pass some or all of the input arguments by name, such as f(x=2). Named arguments must follow unnamed ones. Their order does not have to match the order of the input arguments in the function declaration, and some arguments can be missing. Missing arguments are set to their default value if it exists, or left undefined. Undefined arguments can be detected with isdefined, or the error caused by their use caught by try.
Functions which accept unspecified named arguments or which do not want to expose the argument names used in their implementation can use the special variable namedargin, which is a structure containing all named arguments passed by the caller.
Unused arguments
Character ~ stands for an unused argument. It can be used as a placeholder for an input argument name in the function definition, or in the list of output arguments specified for the function call.
If function f is defined with function header function f(x,~), it accepts two input arguments, the first one assigned to x and the second one discarded. This can be useful if f is called by code which expects a function with two input arguments.
In (a,~,c)=f, function f is called to provide three output arguments (nargout==3), but the second output argument is discarded.
Operator overloading
To redefine an operator (which is especially useful for object methods; see below), use the equivalent function, such as plus for operator +. The complete list is given in the section about operators.
To define a method which is executed when one of the input arguments is an object of class class (or a child in the classes hierarchy), add class:: before the method (function) name. To call it, use only the method name, not the class name.
Examples
Function with optional input and output arguments:
function (Sum, Prod) = calcSumAndProd(x, y)
if nargout == 0
return; % nothing to be computed
end
if nargin == 0 % make something to be computed...
x = 0;
end
if nargin <= 1 % sum of elements of x
Sum = sum(x);
else % sum of x and y
Sum = x + y;
end
if nargout == 2 % also compute the product
if nargin == 1 % product of elements of x
Prod = prod(x);
else % product of x and y
Prod = x .* y;
end
end
Two equivalent definitions:
function S = area(a, b = a, ellipse = false) S = ellipse ? pi * a * b / 4 : a * b;
function S = area(a, b, ellipse)
if ~isdefined(b)
b = a;
end
if ~isdefined(ellipse)
ellipse = false;
end
S = ellipse ? pi * a * b / 4 : a * b;
With unnamed arguments only, area can be called with values for a only, a and b, or a, b and ellipse. By naming ellipse, the second argument can be omitted:
S = area(2, ellipse=true)
S =
3.1416
Function max can return the index of the maximum value in a vector. In the following call, the maximum itself is discarded.
(~, maxIndex) = max([2,7,3,5])
maxIndex =
2
See also
return, nargin, nargout, isdefined, varargin, varargout, namedargin, define, inline, global, persistent
hideimplementation
Hide the implementation of remaining functions in a library.
Syntax
hideimplementation
Description
In a library, functions which are defined after the hideimplementation keyword have their implementation hidden: for errors occuring when they are executed, the error message is the same as if the function was a native function (it does not contain information about the error location in the function or subfunctions), and during debugging, dbstep in steps over the function call.
hideimplementation may not be placed in the same line of source code as any other command (comments are possible, though).
See also
public, private, function, use, error, dbstep
if elseif else end
Conditional execution depending on the value of one or more boolean expressions.
Syntax
if expr
s1
...
end
if expr
s1
...
else
s2
...
end
if expr1
s1
...
elseif expr2
s2
...
else
s3
...
end
Description
If the expression following if is true (nonempty and all elements different from 0 and false), the statements which follow are executed. Otherwise, the expressions following elseif are evaluated, until one of them is true. If all expressions are false, the statements following else are executed. Both elseif and else are optional.
Example
if x > 2
disp('large');
elseif x > 1
disp('medium');
else
disp('small');
end
See also
include
Include libraries.
Syntax
include lib
Description
include lib inserts the contents of the library file lib. Its effect is similar to the use statement, except that the functions and constants in lib are defined in the same context as the library where include is located. Its main purpose is to permit to define large libraries in multiple files in a transparent way for the user. include statements must not follow other statements on the same line, and can reference only one library which is searched at the same locations as use. They can be used only in libraries.
Since LME replaces include with the contents of lib, one should be cautious about the public or private context which is preserved between the libraries. It is possible to include a fragment of function without a function header.
See also
use, includeifexists, private, public
includeifexists
Include library if it exists.
Syntax
includeifexists lib
Description
includeifexists lib inserts the contents of the library file lib if it exists; if the library does not exists, it does nothing.
See also
include, useifexists, private, public
otherwise
Conditional execution of statements depending on a number or a string.
See also
private
Mark the beginning of a sequence of private function definitions in a library.
Syntax
private
Description
In a library, functions which are defined after the private keyword are private. private may not be placed in the same line of source code as any other command (comments are possible, though).
In a library, functions are either public or private. Private functions can only be called from the same library, while public functions can also be called from contexts where the library has been imported with a use command. Functions are public by default.
Example
Here is a library for computing the roots of a second-order polynomial. Only function roots2 can be called from the outside of the library.
private function d = discr(a, b, c) d = b^2 - 4 * a * c; public function r = roots2(p) a = p(1); b = p(2); c = p(3); d = discr(a, b, c); r = [-b+sqrt(d); -b-sqrt(d)] / (2 * a);
See also
public
Mark the beginning of a sequence of public function definitions in a library.
Syntax
public
Description
In a library, functions which are defined after the public keyword are public. public may not be placed in the same line of source code as any other command (comments are possible, though).
In a library, functions are either public or private. Private functions can only be called from the same library, while public functions can also be called from contexts where the library has been imported with a use command. Functions are public by default: the public keyword is not required at the beginning of the library.
See also
repeat
Loop controlled by a boolean expression.
Syntax
repeat
s1
...
until expr
Description
The statements between the repeat statement and the corresponding until are executed repeatedly (at least once) until the expression of the until statement yields true (nonempty and all elements different from 0 and false).
Example
v = [];
repeat
v = [v, sum(v)+1];
until v(end) > 100;
v
1 2 4 8 16 32 64 128
See also
return
Early return from a function.
Syntax
return
Description
return stops the execution of the current function and returns to the calling function. The current value of the output arguments, if any, is returned. return can be used in any control structure, such as if, while, or try, or at the top level.
Example
function dispFactTable(n)
% display the table of factorials from 1 to n
if n == 0
return; % nothing to display
end
fwrite(' i i!\n');
for i = 1:n
fwrite('%2d %3d\n', i, prod(1:i));
end
See also
switch
Conditional execution of statements depending on a number or a string.
Syntax
switch expr
case e1
s1
...
case [e2,e3,...]
s23
...
case {e4,e5,...}
s45
...
otherwise
so
...
end
switch string
case str1
s1
...
case str2
s2
...
case {str3,str4,...}
s34
...
otherwise
so
...
end
Description
The expression of the switch statement is evaluated. If it yields a number, it is compared successively to the result of the expressions of the case statements, until it matches one; then the statements which follow the case are executed until the next case, otherwise or end. If the case expression yields a vector or a list, a match occurs if the switch expression is equal to any of the elements of the case expression. If no match is found, but otherwise is present, the statements following otherwise are executed. If the switch expression yields a string, a match occurs only in case of equality with a case string expression or any element of a case list expression.
Example
switch option
case 'arithmetic'
m = mean(data);
case 'geometric'
m = prod(data)^(1/length(data));
otherwise
error('unknown option');
end
See also
try
Error recovery.
Syntax
try ... end try ... catch ... end try ... catch e ... end
Description
The statements after try are executed. If an error occurs, execution is switched to the statements following catch, if any, or to the statements following end. If catch is followed by a variable name, a structure describing the error (the result of lasterror) is assigned to this variable; otherwise, the error message can be retrieved with lasterr or lasterror. If no error occurs, the statements between try and end are ignored.
try ignores two errors:
- the interrupt key (Control-Break on Windows, Command-. on macOS, Control-C on other operating systems with a keyboard, timeout in Sysquake Remote);
- an attempt to execute an untrusted function in a sandbox. The error can be handled only outside the sandbox.
Examples
a = 1;
a(2), 555
Index out of range 'a'
try, a(2), end, 555
555
try, a(2), catch, 333, end, 555
333
555
try, a, catch, 333, end, 555
a =
1
555
See also
until
End of repeat/until loop.
See also
use
Import libraries.
Syntax
use lib use lib1, lib2, ...
Description
Functions can be defined in separate files, called libraries. use makes them available in the current context, so that they can be called by the functions or statements which follow. Using a library does not make available functions defined in its sublibraries; however, libraries can be used multiple times, in each context where their functions are referenced.
All use statements are parsed before execution begins. They can be placed anywhere in the code, typically before the first function. They cannot be skipped by placing them after an if statement. Likewise, try/catch cannot be used to catch errors; useifexists should be used if the absence of the library is to be ignored.
See also
useifexists, include, function, private, public, info
useifexists
Import libraries if they exist.
Syntax
useifexists lib useifexists lib1, lib2, ...
Description
useifexists has the same syntax and effect as use, except that libraries which are not found are ignored without error.
See also
use, include, function, private, public, info
while
Loop controlled by a boolean expression.
Syntax
while expr
s1
...
end
Description
The statements between the while statement and the corresponding end are executed repeatedly as long as the expression of the while statement yields true (nonempty and all elements different from 0 and false).
If a break statement is executed in the scope of the while loop (i.e. not in an enclosed loop), the loop is terminated.
If a continue statement is executed in the scope of the while loop, statements following continue are ignored and a new loop is performed if the while statement yields true.
Example
e = 1;
i = 2;
while true % forever
eNew = (1 + 1/i) ^ i;
if abs(e - eNew) < 0.001
break;
end
e = eNew;
i = 2 * i;
end
e
2.717