Documentation



CONTENT



MAIN VERSIONS

Loading of packages
since version 3.0

Socket handling
since version 2.17

BNF of the language
since version 2.14

CGI program
since version 2.10

XSL pattern matching
since version 2.08

Sending HTTP requests
since version 2.07

Handling of binary files
since version 2.04



CONTACT US

 		The user's guide and the reference manual are both available into the same PDF file. For downloading it, click to the link CodeWorker.pdf (1060kb).

Please do not hesitate to contact us (questions, criticisms, suggestions, ...).

Grammar of the language

        CodeWorker_grammar.cwp

Quick access to functions and procedures

        Common
        Parsing
        Generation

Common

        Category interpreter
        Category string
        Category array
        Category node
        Category iterator
        Category file
        Category directory
        Category URL
        Category datetime
        Category numeric
        Category standard
        Category conversion
        Category system
        Category command
        Category generation
        Category parsing
        Category socket
        Category unknown

Category interpreter Function for running a CodeWorker script
autoexpand Expands a file on markups, following the directives self-contained in the file.
executeString Executes a script given in a string.
executeStringQuiet Interprets a string as a script and returns all traces intended to the console.
expand Expands a file on markups, following the directives of a template-based script.
generate Generates a file, following the directives of a template-based script.
generateString Generates a string, following the directives of a template-based script.
parseAsBNF Parses a file with a BNF script.
parseFree Parses a file with an imperative script.
parseFreeQuiet Parses a file with an imperative script, reroute all console messages and returns them as a string.
parseStringAsBNF Parses a string with a BNF script.
traceEngine Displays the state of the interpreter.
translate Performs a source-to-source translation or a program transformation.
translateString Performs a source-to-source translation or a program transformation on strings.

Category string Functions for handling strings
charAt Returns the characters present at a given position of a string.
completeLeftSpaces Completes a string with spaces to the left so that it reaches a given size.
completeRightSpaces Completes a string with spaces to the right so that it reaches a given size.
composeAdaLikeString Converts a sequence of characters to a Ada-like string without double quote delimiters.
composeCLikeString Converts a sequence of characters to a C-like string without double quote delimiters.
composeHTMLLikeString Converts a sequence of characters to an HTML-like text
composeSQLLikeString Converts a sequence of characters to a SQL-like string without single quote delimiters.
coreString Extracts the core of a string, leaving the beginning and the end.
countStringOccurences How many occurences of a string to another.
cutString Cuts a string at each separator encountered.
endString Compares the end of the string.
endl Returns an end-of-line, depending on the operating system.
equalsIgnoreCase Compares two strings, ignoring the case.
executeString Executes a script given in a string.
executeStringQuiet Interprets a string as a script and returns all traces intended to the console.
findFirstChar Returns the position of the first character amongst a set, encountered into a string.
findLastString Returns the position of the last occurence of a string to another.
findNextString Returns the next occurence of a string to another.
findString Returns the first occurence of a string to another.
generateString Generates a string, following the directives of a template-based script.
joinStrings Joins a list of strings, adding a separator between them.
leftString Returns the beginning of a string.
lengthString Returns the length of a string.
midString Returns a substring starting at a point for a given length.
parseStringAsBNF Parses a string with a BNF script.
repeatString Returns the concatenation of a string repeated a few times.
replaceString Replaces a substring with another.
replaceTabulations Replaces tabulations with spaces.
rightString Returns the end of a string.
rsubString Returns the left part of a string, ignoring last characters.
startString Checks the beginning of a string.
subString Returns a substring, ignoring the first characters.
toLowerString Converts a string to lowercase.
toUpperString Converts a string to uppercase.
trim Eliminates heading and trailing whitespaces.
trimLeft Eliminates the leading whitespaces.
trimRight Eliminates the trailing whitespaces.
truncateAfterString Special truncation of a string.
truncateBeforeString Special truncation of a string.

Category array Functions handling arrays
findElement Checks the existence of an entry key in an array.
findFirstSubstringIntoKeys Returns the first entry key of an array, containing a given string.
findNextSubstringIntoKeys Returns the next entry key of an array, containing a given string.
getArraySize Returns the number of items in an array.
insertElementAt Inserts a new element to a list, at a given position.
invertArray Inverts the order of items in an array.
isEmpty Checks whether a node has items or not.
removeAllElements Removes all items of the array.
removeElement Removes an item, given its entry key.
removeFirstElement Removes the first item of the array.
removeLastElement Removes the last item of the array.

Category node Functions handling a node
clearVariable Removes the subtree and assigns an empty value.
equalTrees Compares two subtrees.
existVariable Checks the existence of a node.
getVariableAttributes Extract all attribute names of a tree node.
removeRecursive Removes a given attribute from the subtree.
removeVariable Removes a given variable.
slideNodeContent Moves the subtree elsewhere on a branch.
sortArray Sort an array, considering the entry keys.

Category iterator Functions handling an iterator
createIterator Creates an iterator pointing to the beginning of a list.
createReverseIterator Creates a reverse iterator pointing to the end of a list.
duplicateIterator Duplicates an iterator.
first Returns true if the iterator points to the first item.
index Returns the position of an item in a list.
key Returns the entry key of the item pointed to by the iterator.
last Returns true if the iterator points to the last item.
next Move an iterator to the next item of a list.
prec Move an iterator to the precedent item of a list.

Category file Functions handling files
appendFile Writes the content of a string to the end of a file
canonizePath Builds an absolute path, starting to the current directory.
changeFileTime Changes the access and modification times of a file.
chmod Changes the permissions of a file.
copyFile Copies a file.
copyGenerableFile Copies a file with protected areas or expandable markups, only if the hand-typed code differs between source and destination.
copySmartFile Copies a file only if the destination differs.
createVirtualFile Creates a transient file in memory.
createVirtualTemporaryFile Creates a transient file in memory, CodeWorker choosing its name.
deleteFile Deletes a file on the disk.
deleteVirtualFile Deletes a transient file from memory.
existFile Checks the existence of a file.
existVirtualFile Checks the existence of a transient file, created in memory.
exploreDirectory Browses all files of a directory, recursively or not.
fileCreation Returns the creation date of a file.
fileLastAccess Returns the last access date of a file.
fileLastModification Returns the last modification date of a file.
fileLines Returns the number of lines in a file.
fileMode Returns the permissions of a file.
fileSize Returns the size of a file.
getGenerationHeader Returns the comment to put into the header of generated files.
getShortFilename Returns the short name of a file
indentFile Indents a file, depending on the target language.
loadBinaryFile Loads a binary file and stores each byte in a hexadecimal representation of 2 digits.
loadFile Returns the content of a file or raises an error if not found.
loadVirtualFile Returns the content of a transient file or raises an error if not found.
pathFromPackage Converts a package path to a directory path.
relativePath Returns the relative path, which allows going from a path to another.
resolveFilePath Gives the location of a file with no ambiguity.
saveBinaryToFile Saves binary data to a file.
saveToFile Saves the content of a string to a file
scanDirectories Explores a directory, filtering filenames.
scanFiles Returns a flat list of all filenames matching with a filter.

Category directory Functions handling directories
changeDirectory Changes the current directory (chdir() in C).
copySmartDirectory Copies files of a directory recursively only when destination files differ from source files.
createDirectory Creates a new directory.
exploreDirectory Browses all files of a directory, recursively or not.
getCurrentDirectory Returns the current directory (getcwd() in C).
removeDirectory Removes a directory from the disk.
scanDirectories Explores a directory, filtering filenames.
scanFiles Returns a flat list of all filenames matching with a filter.

Category URL Functions working on URL transfers (HTTP,...)
decodeURL Decodes an HTTP URL.
encodeURL Encodes an URL to HTTP.
getHTTPRequest Sends an HTTP's GET request.
postHTTPRequest Sends an HTTP's POST request.
sendHTTPRequest Sends an HTTP request.

Category datetime Functions handling date-time
addToDate Change a date by shifting its internal fields days/months/years or time.
compareDate Compares two dates.
completeDate Extends an incomplete date with today characteristics.
fileCreation Returns the creation date of a file.
fileLastAccess Returns the last access date of a file.
fileLastModification Returns the last modification date of a file.
formatDate Changes the format of a date.
getLastDelay Returns the time consumed to execute a statement.
getNow Returns the current date-time.
setNow Fixes the current date-time.

Category numeric Functions handling numbers
add Equivalent admitted writing is $a + b$.
ceil Returns the smallest integer greater that or equal to a number
decrement Equivalent admitted writing is set a = $a - 1$;.
div Equivalent admitted writing is $a / b$.
equal Equivalent admitted writing is $a == b$.
exp Returns the exponential of a value.
floor Returns the largest integer less that or equal to a number
increment Equivalent admitted writing is set a = $a + 1$;.
inf Equivalent admitted writing is $a < b$.
isNegative Equivalent admitted writing is $a < 0$.
isPositive Equivalent admitted writing is $a > 0$.
log Returns the Neperian logarithm.
mod Equivalent admitted writing is $a % b$.
mult Equivalent admitted writing is $a * b$.
pow Raises a number to the power of another.
sqrt Calculates the square root.
sub Equivalent admitted writing is $a - b$.
sup Equivalent admitted writing is $a > b$.

Category standard Classical functions of any standard library
UUID Generates an UUID.
error Raises an error message
inputKey If any, returns the last key pressed on the standard input.
inputLine Wait for the standard input to the console.
isIdentifier Checks whether a string is a C-like identifier or not.
isNumeric Checks whether a string is a floating-point number or not.
randomInteger Generates a pseudorandom number.
randomSeed Changes the seed of the pseudorandom generator.
traceLine Displays a message to the console, adding a carriage return.
traceObject Displays the content of a node to the console.
traceStack Displays the stack to the console.
traceText Displays a message to the console.

Category conversion Type conversion
byteToChar Converts a byte (hexadecimal representation of 2 digits) to a character.
bytesToLong Converts a 4-bytes sequence to an unsigned long integer in its decimal representation.
bytesToShort Converts a 2-bytes sequence to an unsigned short integer in its decimal representation.
charToByte Converts a character to a byte (hexadecimal representation of 2 digits).
charToInt Converts a character to the integer value of the corresponding ASCII.
hexaToDecimal Converts an hexadecimal representation to an integer.
hostToNetworkLong Converts a 4-bytes representation of a long integer to the network bytes order.
hostToNetworkShort Converts a 2-bytes representation of a short integer to the network bytes order.
longToBytes Converts an unsigned long integer in decimal base to its 4-bytes representation.
networkLongToHost Converts a 4-bytes representation of a long integer to the host bytes order.
networkShortToHost Converts a 2-bytes representation of a short integer to the host bytes order.
octalToDecimal Converts an octal representation to a decimal integer.
shortToBytes Converts an unsigned short integer in decimal base to its 2-bytes representation.

Category system Functions relative to the operating system
computeMD5 Computes the MD5 of a string.
environTable Equivalent of environ() in C
existEnv Checks the existence of an environment variable.
getEnv Returns an environment variable, or raises an error if not exist.
openLogFile Opens a log file for logging every console trace.
putEnv Puts a value to an environment variable.
sleep Suspends the execution for millis milliseconds.
system Equivalent to the C function system().

Category command Relative to the command line
compileToCpp Translates a script to C++.
getIncludePath Returns the include path passed via the option -I.
getProperty Returns the value of a property passed via the option -D.
getVersion Returns the version of the interpreter.
getWorkingPath Returns the output directory passed via option -path.
setIncludePath Changes the option -I while running.
setProperty Adds/changes a property (option -D) while running.
setVersion Gives the version of scripts currently interpreted by CodeWorker.
setWorkingPath Does the job of the option -path.

Category generation Functions relative to generation
addGenerationTagsHandler Adds your own CodeWorker's tags handler
autoexpand Expands a file on markups, following the directives self-contained in the file.
expand Expands a file on markups, following the directives of a template-based script.
extractGenerationHeader Gives the generation header of a generated file, if any.
generate Generates a file, following the directives of a template-based script.
generateString Generates a string, following the directives of a template-based script.
getCommentBegin Returns the current format of a comment's beginning.
getCommentEnd Returns the current format of a comment's end.
getGenerationHeader Returns the comment to put into the header of generated files.
getTextMode Returns the text mode amongst "DOS", "UNIX" and "BINARY".
getWriteMode Returns how text is written during a generation (insert/overwrite).
listAllGeneratedFiles Gives the list of all generated files.
removeGenerationTagsHandler Removes a custom generation tags handler
selectGenerationTagsHandler Selects your own CodeWorker's tags handler for processing generation tasks
setCommentBegin Changes what a beginning of comment looks like, perhaps before expanding a file.
setCommentEnd Changes what an end of comment looks like, perhaps before expanding a file.
setGenerationHeader Specifies a comment to put at the beginning of every generated file.
setTextMode "DOS", "UNIX" or "BINARY"
setWriteMode Selects how to write text during a generation (insert/overwrite).
translate Performs a source-to-source translation or a program transformation.
translateString Performs a source-to-source translation or a program transformation on strings.

Category parsing Functions relative to scanning/parsing
parseAsBNF Parses a file with a BNF script.
parseFree Parses a file with an imperative script.
parseFreeQuiet Parses a file with an imperative script, reroute all console messages and returns them as a string.
parseStringAsBNF Parses a string with a BNF script.
translate Performs a source-to-source translation or a program transformation.
translateString Performs a source-to-source translation or a program transformation on strings.

Category socket Socket operations
acceptSocket Listens for a client connection and accepts it.
closeSocket Closes a socket descriptor.
createINETClientSocket Creates a stream socket connected to the specified port and IP address.
createINETServerSocket Creates a server stream socket bound to a specified port.
receiveBinaryFromSocket Reads binary data from the socket, knowing the size.
receiveFromSocket Reads text or binary data from a socket.
receiveTextFromSocket Reads text from a socket, knowing the size.
sendBinaryToSocket Writes binary data to a socket.
sendTextToSocket Writes text to a socket.

Category unknown Various types of function
not The boolean negation, equivalent to !a.
produceHTML
saveProject Saves the parse tree of the project to XML.
saveProjectTypes Factorizes nodes of the projects to distinguish implicit types for node and saves it to XML.

Parsing

        Category parsing
        Category socket

Category parsing Functions relative to scanning/parsing
countInputCols Column number in the line where the parse cursor points to.
countInputLines Line number where the parse cursor points to.
getInputFilename Returns the path of the input file being parsed.
getInputLocation Returns the current position in the input stream.
getLastReadChars Returns the last scanned characters.
goBack Moves back one byte before.
lookAhead Scans the next characters without moving the input file position.
parseAsBNF Parses a file with a BNF script.
parseFree Parses a file with an imperative script.
parseFreeQuiet Parses a file with an imperative script, reroute all console messages and returns them as a string.
parseStringAsBNF Parses a string with a BNF script.
peekChar Scans the current position without moving the file pointer.
readAdaString Reads a Ada-like string between double quotes.
readByte Reads the current character as a byte (hexadecimal representation of 2 digits).
readBytes Reads a sequence of bytes, given the length.
readCChar Reads a C-like constant character.
readChar Reads the current character.
readCharAsInt Reads the current character as an integer.
readChars Reads a sequence of characters, given the length.
readIdentifier Reads an identifier.
readIfEqualTo Reads a given string or returns false if it doesn't match.
readIfEqualToIdentifier Reads a given identifier or returns false if it doesn't match.
readIfEqualToIgnoreCase Reads a given string ignoring the case, or returns false if it doesn't match.
readLine Reads a line.
readNextText Searches the next occurence of a string.
readNumber Reads a number.
readPythonString Reads a Python-like string (triple-quoted strings recognized).
readString Reads a string between double quotes.
readUptoJustOneChar Searches the first occurence of a character amongst a set of characters and points on it.
readWord Reads a word.
setInputLocation Changes the position in the input stream.
skipBlanks Skips all whitespaces and carriage returns.
skipEmptyCpp Skips blanks and C++-like comments.
skipEmptyCppExceptDoxygen Skips blanks and C++ comments, except comments like Doxygen.
skipEmptyHTML Skips blanks and HTML-like comments.
skipEmptyLaTeX Skips blanks and LaTeX-like comments.
translate Performs a source-to-source translation or a program transformation.
translateString Performs a source-to-source translation or a program transformation on strings.

Category socket Socket operations
acceptSocket Listens for a client connection and accepts it.
attachInputToSocket Attaches the input stream of a parsing script to a socket.
closeSocket Closes a socket descriptor.
createINETClientSocket Creates a stream socket connected to the specified port and IP address.
createINETServerSocket Creates a server stream socket bound to a specified port.
detachInputFromSocket The current parsing script doesn't use the socket as input stream anymore.
receiveBinaryFromSocket Reads binary data from the socket, knowing the size.
receiveFromSocket Reads text or binary data from a socket.
receiveTextFromSocket Reads text from a socket, knowing the size.
sendBinaryToSocket Writes binary data to a socket.
sendTextToSocket Writes text to a socket.

Generation

        Category generation
        Category socket

Category generation Functions relative to generation
addGenerationTagsHandler Adds your own CodeWorker's tags handler
allFloatingLocations Gives all floating locations registered to the output stream.
autoexpand Expands a file on markups, following the directives self-contained in the file.
countOutputCols Column number in the line where the cursor points to.
countOutputLines Line number where the cursor points to.
decrementIndentLevel Decrements the indentation level, used to indenting output files automatically while writing.
existFloatingLocation Checks whether a floating location exists or not.
expand Expands a file on markups, following the directives of a template-based script.
extractGenerationHeader Gives the generation header of a generated file, if any.
generate Generates a file, following the directives of a template-based script.
generateString Generates a string, following the directives of a template-based script.
getCommentBegin Returns the current format of a comment's beginning.
getCommentEnd Returns the current format of a comment's end.
getFloatingLocation Returns the position attached to a key of floating location.
getGenerationHeader Returns the comment to put into the header of generated files.
getLastWrittenChars Recalls the last written characters.
getMarkupKey Returns the key of the current markup.
getMarkupValue Returns the value attached to the current markup.
getOutputFilename Returns the path of the output file being generated.
getOutputLocation Returns the current output file position.
getProtectedArea Returns the content of a given protected area, if not put into the file yet.
getProtectedAreaKeys Returns the list of all protected area keys found into the file before generation.
getTextMode Returns the text mode amongst "DOS", "UNIX" and "BINARY".
getWriteMode Returns how text is written during a generation (insert/overwrite).
incrementIndentLevel Increments the indentation level, used to indenting output files automatically while writing.
indentText Indents the output stream.
insertText Inserts text at a given position.
insertTextOnce Inserts text at a given position, if never inserted before.
insertTextOnceToFloatingLocation Inserts text at a given floating location, if never inserted before.
insertTextToFloatingLocation Inserts text at a given floating location.
listAllGeneratedFiles Gives the list of all generated files.
newFloatingLocation Assigns the current file pointer to a floating location.
overwritePortion Overwrites text at a given position.
populateProtectedArea Puts a protected area at the current position, giving its content.
remainingProtectedAreas Returns the list of all protected area keys remaining to put into the file.
removeFloatingLocation Removes the floating location attached to a given key.
removeGenerationTagsHandler Removes a custom generation tags handler
removeProtectedArea Removes a protected area remaining to put into the file.
resizeOutputStream Reduces the size of the output, loosing the text out of bound.
selectGenerationTagsHandler Selects your own CodeWorker's tags handler for processing generation tasks
setCommentBegin Changes what a beginning of comment looks like, perhaps before expanding a file.
setCommentEnd Changes what an end of comment looks like, perhaps before expanding a file.
setFloatingLocation Defines a file position that will move when text will be inserted before or just on it.
setGenerationHeader Specifies a comment to put at the beginning of every generated file.
setOutputLocation Changes the location of the output file pointer.
setProtectedArea Puts a protected area at the current location.
setTextMode "DOS", "UNIX" or "BINARY"
setWriteMode Selects how to write text during a generation (insert/overwrite).
translate Performs a source-to-source translation or a program transformation.
translateString Performs a source-to-source translation or a program transformation on strings.
writeBytes Writes a series of bytes at the current position.
writeText Imperative form of the template writing @...@.
writeTextOnce Writes the text only if it wasn't encountered before in this function or when inserting.

Category socket Socket operations
acceptSocket Listens for a client connection and accepts it.
attachOutputToSocket Attaches the output stream of a template-based script to a socket.
closeSocket Closes a socket descriptor.
createINETClientSocket Creates a stream socket connected to the specified port and IP address.
createINETServerSocket Creates a server stream socket bound to a specified port.
detachOutputFromSocket Once completed, the current output stream won't be sent to a socket.
flushOutputToSocket Flushes the output stream of a template-based script to a socket.
receiveBinaryFromSocket Reads binary data from the socket, knowing the size.
receiveFromSocket Reads text or binary data from a socket.
receiveTextFromSocket Reads text from a socket, knowing the size.
sendBinaryToSocket Writes binary data to a socket.
sendTextToSocket Writes text to a socket.

About the manual

Efforts are focused on improving the reliability of the documentation on examples and on the reference manual (except on english text, I'm afraid!).

A formal representation describes all functions and procedures that CodeWorker provides, with their prototype and a short explanation and an example and the list of all similar functions and procedures.
This formal representation is used to generate source codes of CodeWorker that handle parsing and C++ mapping and execution of each function and procedure of the scripting language. This formal representation that conforms to what CodeWorker expects in terms of function/procedure prototypes, is reused to generate the LaTeX part of the reference manual that presents each of them.
Examples are executed while generating the documentation to be sure they are correct, and to report an up to date output.

The chapter getting started is partially generated too, and the guarantee is given that every script runs successfully and that every example file has the last annotations. To warrant that, scripts are executed while generating the documentation, and example/script files contain some formatted comments just before lines to annotate. While including them into the chapter, their content is numeroted line by line, and notes are extracted. Notes are written just after the content, and refer to the line they explain.

The documentation is written in LaTeX. The great advantage of LaTeX is that it offers a powerful text processing and that it is easy to manipulate for source code generation (text format instead of binary, and it accepts comments). Markups are inserted into the documentation at the points where generated text must be included. A markup is a special comment that CodeWorker recognizes. This mode of source code generation is an illustration of what is called expansion mode here.

 CodeWorker is maintained by Cedric Lemaire. Please send a mail to Submit a bug or feature