All Past Downloads

• procedure loadProject(XMLorTXTFileName : string, nodeToLoad : tree)
  

  Parameter	Type	Description
  XMLorTXTFileName	string	an input file whose content describes a node
  nodeToLoad	tree	the node to populate from the file; if omitted, it is defaulted to the global variable \samp{project}

  Loads a parse tree previously saved thanks to saveProject().

• function existDirectory(path : string) : bool
  

  Parameter	Type	Description
  path	string	path name of the directory

  The function checks the existence of a directory specified by the path argument.

• procedure extendExecutedScript(scriptContent : string)
  

  Parameter	Type	Description
  scriptContent	string	A piece of CodeWorker's script to compile at the end of the currently executed script

  Extend the currently executed CodeWorker's script with new instructions. The argument scriptContent is a piece of script to compile at the end of the executed script.

• function equalLastWrittenChars(text : string) : bool
  

  Parameter	Type	Description
  text	string	string value to compare

  Compare the text argument with last characters written in the output file.

This directive is located anywhere in the script to study, and requires a variable the code generation engine will populate with coverage data. The variable will be a list of sorted segments, entirely determined by their starting position in the output and by the position of the corresponding script instruction. These positions are respectively stored in attributes output and script.

An added information is assigned to the node representing the segment. It specifies the type of script instruction, belonging to one of the following values:

• R: rough text,
• W: expression, variable or call to a writeText()-family procedure,
• I: call to a insertText()-family procedure,
• O: call to overwritePortion() procedure,

Example:

rough text @this.name@ EOL
@
#coverage(project.coverage)

Let say that this.name is worth "VARIABLE_CONTENT". The script generates the following output file:

rough text VARIABLE_CONTENT EOL

The variable project.coverage is then worth the following list:

   ["0"] = "R"
     |--+
       script = 12
       output = 0
   ["1"] = "W"
     |--+
       script = 21
       output = 11
   ["2"] = "R"
     |--+
       script = 29
       output = 27

      Tree structure of the variable populated by the BNF engine
      for #matching(variable):
     
      * variable
        |
        +- rules[]: list of production rules (signatures only),
        |
        +- areas[]: table of positions in the input text, the
          | key is worth the position P; no item value
          +- begin[]: (optional) table for every rule starting
          | | at the position P, the key being worth the
          | | ending position Pf (decreasing order)
          | +- []: list of all rules matching [P, Pf] exactly,
          |
          +- end[]: (facultative) table for every rule ending at
            | the position P, the key being worth the
            | starting position Pi (increasing order)
            +- []: list of all rules matching [Pi, P] exactly,

Conditions conform to the syntax of usual CodeWorker expressions. When a break/watchpoint is activated, a block of instructions can be executed. The block is a piece of CodeWorker script.

• function duplicateIterator(oldIt : iterator, newIt : treeref) : bool
  

  Parameter	Type	Description
  oldIt	iterator	the original iterator to duplicate
  newIt	treeref	copy of the original iterator

  Duplicates an iterator or returns false if oldIt isn't an iterator.

• function createIterator(i : iterator, list : treeref) : bool
  

  Parameter	Type	Description
  i	iterator	iterator to initialize
  list	treeref	the iterator will point to the beginning of this list

  The variable i will become an iterator pointing to the first item of the list.

  If the list is empty, there is no iterator created and the function returns false.

  i must have been declared before.

• function createReverseIterator(i : iterator, list : treeref) : bool
  

  Parameter	Type	Description
  i	iterator	iterator to initialize
  list	treeref	the iterator will point to the end of this list

  The variable i will become an iterator pointing to the last item of the list and will iterate in the reverse order.

  If the list is empty, there is no iterator created and the function returns false.

  i must have been declared before.

• function index(i : iterator) : int
  

  Parameter	Type	Description
  i	iterator	iterator of a \samp{foreach} statement

  Returns the position of the item the iterator points to. The position in the list begins counting at 0.

• function prec(i : iterator) : bool
  

  Parameter	Type	Description
  i	iterator	iterator of a \samp{foreach} statement or pointing to items of a list

  The iterator will now point to the precedent item of the list and returns true if exists.

• function next(i : iterator) : bool
  

  Parameter	Type	Description
  i	iterator	iterator of a \samp{foreach} statement or pointing to items of a list

  The iterator will now point to the next item of the list and returns true if exists.

In front of a variable name never declared, the behaviour remains the same: the variable is inserted to the this context automatically as a new attribute.

The rationale is firstly for improving the reliability of scripts, detecting bad variable names like spelling or foolish mistake in the name, and secondly to prepare the introduction of Object-Oriented Programming into CodeWorker.

• function addToDate(date : string, format : string, shifting : string) : string
  

  Parameter	Type	Description
  date	string	the date to change
  format	string	the format to apply on the reading of the \samp{shifting} argument
  shifting	string	the offset values to apply on the date, whose meanings are known by the \samp{offset} argument

  Change a date by applying offset values on its internal representation. The internal representation holds the year / month / day and hour / minute / second and millisecond fields. You choose what fields to shift, giving a date format as the first argument, and an offset value for each fields seen in the format as the second argument.

  The field types have the same syntax as in the function formatDate, except that the field values might be negative.
  For instance, if the field type is "%m", the month must occupy 2 digits maximum for a positive offset, and 3 characters for a negative offset, the first one being the sign.

  The offsets are applied in the order they are read, from the left-hand side to the right.

  The function returns the value of the date after applying the shift.

• procedure allFloatingLocations(list : tree)
  

  Parameter	Type	Description
  list	tree	floating location names and their position

  Populates the argument list with all floating location registered to the current output stream, such as the entry key is the floating location name and the entry value is the position in the stream.

• function removeFloatingLocation(key : string) : int
  

  Parameter	Type	Description
  key	string	name of an existing floating position into the output stream

  Removes the floating location attached to key and returns its position. If the floating location belongs to a parent output stream, it is removed from the parent.

  The function returns a negative integer if the floating location doesn't exist.

• function sqrt(x : double) : double
  

  Parameter	Type	Description
  x	double	the number we want to calculate the square root

  Calculates the square root of x.

  An invalid number causes the function to throw an error.

• procedure sleep(millis : int)
  

  Parameter	Type	Description
  millis	int	how many milliseconds the execution must be suspended

  The procedure suspends the execution for millis milliseconds.

• procedure incrementIndentLevel()
  Increments the indentation level, used to indenting output files automatically while writing.

  If first call, it enables the indent-mode: each time a text will have to be written at the beginning of a line, the line will be indented, depending on the indentation level.

  Call the function decrementIndentLevel() to decrease the indentation.

• function decrementIndentLevel() : bool
  Decrements the indentation level, used to indenting output files automatically while writing.

  If the function returns false, the indentation level is worth zero and it disables the indent-mode. Otherwise, each time a text will have to be written at the beginning of a line, the line will be indented, depending on the indentation level.

  Call the function incrementIndentLevel() to increase the indentation.

{"a", {"yellow", "red"}, "submarine"}

• function isNumeric(number : string) : bool
  

  Parameter	Type	Description
  number	string	a floating-point number in text representation

  This predicate checks whether the string passed by parameter is a floating-point or not.

• if you parse a double at the beginning of "2. is a floating point", 2. is consumed.
• if you parse a double at the beginning of "2..n", 2 only is consumed.

• procedure insertElementAt(list : treeref, key : string, position : int)
  

  Parameter	Type	Description
  list	treeref	an array of nodes
  key	string	the entry key of the element to insert
  position	int	where to insert the new element, starting at 0

  Insert a new element to list, at a position given by the argument position. The argument key indicates the key of this element, which is built empty.

  If the key is an empty string, then the key is supposed to be worth the size of the list automatically.

  You can access the new element by writing either:
  

  list#[position]

  
  or
  

  list[key]

• aVariable#front ignored during the C++ translation in some cases,
• the keyword cascading wasn't taken into account while translating foreach and forfile,
• the return value of a BNF symbol (piece of text matched) wasn't concatenated correctly when needed (functionality rarely required).

Example:

// declaration of 3 local variables in one shot
local a = "1", b, c= 2;

Examples for a plugin named MyModule:

MyModulecw_d.dll
MyModulecw_d.so

Example:

scanFiles(dir, "project/examples", "src/*.cpp", true)

"project/examples/airplanes/src/*.cpp"
"project/examples/boats/yacht/src/*.cpp"
"project/examples/bicycles/src/*.cpp"

• the BNF directive #skipIgnore,
• the BNF binary operator ‘|>‘,

• initialization of predefined global variables (_ARGS and _REQUEST),
• C++ writing of variable expressions in general,
• implicit copy in a translation script,

<filename>(line-number): <error-message>

"<filename>" line line-number): <error-message>

• function countInputCols() : int
  Determines the column number in the line where the parse cursor points to.

• function countOutputCols() : int
  Determines the column number in the line where the output stream cursor points to.

Example:

#moveAhead [A]? [B]?

If A doesn‘t match, then B must match so that the scan has read at least one character.

• function getShortFilename(pathFilename : string) : string
  

  Parameter	Type	Description
  pathFilename	string	a file name with its path

  Returns the short name of a file, meaning without the path. It is composed of a radical + an extension.

codeworker <script-file> <arg1> ... <argN> [<switch>]*

It is more natural than the equivalent writing:

codeworker -script <script-file> -args <arg1> ... <argN> [<switch>]*

Example:

      local list;
      insert list["silverware"] = "tea spoon";
      insert list["Mountain"] = "Everest";
      insert list["SilverWare"] = "Tea Spoon";
      insert list["Boat"] = "Titanic";
      insert list["acrobat"] = "Circus";
     
      traceLine("Sorted list in a classical order:");
      foreach i in sorted by_value list {
          traceLine("\t" + i + " -> " + key(i));
      }


Output:
    Titanic -> Boat
    Everest -> Mountain
    Tea Spoon -> SilverWare
    Circus -> acrobat
    tea spoon -> silverware

An example is encapsulating a Trolltech-Qt widget for building GUI, implemented in a plugin or in an application linking with the CodeWorker‘s library, and handled from a CodeWorker‘s script.

• function computeMD5(text : string) : string
  

  Parameter	Type	Description
  text	string	the string to encrypt in MD5

  Computes the MD5 of a string.

  This optimized MD5 implementation conforms to RFC 1321.
  Source: http://www.cr0.net:8040/code/crypto/md5/
  Copyright 2001-2004 Christophe Devine

• function getWriteMode() : string
  Returns how text is written during a generation or during an implicit copy while translating: "insert" or "overwrite" mode (default mode).

• procedure setWriteMode(mode : string)
  

  Parameter	Type	Description
  mode	string	is worth \samp{"insert"} or \samp{"overwrite"}

  Selects how to write text during a generation and how to apply an implicit copy during a translation.

  By default, a text is written in overwrite mode (mode = "overwrite"): if the file cursor doesn‘t point to the end of the current output file, the new text overwrites the old one and the remaining, if any, is inserted at the end.
  The insert mode (mode = "insert") causes a shift of the old text, so as to preserve it.

• function addGenerationTagsHandler(key : string, reader : script, writer : script) : bool
  

  Parameter	Type	Description
  key	string	designates the handler
  reader	script	extended-BNF script of the reader
  writer	script	template-based script of the writer

  Adds a new generation tags handler, designated by key.

  Returns true if key isn‘t reserved yet for another generation tags handler.

• function removeGenerationTagsHandler(key : string) : bool
  

  Parameter	Type	Description
  key	string	designates the handler to remove

  Removes the current generation tags handler amongst those previously registered thanks to the function addGenerationTagsHandler(). If the current generation tags handler is worth this one, no custom handler is selected.

  Returns true if key designates a registered handler.

• function selectGenerationTagsHandler(key : string) : bool
  

  Parameter	Type	Description
  key	string	designates the handler to take

  Selects the current generation tags handler amongst those previously registered thanks to the function addGenerationTagsHandler(). If the parameter key is worth false (empty string), the default generation tags handler is used.

  Returns true if key designates a registered handler.

• procedure sortArray(array : tree)
  

  Parameter	Type	Description
  array	tree	the array node to sort

  Sort an array in the lexicographical order of the entry keys.

• procedure listAllGeneratedFiles(files : treeref)
  

  Parameter	Type	Description
  files	treeref	populated with the names of all files generated since the interpreter has launched

  Populates the parameter files with the list of all output files generated since the interpreter has launched.

  The array files indexes each node with the name of the generated output file, and each node owns a branch called scripts.
  This branch gives the list of all template-based scripts that have contributed to the generation of the output file (often one script only, but could be more).
  The key index and the value of the nodes in the array scripts are worth the script file names.

  The procedure raises an error if the tree parameter files doesn‘t exist.

• function createDirectory(path : string) : bool
  

  Parameter	Type	Description
  path	string	the path of directories to create

  This function creates a new directory and returns whether the operation has succeeded or not.

  It fails if the complete path already exists, or if it is invalid.

The structure of the grammar is so rich that it is a challenge to find a text editor, which offers a syntax highlighting engine powerful enough. JEdit proposes the writing of production rules to describe it, so it is possible to express the syntax highlighting of the scripting language.

You‘ll find a package dedicated to JEdit on the Web site, for the inclusion of these new highlighting modes. Many thanks to Patrick Brannan for this contribution.

• function translateString(patternFileName : script, this : tree, inputString : string) : string
  

  Parameter	Type	Description
  patternFileName	script	file name of the \textit{pattern script}, which merges both the BNF syntax and the source code generation tags
  this	tree	the current node that will be accessed via \textit{this} variable
  inputString	string	the input string to parse

  Parses the input string given by the argument inputString and returns the output string resulting of the translation, following the instructions of the pattern script called patternFileName.

  The pattern script merges the BNF syntax presented section BNF syntax with the source code generation syntax described section source code generation.

It defines a rule that describes how to transform the header (left member) and the production rule (right member) of a non-terminal declaration.

Example:

INTEGER ::= #ignore [‘0‘..‘9‘]*;


INTEGER is the header and #ignore [‘0‘..‘9‘]* is the production rule.

During the compilation of a BNF parse script, before processing the declaration of a non-terminal, the compiler checks whether a transforming rule validates the name of the non-terminal. If so, both the header of the declaration and the production rule are translated, following the directives of the rule.

The #transformRules statement must be put in the BNF script, before the production rules to transform.

It means that A and/or B match(es), which justifies the syntax of the operator.

• function countOutputLines() : int
  Determines the line number of where the cursor points in the output stream.

Using #nextStep allows changing the shift of the cursor to more than one character. It is very useful when you encounter quoted strings or identifiers. For instance, if you are looking for constant strings and then number or identifiers, the following code is incorrect:

->[#readCString #readInteger | #readIdentifier]

Why is it incorrect? If the constant string matches but not the integer, the next iteration will put the cursor just after the quote and will perhaps point to an identifier, embedded into the constant string. Then, the operator will match during the second iteration.

In fact, if the constant string matches but not the rest of the BNF sequence, we want to force the next jump just after the constant string:

->[#readCString #nextStep #readInteger | #readIdentifier]

Hit a key to interrupt the display of trace information and to pause the controlling sequence.

• function inputKey(echo : bool) : string
  

  Parameter	Type	Description
  echo	bool	asks for echoing the standard input on the console

  Returns a character extracted from the standard input, the keyboard generally. If no key was pressed, it returns an empty string.

  See statement modifiers file_as_standard_input (file as standard input) and string_as_standard_input (string as standard input) to change the source of the standard input.

  If the source of the standard input is the keyboard, the argument echo has no effects. Otherwise, the input text is displayed into the console only if echo is worth true.

Now, you can specify to concatenate the covered text to the ancient value of the variable: B:+v.

Example:
If v is worth "nebula:" and if the sentence starts with "Orion.", then v becomes "nebula:Orion" after the resolution of #readIdentifier:+v.

Example:

function f(x : node) {/*is a synonym of f<"">(x : node)*/}

function f<T>(x : node) {{
      // ‘{{‘ announces a template–based script, which
      // will generate the correct implementation during the instantiation
      insert x.@T@ = "@T@";
      f<"@T.rsubString(1)@">(x);
@
      // ‘}}‘ announces the end of the template–based script
}}

f<"field">(project);
traceObject(project);


Output:

Tracing variable ‘project‘:
      field = "field"
      fiel = "fiel"
      fie = "fie"
      fi = "fi"
      f = "f"
End of variable‘s trace ‘project‘.

The sequence A |> B is understood as considering the sub sentence scanned by A, which delimits the portion of text left visible to B. B starts scanning at the beginning of the sub sentence covered by A and cannot go beyond.

When the operator has achieved with success, the cursor points to the end of the sub sentence covered by A.

You‘ll find below the different steps processed by the operator:

• the BNF literal A is executed,
• if success, the cursor comes back to the beginning of the sub sentence covered by A
• then, B is executed, knowing that the operator forces the end of the sub sentence where A had finished,
• if success, the cursor points to the end of A, even if B hadn‘t scan up to the end of the sentence.

Example:

We want to recognize all colons present on a line. The sub sentence we would like to scan is a line: –>‘\n‘. Recognizing colons is like: [–>‘:‘]*, which asks for jumping from a colon to another, without considering the end of line.
–>‘\n‘ |> [–>‘:‘]* restricts the colon recognition to the line.

–>A jumps just after the the first matching of A in the sentence. It processes the equivalent piece of extended–BNF script:

=> local iLocation;
~[A => iLocation = getInputLocation();]*
=> setInputLocation(iLocation);


To intervene on the boundaries of the repeated sequence [A ...]*, an extension was added to the syntax: –>boundaries A, where boundaries gives the multiplicity of the bracketed sequence (‘?‘, ‘+‘, ‘2..*‘, #repeat(iBegin, iEnd) ...).
Note: the boundaries must be declared just after the arrow.

The text covered by –>A includes the unmatched characters plus the sub sentence scanned by A, so –>A:v assigns the complete covered text to the variable v. This is sometimes a drawback: perhaps do you want to take the unmatched character or the sub sentence scanned by A.
So now, you can specify the variables intended to receive these intermediate values:
–>(:varBefore –:varAfter)A:varTotal
Note: the intermediate variables are declared just before the BNF symbol A, after the boundaries if any.

Example:
We will apply [–>(:varBefore –:varAfter) #readNumeric]:varTotal on the sentence "Garfield.laziness 99.99 percent":

• varBefore = "Garfield.laziness "
• varAfter = "99.99"
• varTotal = "Garfield.laziness 99.99"

The last extension brought to the jump operator –>A is to allow the execution of a BNF sequence at the beginning of the sub sequence matched by A. This BNF sequence is declared into the parenthesis used for the intermediate variables, behind these variables, if any:
–>(:varBefore –:varAfter B)A
The advantage of infiltrating the BNF sequence B is that the intermediate variables are populated, and that the cursor doesn‘t point after the matching of A yet, but at the beginning of the sub sentence matched by A.

• function getVariableAttributes(variable : treeref, list : tree) : int
  

  Parameter	Type	Description
  variable	treeref	the variable to explore
  list	tree	will contain the name and type (reference to another node or not) of each attribute

  Populates a list with all attribute names of a tree node. The name of branches just below the node variable are put into list.

  The attribute‘s name is a key in the list and there is no value assigned to the item, except for attributes that point to another node (a reference). In that case, the item is worth the complete name of the referenced node.

  The function returns the number of attributes found, or a negative value (–1) if the tree node variable doesn‘t exist.

  Note: use #evaluateVariable() to navigate along a tree node, where the complete name is determined at runtime.

Now, customized ignore clauses are declared with a key between brackets :
#ignore["designate this ignore clause"] ::= /*production rule*/;.

Into production rules, you specify the change with #ignore(textit{"designate this ignore clause")}.

Example:

["–––" #break | attribute]+


Here, the engine reads at least one attribute, and leaves with success when it encounters the string "–––".

• function joinStrings(list : tree, separator : string) : string
  

  Parameter	Type	Description
  list	tree	the list that contains the strings to join
  separator	string	the sequence of chars that separates the strings

  This function returns the concatenation of all strings put into list, putting a separator between each of them.

  If the list is empty, the function will return an empty string.

• function equalsIgnoreCase(left : string, right : string) : bool
  

  Parameter	Type	Description
  left	string	first string to compare
  right	string	second string to compare

  Compares two strings, ignoring the case. It returns true when the comparison succeeds.

• more functions to handle parse trees,
• call of CodeWorker‘s functions from the plug–in

You can integrate your own functions or interface layers to work with databases or any other gluing requirements.

• procedure appendFile(filename : string, content : string)
  

  Parameter	Type	Description
  filename	string	name of the file to append
  content	string	sequence of characters to write at the end of the file

  Writes the text content at the end of the file filename.

  If the file doesn‘t exist, the function creates it.

• function composeSQLLikeString(text : string) : string
  

  Parameter	Type	Description
  text	string	a sequence of character to convert to a SQL-like string

  Returns the conversion of the sequence of characters given by argument text to a SQL–like string, without single quote delimiters. It means that special characters of text are replaced by their escape sequence, the rest remaining the same.

  It recognizes the following escape sequences:

  • ‘\\‘ as backslash (\), ASCII value 92,
  • ‘\‘ ‘ as single quotation mark (‘), ASCII value 39,
  • ‘\"‘ as double quotation mark ("), ASCII value 34,
  • ‘\a‘ as alert (BEL), ASCII value 7,
  • ‘\b‘ as backspace (BS), ASCII value 8,
  • ‘\f‘ as formfeed (FF), ASCII value 12,
  • ‘\n‘ as newline (LF), ASCII value 10,
  • ‘\r‘ as carriage return (CR), ASCII value 13,
  • ‘\t‘ as horizontal tab (HT), ASCII value 9,
  • ‘\v‘ as vertical tab (VT), ASCII value 11,
  The function translates the single quote to an escape sequence "\‘", instead of repeating twice the single quote as in the SQL–standard. It presents the advantage of being more readable, but if you encounters a drawback in using this translation, apply replaceString() to change "\‘" in "‘‘".

• function getOutputFilename() : string
  Returns the path of the output file being generated.

• function ceil(number : double) : int
  

  Parameter	Type	Description
  number	double	the floating-point number to ceil

  Returns the smallest integer that is greater than or equal to number. If number isn‘t a number, the function returns 0.

• function exp(x : double) : double
  

  Parameter	Type	Description
  x	double	the floating-point whose exponential is to compute

  Returns the exponential of x.

  On underflow, it returns 0.
  On overflow, it returns infinite.

• function log(x : double) : double
  

  Parameter	Type	Description
  x	double	the floating-point whose logarithm is to compute

  Returns the logarithm of x.

  If x is negative, it throws an error.
  If x is 0, it returns infinite.

It avoids the writing of a specific script file each time the developer requires a task of parsing or code generation.

Example:

//generation of an HTML file, which shows the title and the content
//of some financial market news previously extracted
generate(
{<html>
   <body>
@
foreach i in this.news {
     @@composeHTMLLikeString(i.title)@<br>@endl()@@
     @<table><tr><td>@endl()@@
       @@composeHTMLLikeString(i.body) + endl()@@
     @</td></tr></table>@endl()@@
}
@   </body>
</html>
@}, project, "news.html");

• It avoids the writing of 2 files, as it was unavoidable before:
  

  generate("news2HTML.gen", project, "news.html");

• such as "news2HTML.gen", which contains:
  

  <html>
   <body>
@
foreach i in this.news {
     @@composeHTMLLikeString(i.title)@<br>@endl()@@
     @<table><tr><td>@endl()@@
       @@composeHTMLLikeString(i.body) + endl()@@
     @</td></tr></table>@endl()@@
}
@   </body>
</html>

Example: getInputFilename() isn‘t allowed in a common script, because it should be present in parse scripts only (it gives the name of the file being currently parsed). Now, if you try to use this function in a common script, a syntax error occurs.

• function resolveFilePath(filename : string) : string
  

  Parameter	Type	Description
  filename	string	the path of the file to resolve

  Searches the file filename in the current directory and, if fails, it continues searching it in the include directories (‘–I‘ switch on the command line).

  It returns the location of the file in directories, removing any ambiguity.
  If the file doesn‘t exist, the function returns an empty string.
  If filename points to a virtual file, the function returns filename.
  

• function countInputLines() : int
  Determines the current line number where the parse cursor points to.

• function getInputFilename() : string
  Returns the path of the input file being parsed.

The directive is always true, even if the parsing has already reached the end of file or if there are no insignificant characters.

• function skipEmptyCppExceptDoxygen() : bool
  Ignores all blank characters and all C++/JAVA–like comments, except when the comment conforms to the Doxygen format. The current file position moves to the first character that must be kept.

Classical example:

function f<1>() { return 1; }
function f<N>() { return $N*f<$N – 1$>()$; }
traceLine("10! = " + f<10>());

[BNF–sequence]#repeat(begin–expression[, end–expression])

• function hostToNetworkLong(bytes : string) : string
  

  Parameter	Type	Description
  bytes	string	a 4-bytes representation of a long integer sorted in the host bytes order

  Converts a 4–bytes representation of a long integer to the network bytes order. CodeWorker stores a byte as a 2–hexadecimal digits; the function raises an error if the argument bytes is malformed.

  Use longToBytes() and bytesToLong() to swap between decimal and host binary representation of a long integer.

• function networkLongToHost(bytes : string) : string
  

  Parameter	Type	Description
  bytes	string	a 4-bytes representation of a long integer sorted in the network bytes order

  Converts a 4–bytes representation of a long integer to the host bytes order. CodeWorker stores a byte as a 2–hexadecimal digits; the function raises an error if the argument bytes is malformed.

  Use longToBytes() and bytesToLong() to swap between decimal and host binary representation of a long integer.

• function hostToNetworkShort(bytes : string) : string
  

  Parameter	Type	Description
  bytes	string	a 2-bytes representation of a short integer sorted in the host bytes order

  Converts a 2–bytes representation of a short integer to the network bytes order. CodeWorker stores a byte as a 2–hexadecimal digits; the function raises an error if the argument bytes is malformed.

  Use shortToBytes() and bytesToShort() to swap between decimal and host binary representation of a short integer.

• function networkShortToHost(bytes : string) : string
  

  Parameter	Type	Description
  bytes	string	a 2-bytes representation of a short integer sorted in the network bytes order

  Converts a 2–bytes representation of a short integer to the host bytes order. CodeWorker stores a byte as a 2–hexadecimal digits; the function raises an error if the argument bytes is malformed.

  Use shortToBytes() and bytesToShort() to swap between decimal and host binary representation of a short integer.

• function longToBytes(long : ulong) : string
  

  Parameter	Type	Description
  long	ulong	an unsigned long integer using the decimal base

  Converts an unsigned long integer in decimal base to its 4–bytes representation. Bytes are ordered in the host order (memory storage).

• function shortToBytes(short : ushort) : string
  

  Parameter	Type	Description
  short	ushort	an unsigned short integer using the decimal base

  Converts an unsigned short integer in decimal base to its 2–bytes representation. Bytes are ordered in the host order (memory storage).

• function bytesToShort(bytes : string) : ushort
  

  Parameter	Type	Description
  bytes	string	a 2-bytes representation of an unsigned short integer (host bytes order)

  Converts a 2–bytes representation of an unsigned short integer to its decimal representation. Bytes are ordered in the host order (memory storage).

  If the argument bytes is malformed, the function raises an error.

• function bytesToLong(bytes : string) : ulong
  

  Parameter	Type	Description
  bytes	string	a 4-bytes representation of an unsigned long integer (host bytes order)

  Converts a 4–bytes representation of an unsigned long integer to its decimal representation. Bytes are ordered in the host order (memory storage).

  If the argument bytes is malformed, the function raises an error.

• #readBytes(length–expr): to read a sequence of bytes, where the arithmetic expression length–expr determines how many bytes to read,
• #readChars(length–expr): to read a sequence of characters, where the arithmetic expression length–expr determines the length of the text,

• function createINETClientSocket(remoteAddress : string, port : int) : int
  

  Parameter	Type	Description
  remoteAddress	string	a remote IP address (Internet namespace)
  port	int	a remote port number

  This function creates a client socket and connects it to the specified remote port, at the specified address IP remoteAddress, and returns a new socket descriptor. The socket is of type stream.

  Once the creation has achieved, use directly the send/receive functions or attachInputToSocket()/attachOutputToSocket for reading/writing to the socket via a BNF–parsing/template–based script.

• function createINETServerSocket(port : int, backLog : int) : int
  

  Parameter	Type	Description
  port	int	a local port number
  backLog	int	maximum queue length for incoming connection (1-5)

  This function creates a server socket bound to port and returns a new socket descriptor. The socket is of type stream.

  The argument backLog specifies the size of the queue connection. A new connection is refused when the queue is full.

  Once the creation has achieved, use the function acceptSocket() to wait for a new client connection (blocking call).

• function acceptSocket(serverSocket : int) : int
  

  Parameter	Type	Description
  serverSocket	int	a server socket previously created via \samp{createINETServerSocket()}

  This function blocks until a client connection arrives, and returns the corresponding socket descriptor.

  Once a connection has been established, use directly the send/receive functions or attachInputToSocket()/attachOutputToSocket for reading/writing to the socket via a BNF–parsing/template–based script.

• procedure attachInputToSocket(socket : int)
  

  Parameter	Type	Description
  socket	int	a client socket descriptor

  Joins the input stream of a parsing script to a socket stream: each time that the input stream pointer reaches the end, the interpreter waits for bytes coming from the socket.

  Waiting for bytes is a blocking process, so once you don‘t expect for other bytes anymore, don‘t forget to detach the socket via the procedure detachInputFromSocket() before reaching the end of the stream.

• procedure detachInputFromSocket(socket : int)
  

  Parameter	Type	Description
  socket	int	a client socket descriptor

  Disconnects the input stream of a parsing script from a socket stream. You should have join the socket to the input stream before, via the procedure attachInputToSocket().

• procedure attachOutputToSocket(socket : int)
  

  Parameter	Type	Description
  socket	int	a client socket descriptor

  Joins the output stream of a template–based or translation script so that to send the generated text to the socket.

  The generated text is sent at the end of the complete script execution.

• procedure detachOutputFromSocket(socket : int)
  

  Parameter	Type	Description
  socket	int	a client socket descriptor

  Disconnects the output stream of a parsing script from a socket stream. You should have join the socket to the output stream before, via the procedure attachOutputToSocket().

  To call only if you have changed your mind and don‘t want the generated text to be sent to the socket at the end of the template–based script execution anymore.

• function flushOutputToSocket(socket : int) : bool
  

  Parameter	Type	Description
  socket	int	a client socket descriptor

  Sends to a socket the complete text or binary data already generated by the template–based or translation script. The function then purges the output stream.

  This function has no link with attachOutputToSocket(). It only requires that the socket descriptor exists and is opened correctly.

• function receiveBinaryFromSocket(socket : int, length : int) : string
  

  Parameter	Type	Description
  socket	int	a client socket descriptor
  length	int	number of bytes to read

  This function waits for length bytes to read from socket, and returns a sequence of bytes (CodeWorker represents a byte with 2 hexadecimal digits).

  If an error occurs, the function returns an empty string.

• function receiveFromSocket(socket : int, isText : boolref) : string
  

  Parameter	Type	Description
  socket	int	a client socket descriptor
  isText	boolref	the function will populate this parameter with \samp{true} if read bytes designate a string and \samp{false} if they are binary data

  This function waits for bytes to read from socket and returns them. If an error occurs, the function returns an empty string.

  The function sets isText to:
  

  • true if it has received a text,
  • false if it has received binary data: the returned string is then a sequence of bytes (CodeWorker represents a byte with 2 hexadecimal digits),

• function receiveTextFromSocket(socket : int, length : int) : string
  

  Parameter	Type	Description
  socket	int	a client socket descriptor
  length	int	size of the text to read

  This function waits for length bytes to read from socket, and returns a string.

  If an error occurs, the function returns an empty string.

• function sendTextToSocket(socket : int, text : string) : bool
  

  Parameter	Type	Description
  socket	int	a client socket descriptor
  text	string	the text to write

  This function writes a text to a socket and returns true if it has achieved successfully.

• function sendBinaryToSocket(socket : int, bytes : string) : bool
  

  Parameter	Type	Description
  socket	int	a client socket descriptor
  bytes	string	a sequence of bytes to write

  This function writes binary data to a socket and returns true if it has achieved successfully.

  The function raises an error if a byte passed to bytes is malformed: CodeWorker expects 2 hexadecimal digits to represent a byte.

• procedure closeSocket(socket : int)
  

  Parameter	Type	Description
  socket	int	a \textit{client}/\textit{server} socket descriptor

  This procedure closes the socket descriptor specified to the argument socket.

• procedure insertTextToFloatingLocation(location : string, text : string)
  

  Parameter	Type	Description
  location	string	the name of a floating location
  text	string	sequence of characters to insert

  Inserts a sequence of characters passed to argument text, at the position of the floating location, whose name is given by the argument location.

  If the floating location doesn‘t exist, the function raises an error.

  In expansion mode, the floating location might point into a markup area previously generated. So, on the contrary of insertText(), the function permits to insert text out of the current markup area.

• procedure insertTextOnceToFloatingLocation(location : string, text : string)
  

  Parameter	Type	Description
  location	string	the name of a floating location
  text	string	sequence of characters to insert

  Inserts a sequence of characters passed to argument text, at the position of the floating location, whose name is given by the argument location, but only if the text has never been encountered previously by a insertTextOnce() or a writeTextOnce()procedure.

  If the floating location doesn‘t exist, the function raises an error.

  In expansion mode, the floating location might point into a markup area previously generated. So, on the contrary of insertTextOnce(), the function permits to insert text out of the current markup area.

• function existFloatingLocation(key : string, parent : bool) : bool
  

  Parameter	Type	Description
  key	string	name of a floating position into the output stream
  parent	bool	while expanding a file, search into precedent markup area if this floating location exists or not

  Returns true if the floating location, whose name is passed to argument key, already exists.

  If required (parameter parent set to true) and if the current output file is being expanded, the function searches the floating location in precedent visited markup areas.

The tool uses libcurl for sending HTTP requests only. If you don‘t need this functionality, you might recompile sources after having disabled the preprocessor definition CODEWORKER_CURL_LIB.

foreach i in reverse sorted list ...

• procedure autoexpand(outputFileName : string, this : treeref)
  

  Parameter	Type	Description
  outputFileName	string	the existing file to expand
  this	treeref	the current node that will be accessed with \textit{this} variable

  Expands an existing file whose name is passed to the argument outputFileName, executing template–based scripts located at each markup. The file contains its own scripts for expanding code.

  Expanding a file consists of generating code into marked out areas only, the rest of the file remaining the same. The markup is put into a comment, knowing that the syntax of the comment must conform to the type of the expanded file outputFileName. So, an HTML file expects <!– – and – –>, a JAVA file is waiting for // and "\n", ... The markup is announced by ##markup## followed by a string that represents the markup key. Don‘t forget to configure correctly the syntax of comment boundaries with procedures setCommentBegin() (see setCommentBegin()) and setCommentEnd() (see setCommentEnd()).

  When the procedure is called, CodeWorker jumps from a markup to another. To handle a markup, it checks whether text was already generated, put between tags ##begin##"markup–key" and ##end##"markup–key", added automatically the first time an expansion is required, to demarquate the portion of code that doesn‘t belong to the user. Then, it extracts all protected areas, if any, and it generates code at the position of the markup, adding begin/end tags seen before.

  The interpreter reclaims the tags ##script## just after the markup. It extracts the embedded text, considered as a template–based script, eventually put between comments, and the interpreter executes this embedded script.

  Note that some data might be put between tags ##data##, accessible in the template–based script via the function getMarkupValue() (see getMarkupValue()). This block of custom data comes after the ##script## tag, if present.

  Be careful not to confuse this prodedure with generate() that doesn‘t care about markups and that overwrites the output file completely, except protected areas of course.

• procedure traceEngine()
  Traces some states about the interpreter and the current script.

• function getMarkupValue() : string
  This function must be called into a pattern script that runs in expansion mode. It returns the current markup value, if any, put between tags ‘##data##‘ after declaring the markup key.

• function changeFileTime(filename : string, accessTime : string, modificationTime : string) : int
  

  Parameter	Type	Description
  filename	string	name of the file to set
  accessTime	string	date-time of the last access
  modificationTime	string	date-time of the last modification

  The function changes the access and modification times of the file filename. The user ID of the process must be the owner of the file, or the process must have appropriate privileges.

  In case of failure, the function returns a negative integer:

  • –1: unknown error that shouldn‘t appear,
  • –2: permission denied,
  • –3: too many files have been opened,
  • –4: file not found,
  • –5: invalid times argument,

Example:
nonterminal<"Case 1"> ::= ...;
nonterminal<"Case 2"> ::= ...;
are instantiations of nonterminal resolved for "Case 1" and "Case 2".
nonterminal<T> ::= ...;
is a template BNF clause where the instantiation isn‘t resolved and that describes the generic implementation of the production rule. It will be called for "Case 3" or any constant different of "Case 1" and "Case 2".

• procedure randomSeed(seed : int)
  

  Parameter	Type	Description
  seed	int	a new seed for generating pseudorandom integers

  Sets the seed for generating a series of pseudorandom integers. To change the seed to a given starting point, choose any positive value different of 1 as the seed argument. A value of 1 reinitializes the generator. Any negative value let CodeWorker choose a random seed for you.

• function randomInteger() : int
  Generates a pseudorandom number.

• procedure copyGenerableFile(sourceFileName : string, destinationFileName : string)
  

  Parameter	Type	Description
  sourceFileName	string	the name of the file to copy
  destinationFileName	string	the name of the copy

  This procedure copies a generable file sourceFileName to another location destinationFileName if the files have differences in the hand–typed text. It raises an error if something wrong has happened (either the source file doesn‘t exist or permissions are insufficient for copy).

  A generable file is any source file containing protected areas or expandable markups.

• function UUID() : string
  This function generates an UUID and returns it as a string. An UUID is a 128–bit universally unique id, used by Microsoft and being proposed as an internet standard.

• procedure environTable(table : tree)
  

  Parameter	Type	Description
  table	tree	will contain the list of all environment variable names

  The procedure returns the array of all environment variable in the argument table. The name of the environment variable is assigned to the value of the item.

• procedure setFloatingLocation(key : string, location : int)
  

  Parameter	Type	Description
  key	string	name of a floating position to put into the output stream
  location	int	the position into the output stream to assign to the key, starting at \samp{0}

  Assigns a position to the floating location whose name is passed to argument key.

• procedure openLogFile(filename : string)
  

  Parameter	Type	Description
  filename	string	name of the file where log information will be put

  Creates (or erases if already exists) a log file, which remains valid upto the end of the execution. Each trace function (traceLine(), traceText(), traceStack()) will write in the log file.
  This function is very convenient for debugging a CGI script, where the standard output is devoted to the result page.

  Note that passing an empty filename stops the log mechanism.

• function completeDate(date : string, format : string) : string
  

  Parameter	Type	Description
  date	string	a date-time representation to complete
  format	string	the format that the \samp{date} argument conforms to

  Completes the date passed to the argument date, so as it conforms to the syntax of a date in CodeWorker meaning: "%d%b%Y %H:%M:%S.%L".

  Starting from today date with reset time (00:00:00.0), it replaces date–time characteristics with those of the parameter date and returns the result of the substitutions.

• ‘%w‘ means that the weekday must be written as an integer (0–6; 0 is sunday),
• ‘%W‘ means that the weekday must be written as the complete english name,

• function encodeURL(URL : string) : string
  

  Parameter	Type	Description
  URL	string	readable URL to encode

  Encode an URL for an HTTP request, meaning that the space character changes in ‘+‘ and all non–alphanumeric characters are encoded in hexadecimal, preceded by ‘%‘.

  Note that conversions are transparent while doing HTTP requests.

• function decodeURL(URL : string) : string
  

  Parameter	Type	Description
  URL	string	readable URL to encode

  Decode an URL from an HTTP request, meaning that the ‘+‘ character changes in a space and all hexadecimal descriptions of bytes (2 digits preceded by ‘%‘) are converted to characters.

  Note that conversions are transparent while doing HTTP requests.

• function getNow() : string
  Returns the current date–time, conforming to the format:
  %d%b%Y %H:%M:%S.%L

  For explanations about format types, see function formatDate at {formatDate()}.

• procedure setNow(constantDateTime : string)
  

  Parameter	Type	Description
  constantDateTime	string	the current date-time is fixed to this value

  Fixes the current date–time to the value passed to argument constantDateTime, conforming to the format:
  %d%b%Y %H:%M:%S.%L

  The procedure doesn‘t change the system time. now is just frozen for the scripting language when calling getNow(). One passes an empty date–time to unfreeze the time.

  For explanations about format types, see function formatDate at {formatDate()}.

The global statement was added to provide the feature:
global–statement ::= "global" variable [‘=‘ expression–to–assign]?

• function existEnv(variable : string) : bool
  

  Parameter	Type	Description
  variable	string	the environment variable name

  The function returns true if the environment table entry contains the variable.

• procedure setWorkingPath(path : string)
  

  Parameter	Type	Description
  path	string	the new working path

  Changes the output directory that was assigned to the option –path on the command line.

• function getIncludePath() : string
  It returns the include path passed to the command line with one or more times the setting of option –I, or the latest include path set via the procedure setIncludePath().

  The include path is a concatenation of paths separated by semi–commas ( extbf{‘;‘}).

• procedure setIncludePath(path : string)
  

  Parameter	Type	Description
  path	string	a concatenation of paths separated by \textbf{';'}

  It changes the include path passed to the command line with one or more times the setting of the option –I.

  The include path expects a concatenation of paths separated by semi–commas (‘;‘).

• procedure overwritePortion(location : int, text : string, size : int)
  

  Parameter	Type	Description
  location	int	points to a position in the output stream
  text	string	sequence of characters to write
  size	int	size of the portion to overwrite

  Writes a sequence of characters passed to argument text, at the position of the output stream given by argument location. The text overwrites up to size characters and inserts the rest if any. The position starts counting at 0.
  About the behaviour of the overwriting:

  • If there are more than size characters in text, all floating locations that point to location + size, or after, are impacted by the insertion of the remaining characters of text, and shift for an offset that is worth the size of the text minus the size of the portion to overwrite.
  • overwritePortion(pos, text, 0) is worth insertText(pos, text).
  • If the portion to overwrite is bigger than the length of text, all not overwritten characters of the portion are removed.
  • overwritePortion(pos, "", size) removes size characters from the output stream at position pos.

  If the position isn‘t valid, negative or bigger than the end of the output stream, an error is raised.

  In expansion mode, the position 0 points to the first character written for expansion and cannot exceed the last character written for expansion.

  Generally, the position is given by the function getFloatingLocation().

• function findNextString(text : string, find : string, position : int) : int
  

  Parameter	Type	Description
  text	string	a sequence of characters to explore
  find	string	a substring to find into \samp{text}
  position	int	the position in the string (starting at 0) the search must begin

  Returns the lowest beginning index of the substring find that matches the sequence of characters passed to argument text, starting the search at position. The index starts counting to 0.

  If the substring find doesn‘t belong to text (starting at position), the negative value –1 is returned.

• procedure removeVariable(node : tree)
  

  Parameter	Type	Description
  node	tree	the node to remove from the tree

  All attributes of the argument node are deleted, its array of nodes is cleared and its value becomes an empty string. If the node was referring to another node, the link is cleared. Once these task are completed, the variable node is removed from the tree it belongs to (as an attribute or an element).

  Note that trying to remove a local variable throws an error.

• function getHTTPRequest(URL : string, HTTPSession : tree, arguments : tree) : string
  

  Parameter	Type	Description
  URL	string	URL of the HTTP server
  HTTPSession	tree	an object to describe the HTTP session
  arguments	tree	list of the arguments to GET; the key contains the name of the argument and the element gives the value

  This function sends an HTTP‘s GET request to the HTTP server pointed to by the parameter URL with the list of arguments put into the the parameter arguments.

  The function returns the document read from the HTTP server.

  The function sendHTTPRequest() (see {sendHTTPRequest()}) describes the structure of the HTTP session object.

• function postHTTPRequest(URL : string, HTTPSession : tree, arguments : tree) : string
  

  Parameter	Type	Description
  URL	string	URL of the HTTP server
  HTTPSession	tree	an object to describe the HTTP session
  arguments	tree	list of the arguments to POST; the key contains the name of the argument and the element gives the value

  This function sends an HTTP‘s POST request to the HTTP server pointed to by the parameter URL with the list of arguments put into the the parameter arguments.

  The function returns the document read from the HTTP server.

  The function sendHTTPRequest() (see {sendHTTPRequest()}) describes the structure of the HTTP session object.

• function sendHTTPRequest(URL : string, HTTPSession : tree) : string
  

  Parameter	Type	Description
  URL	string	URL of the HTTP server
  HTTPSession	tree	an object to describe the HTTP session

  This function sends an HTTP request to the HTTP server pointed to by the argument URL, and returns the document read from the HTTP server.

  If the request fails, an error message is thrown.

  The well–named argument HTTPSession specifies some information into devoted attributes:

  • agent (optional) is the browser name, "CodeWorker" by default,
  • referer (optional),
  • proxy (optional):
    • proxy.host (compulsory),
    • proxy.port (compulsory),
  • cookies (optional) is a list of nodes such as:
    • name (compulsory),
    • value (optional) is worth by default,
    • path (optional),
    • domain (optional),
    • expires (optional) for a permanent cookie,

pushItem #evaluateVariable("variable.list");

pushItem variable.list;

function f(v : variable, a : value) {
    pushItem #evaluateVariable("v." + a);


It allows building the structure of the parse tree dynamically. It is the case when parsing an XML file with no information about its DTD.

• procedure removeFirstElement(list : tree)
  

  Parameter	Type	Description
  list	tree	an array of nodes

  Removes the first element from the array of nodes called list.

  Nothing occurs if list doesn‘t exist or is empty.

• procedure removeLastElement(list : tree)
  

  Parameter	Type	Description
  list	tree	an array of nodes

  Removes the last element from the array of nodes called list.

  Nothing occurs if list doesn‘t exist or is empty.

• function octalToDecimal(octalNumber : string) : int
  

  Parameter	Type	Description
  octalNumber	string	an octal integer to convert to a decimal number

  Converts an octal integer, passed to the argument octalNumber, to a signed decimal integer and returns the result. If octalNumber doesn‘t conform to the syntax of an octal number (octalNumber ::= #!ignore [‘0‘..‘8‘]+), the function raises an error.

• function hexaToDecimal(hexaNumber : string) : int
  

  Parameter	Type	Description
  hexaNumber	string	an hexadecimal integer to convert to a decimal number

  Converts an hexadecimal integer, passed to the argument hexaNumber, to a signed decimal integer and returns the result. If hexaNumber doesn‘t conform to the syntax of an hexadecimal number (hexaNumber ::= #!ignore [‘0‘..‘9‘ | #noCase ‘A‘..‘F‘]+), the function raises an error.

Examples: if the current position points to the fifth character...

• #readCompleteIdentifier scans "room" from the input stream "1234room",
• #readCompleteIdentifier fails to scan the input stream "mushroom", because "room" doesn‘t coincide with the beginning of an identifier, but is a part of "mushroom".

• #readInteger to scan an integer ; equivalent to #!ignore [‘0‘..‘9‘]+,
• #readNumeric to scan a floating–point number ; equivalent to #!ignore [#readInteger [‘.‘ [‘0‘..‘9‘]*]? | ‘.‘ [‘0‘..‘9‘]*] [[‘e‘ | ‘E‘] [‘+‘ | ‘–‘]? [‘0‘..‘9‘]+]?,

• function readByte() : string
  Returns the byte read at the current file position, or an empty string if the end of file has been reached. If succeeded, the position of the input file moves to the next character.

  The byte is returned as a 2–hexadecimal digit.

• procedure writeBytes(bytes : string)
  

  Parameter	Type	Description
  bytes	string	sequence of bytes to write at the current position of the output stream

  Writes a sequence of bytes passed to argument bytes, at the current position of the output stream.

  A byte is a couple of hexadecimal digits.

• 3 parameters expected to initialize the runtime environment of a BNF–parsing script since version 2.03,
• conversion to string expected for the name of files to generate (C++ translation of functions generate(), expand(), translate()),

• function byteToChar(byte : string) : string
  

  Parameter	Type	Description
  byte	string	an hexadecimal number of 2 digits exactly

  Converts a byte to a character. A byte is considered as an hexadecimal number of 2 digits exactly.

  If the argument byte doesn‘t contain an hexadecimal number of 2 digits, an error is raised. If byte is worth ‘00‘, the function returns an empty string.

• function charToByte(char : string) : string
  

  Parameter	Type	Description
  char	string	a character

  Converts a character to its hexadecimal representation, taking 2 digits, even if less than 0x10.

  If the argument char is empty, the function returns ‘00‘. If it contains more than one character, an error is raised.

• function loadBinaryFile(file : string) : string
  

  Parameter	Type	Description
  file	string	name of the binary file to load

  Returns the binary content of the file whose name is passed to argument file. The content concatenates a sequence of hexadecimal digits, so a byte is stored in 2 characters:
  binary–content ::= [byte]*;
  byte ::= [‘0‘..‘9‘ | ‘A‘..‘F‘ | ‘a‘..‘f‘]2;

  If the file doesn‘t exist or can‘t be read with success, an error occurs.

• procedure saveBinaryToFile(filename : string, content : string)
  

  Parameter	Type	Description
  filename	string	name of the binary file to write into
  content	string	sequence of bytes (2 hexadecimal digits) to write into the file

  Saves the binary content to the file filename. The parameter content concatenates a sequence of hexadecimal digits, so a byte is stored in 2 characters:
  binary–content ::= [byte]*;
  byte ::= [‘0‘..‘9‘ | ‘A‘..‘F‘ | ‘a‘..‘f‘]2;
  The hexadecimal pairs of digit are converted to binary (8 bits) before writing the content.

  If the file cannot be created, an error is raised. If the file already exists, its content is replaced by the new binary content.