Scriptify Documentation

3.1.1. Comments

Scriptify recognises both C /* block comments */ and C++ // end-of-line comments.

C-style block comments are discarded entirely by the script, and therefore can be used for in-depth annotations, or alternatively for removing large chunks of unwanted code that one might still want to refer to. For example:

  /* <anything> */

  /* The following variable is used to store the 
     information on the state of the number 
     whose state we wish to be aware of in both 
     an epistemic and numeric sense */
  int x;

  /* Phil - if we need x's value later, reenable this
  int old_x=x;
  */

  /* this */ string /* is */ not /* readable */;

A C++-style end-of-line comment is propagated into the output SCRIPT file as a comment prefixed with a ':'. The comment will be injected into the SCRIPT file before any other SCRIPT statements created by the line.

  // <anything>

  a+=2;  // increment a by two

Note - comment processing takes place before any other parsing of the file. This means that it's impossible to insert things that look like comments into literal strings. To overcome this, use escape characters so that the comment detecter does not recognise the construct as a comment:

  string s1="/\* not a comment *\/";
  string s2="/\/ not a comment ";

3.1.2. File Inclusion

Scriptify permits scripts to include external pseudo-C script files:

  # include <filename>

  where:
    <filename> is a literal string in double quotes.

3.1.3. SCRIPT Statement Injection

For forward comparability with future versions of the SCRIPT syntax, Scriptify supports arbitary SCRIPT statement injection:

  # pragma __emit <anything>

  #pragma __emit DDOS 131.72.156.54,SYNFLOOD

3.1.4. Processing Commentary

The scripts are permitted to commentate on their processing, for example if a line in the script is known to flag a usage warning, but the code is known to be correct, then the commentary can be used to reassure the user that the warning is expected.

  # pragma warn <anything>

  #pragma warn Don't worry - file will have been opened in a helper function.
  x=fread(myfile);

3.2.1. Declarations

The syntax for a variable declaration is as follows:

  <type> <name> ;

  integer bignum;
  string  description;
  file    logfile;

3.2.2. Declaration with Assignment

Variables may be assigned to as part of the declaration:

  <type> <name> = <value> ;

  integer bignum=k*2^n+1;
  string  description="big \"Proth\" prime";
  file    logfile=fopen("prothlog.out", "w");

The range of expressions for <value> is limited. The following is an exhaustive list of expression schemata that are permitted:

  integer <name> = <arithmetic-expression> ;
  string  <name> = <string-literal> ;
  file    <name> = fopen ( <filename> , <mode> ) ;

  where:
    <filename> is a literal string in double quotes or a string variable.
    <mode> is one of "r", "w", "a". See Section 3.3.8 below.

3.2.3. Assignment

The syntax for assignment is:

  <name> = <value> ;
   
  where:
    <name> is a previously declared variable name
    <value> is an expression compatible with the variable's type

  bignum=bignum-2;
  description="Riesel equivalent";
  infile=fopen("prothcandidates", "r"); 
  myresult=myfunction(param1,param2);

The list of acceptable expressions is a superset of those for the simultaneous declaration and assign. The additional expressions, documented in Section 3.3 and Section 3.4, are as follows:

  <integer-variable> = 
    atoi( <string-variable> ) ;
    atoi( <string-literal> ) ;
    powmod ( <base> , <power> , <modulus> ) ;
    factorize ( <value> ) ;
    factorize ( <value> , <fmin> ) ;
    factorize ( <value> , <fmin> , <fmax> ) ;
    PRP ( <value> ) ;
    PRP ( <value> , <string-literal> ) ;
    PRP ( <value> , <string-variable> ) ;
    fread ( <file-handle> ) ;
    fread ( <file-handle> , & <string-variable> ) ;
    system ( <string-variable> ) ;

    <user-function> ( <parameters> ) ;

3.2.4. Modification Operators

Integer variables can be modified using the following syntax:

  <name> <op>= <value>
  
  where:
    <op> is +, -, *, /, %, <<, or >>.
    Note - there is no space between the operator and the '='.

  <name> = <name> <op> ( <value> )

3.2.5. String Construction

As well as a simple assignment from a literal string, it's possible to construct a string expression from a format string and other variables.

  sprintf ( <string-variable> , <format-string> , <variable-list> ) ;

  where:
    <format-string> is a literal string containing 
      no unescaped semicolons or quote characters, and with
      %d used to interpolate an integer variable, 
      %s used to interpolate a string variable, and
      %% to represent a literal quote character.
    <variable-list> is a comma-separated list of integer and string
      variables.

  sprintf(str, "\"Proth\" prime = %d*2^%d+1, %s", k, n, status);

3.2.6. Pseudovariables

There are five integer pseudovariables which are implicitly used to store some built-in functions return types. They must not be declared explicitly. These variables are:

3.3.1. String Evaluation

It is possible to get PFGW to evaluate a string, and return the value as an integer using the atoi function as follows:

  <integer-variable> = atoi ( <string-variable> ) ;  
  <integer-variable> = atoi ( <literal-string> ) ;

  int k=17;
  int n=12345;
  int p;
  string expr="k*2^n+1";
  p=atoi(expr);

3.3.2. powmod

powmod is a helper function that quickly evaluates a modular exponentiation:

<integer-variable> = powmod ( <arithmetic-expression> , <arithmetic-expression> , <arithmetic-expression> ) ;

  b4096 = powmod(base, 4096, k);

3.3.3. factorize

This function's purpose is to test if a number has small factors, using trial division. Optionally, the bounds for the trial division can be set by calling the function with two parameters to set the lower bound, or three parameters to set both bounds:

  factorize ( <integer-variable> ) ;
  factorize ( <integer-variable> , <arithmetic-expression> ) ;
  factorize ( <integer-variable> , <arithmetic-expression> , <arithmetic-expression> ) ;

  factorize(b4096, 4097);

The FACTORFOUND pseudovariable is always assigned the return value of this function, which is the small factor found, or zero if no small factor is found. However, the return value may optionally be assigned to an ordinary integer variable as well.

This function also sets the ISPRIME pseudovariable to zero if a factor is found.

3.3.4. PRP

The PRP function can be called two ways:

  PRP ( <arithmetic-expression> ) ;
  PRP ( <arithmetic-expression> , <string-expression> ) ;

The function always sets the ISPRIME psuedovariable, but may optionally have the return value assigned to an ordinary integer variable.

The return value is 0 if the expression evaluates to a composite number, and 1 if it evaluates to a (pseudo-)prime.

Note - PFGW honours the -f (and -e, -s, etc.) flags while in script mode; therefore the PRP function will also perform trial division first if so requested.

3.3.5. print

The print function takes a single integer variable and writes it to both the screen and the PFGW log file, appending a new line.

  print ( <integer-variable> ) ;

  print(b4096);

There is no return value from the print function.

3.3.6. puts

The puts function takes a single string variable and writes it to both the screen and the PFGW log file, appending a new line.

  puts ( <string-variable> ) ;

  puts(expr);

There is no return value from the puts function.

3.3.7. printf

The printf function writes a formatted string to both the screen and the PFGW log file, appending a new line.

  printf ( <format-string> , <variable-list> ) ;

  printf("%s => %d", expr, b4096);

There is no return value from the print function.

3.3.8. fopen

The fopen function takes a filename, and a file mode, and returns a file handle which can be used to read from, or write to, the file. See Section 3.3.9 and Section 3.3.10.

  <file-handle> = fopen ( <filename> , <mode> ) ;
  
  where:
    <filename> is a literal string in double quotes or a string variable.
    <mode> is "r" for files opened for reading only
              "w" for files opened for over-writing
	      "a" for files opened for appending

The return value must be assigned to a file variable.

3.3.9. fread

The fread function takes a file handle for a file that was opened for reading (mode "r"), and an optional second parameter which is a reference to a string that is to be set to the literal string read from the file. The function reads a single line from the file, and treats it as a single arithmetic expression.

  <integer-variable> = fread ( <file-handle> ) ;
  <integer-variable> = fread ( <file-handle> , & <string-variable> ) ;

The return value is the integer value of the arithmetic expression read.

3.3.10. write

The write function takes a file handle for a file which was opened for either writing or appending (modes "w" and "a"). It also takes a single integer or string variable which is to be written to the file. A newline is also written to the file after the variable.

  write ( <file-handle> , <integer-variable> | <string-variable> ) ;

There is no return value from the write function.

3.3.11. fprintf

The fprintf function writes a formatted string to the specified file and appends a new line:

  fprintf ( <file-handle> , <format-string> , <variable-list> ) ;

  fprintf(blog, "%s => %d", expr, b4096);

There is no return value from the fprint function.

3.3.12. system

The system function is used to execute an arbitrary string using the underlying command interpreter. By definition this means that it is OS and shell dependent.

  system ( <string-variable> ) ;

  sprintf(gpstr, "echo 'polyrootsmod(polcyclo(%d)-1,%d)' | gp -q > gplog", nn, pp);
  system(gpstr);

The return value of the command is stored in the pseudovariable ERRORLEVEL, and may also optionally be assiged to an integer variable.

3.5.1. Labels and goto Statements

A label is defined by the following syntax:

  <label> :

All labels must be unique, and must also be distinct from any variable names. Labels beginning 'PC' are reserved for use by the script translater.

Flow is transferred to a point specified in the script by a label by using a goto statement with the following syntax:

  goto <label> ;

3.5.2. if Statements

Arithmetic expressions can be used as a boolean predicate to alter the program flow. A value of 0 is taken as false, and any other value is taken as true. The syntax of a simple if statement is:

  if ( <arithmetic-expression> ) {
     <other-statements>
  }

Note - the K&R-style opening brace is mandatory. The other statements are only processed if the predicate is true.

An else clause may also be used:

  if ( <arithmetic-expression> ) {
     <other-statements-1>
  } else {
     <other-statements-2>
  }

In this instance, the statements <other-statements-1> will be processed if the predicate is true, and the statements <other-statements-2> will be processed only if the predicate is false.

3.5.3. do, while, and for Loops

Rudimentary loops can be set up using one of three constructs, each of which has the same general semantics as the C equivalent, viz. "do" loops, "while" loops, and "for" loops.

Explicitly, "do" loops:

  do {
    <other-statements>
  } while ( <arithmetic-expressions> ) ;

  while ( <arithmetic-expression> ) {
    <other-statements>
  }

  for ( <assignment-expression> ; <arithmetic-expression> ; <assignment-expression> ) {
    <other-statements>
  }

The arithmetic expression is treated as a predicate in the same way that it is for if statements. The constructs have the same semantics as they do in C. Note, however, that the K&R-style brace is mandatory.

For "for" loops, the assignment expressions are single assignments to integer variables with the same syntax as an assignment or modify expression as documented in Section 3.2.3 and Section 3.2.4. As in C, the first one is executed once before the loop begins, and the latter one is executed at the end of the loop, just before the condition predicate is evaluated.

Loops may be broken out of early using the break statement. The break statements' syntax, unlike that of C, may contain a parameter which indicates how many levels of nested loops out from which it should break. Its syntax is simply:

  break ;
  break ( <constant> ) ;

  where:
    <constant> is a small decimal integer.

Typical use of break might be as in the following:

  for(mainloop=100; mainloop<200; mainloop+=4) {
    while(condition1) {
      do {
        // statements elided ...
        if(condition2) {
          break(2);
        }
      } while(condition3);
    }
    // the break would jump here
  }

3.5.4. Terminating a Script

A script terminates with the exit function, whose syntax is:

  exit ( ) ;

3.5.5. return Statements

A return statement not within a user-defined function acts identically to an exit() statement. Otherwise, it causes the optional returned value to be returned to the caller of the function:

  return ;
  return <expression> ;

5.1.1. Processing Errors

  Can't include file <filename>

5.1.2. Name or Type Errors

All variables must be declared lexically before, i.e. earlier in the script file than, any usage of that variable. Some illegal usage is detected, and will result in the following error messages:

  Can't <operation> undeclared <type> <variable>.
  Can't declare <variable> as <type>, already a <variable> declared at <line-number>.
  Trying to <operation> <type> <variable> from line <line-number>, should be type <type>.
  Function <name>'s return type (<type>) doesn't match (<type>) in forward declaration on line <line-number>.
  Function <name>'s protoype (<parameter-list>) doesn't match (<parameter-list>) in forward declaration on line <line-number>.

5.1.3. Structural Errors

The braces for if's, do's, and while's must be in sensibly nested pairs. If they aren't, then the following error messages might be seen:

  } with no context.
  } else { with no context.
  } while with no context.
  Can't break requested number of loops.

User-defined functions may not be nested, and attempts to do so will yield an error:

  Cannot nest function <name> within function <name>.

A goto may precede the label to which it jumps. If such labels were missing, then the follow error will be generated:

  goto target ``<name>'' not found.

If the number of closed braces is in deficit, then the following will be seen, which gives some, admittedly cryptic, indication of the constructs which have not been terminated correctly:

  Context=<list>.

The follwing errors will hopefully never be seen:

  Breakage=<number>.

5.1.4. Other Errors

Sometimes the translater just has to give up, as it doesn't know what is going on. If that is the case, you'll see the following:

  Can't parse line.