# Documentation

### CONTENT Overview Why use this tool? Getting Started (49kb) Documentation All CodeWorker (1302kb) Scripting language (918kb) Tutorials Repository of scripts Download Related links ### 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 (862kb). 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 index 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 index | Functions handling a foreach index
`first` | Returns `true` if the index points to the first item.
`key` | Returns the entry key of the item pointed to by the index.
`last` | Returns `true` if the index points to the last item.
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.
`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). Markers are inserted into the documentation at the points where generated text must be included. A marker 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