en fr

Sysquake Pro – Table of Contents

Sysquake – 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:

classdef
goto
parfor
spmd

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

switch, otherwise

catch

Error recovery.

See also

try

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

while, repeat, for, break

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

function

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

switch, while

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

switch, case

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, function, use

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

private, function, use

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

while, for, break, continue

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

function

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

case, otherwise, if

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

lasterr, lasterror, error

until

End of repeat/until loop.

See also

repeat

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

See also

repeat, for, break, continue, if