User Function Text Package

There are two primary purposes for these text function additions to the UF Programmer. One is to allow text and characters to be read from a file for display in the graphics window. And the other is to provide tools for manipulating text documents to convert them to music source material.

String (text) parameters can be defined by enclosing the parameter in quotation marks ("This is a string.") or by using a string variable.

String variables must be predefined before use. Define them with the SetVar button in the lower right of the calculator, just as you would with numeric variable, but with the string value in quotation marks. You cannot assign numbers to string variables, or strings to numeric variables - however they were originally declared, is how they must be used.

CRLF and TAB are string constants that insert a newline and tab, respectively, into a text variable string.

LetStr(VarName, "Any Text", ["More Text"], ... , ["More Text"]) - assigns a text string to an existing string variable. Optionally assigns multiple strings (up to 10), concatenated from left to right. The target string variable may be used in any of the assignment parameters. For example:

If TxtVar is a predefined text variable containing the string, " is red" then:

LetStr(TxtVar, "My dog ", TxtVar, " and blue.") will assign to TxtVar the string "MY DOG is red AND BLUE."

TxtStoreX(Page, Index, "Any Text") - store given text into text array at Page (0-127), Index (0-127). This is similar to StoreX for numeric values, but it stores text strings.

TxtFetchX(VarName, Page, Index) - assign text in text array at Page (0-127), Index (0-127) to named global string variable VarName. similar to FetchX for numeric values, but it returns stored text strings.

Private String Variables: Tx0-Tx9 - UF Modules have 10 private string variables available to them, that can not be accessed by any other module. These are predefined string variables named Tx0 to Tx9. They are similar in concept to the private number variables V0 to V9.

Assign string values to the variables with: Tx0.("Any String"). The string that is to be assigned can be either a literal string or a named global string variable.

Retrieve a previously stored private string variable with: TX0(VarName). Note there is no period between "TX0" and the left parenthese. The given global string variable "VarName" can be used over and over for different private variables, as long as you use the results right away.

LetChr(VarName, N) - assigns a single character defined by ASCII value N to an existing string variable.

ChrNum("Any Text") - converts first character to its numeric equivalent, the reverse of LetChr, above. Note that both LetChr and ChrNum converts to & from binary character representations. For ASCII/ANSI values 0-127 these are printable values, but from 128 to 255 they are not printable. They can still be used, however, for tasks such as sending & receiving COM Serial byte data as characters.

LetNum(VarName, N, [Key]) - converts the number in N to a text string, and assigns it to an existing string variable.

Key is an optional conversion key:
0 is the default, which converts to normal decimal numbers;
1 converts to hexadecimal format;
2 converts to a binary string of 1's and 0's; and
3 converts to Roman numerals (1 - 4999).

LetJustify(VarName, "Any Text", [Key], [Field]) - justifies a text string left, right or center within the given field size, and assigns the resulting string to an existing string variable. Returns 0 for success, 1 if error.

Key is the optional justification key:
0 (default) for left,
1 for right, and
2 for center.

Field is an optional parameter that specifies the number of characters to be returned to the text string. The default is 24 characters. Text justification is within this field; if the text exceeds the field size it is truncated.

TxtNum("Any Text") - Converts a numeric string to a value, the opposite of LetNum(), above. Scans given text for the first occurance of a numeric sub string, and if found returns its numeric value. Only the first numeric string found is converted. Decimal points are considered numeric characters so a decimal point followed by non numeric characters followed by numeric characters will return 0. Returns 0 if no numeric characters are found.

Examples:
123 returns 123
"abc123xx" returns 123
"answer: 123.5" returns 123.5
"answer. 123.5" returns 0 (contains "." followed by space).

SubStr(VarName, "Any Text", Start, Chars) - Assigns a substring from the given string to an existing global string variable. Start is the 1-based starting position in the string (optional, defaults to 1), Chars is the number of characters to return (optional, defaults to all remaining). The function returns the number of characters found, or 0 if error.

LetTxtLine(VarName, TextSet, LineNumber) - Assigns a single line of a text document to an existing variable. See below for text file functions. Line numbers are always numbered from 1, not 0

TxtOpen(TextSet, "FileName", [Squeeze]) - Reads a text file into one of the 10 available text set arrays, optionally squeezing white space into single spaces. Returns number of lines read if successful, 0 if error. You can view the text stored in a text set any time by clicking on the Show Text button.

TextSet is in the range of 0-9. This becomes the identifying "handle" of the text document. Each text set represents a text file that is broken down into lines, with each line available as an array element of the text set. Lines are defined by the text's new line characters, which are not included in the stored string, but which must be present in the text document for the line to be read. The last line of a document will be ignored if it does not end with a new line.

"File Name" is a string in quotes, or a string variable (without quotes). It is the path name for the text document to be read, and should look something like: "c:\documents\textfile.txt" - no checking is done to restrict file types, any file may be read. However the files are separated into lines so files without new line characters may give unexpected results.

Squeeze is an optional parameter. If 1 (or any non zero), each occurrence of white space (spaces, tabs, nulls) is reduced to a single space. Do not include the square brackets - they are used here only to indicate the parameter is optional.

TxtDelEmpty(N) - removes empty lines from text set N, which must be in the range of 0-9. Returns new number of lines if successful, 0 if error.

TxtWordList(DestinationTextSet, SourceTextSet, [LineNumber], [Case], ["Remove"] - Converts an existing text set to a word list in a new text set. Optionally select just a single line of the source text set to convert. Removes punctuation marks, which may optionally be specified or set to not be removed at all. Returns 0 if successful, 1 if error.

DestinationTextSet may be any text set, 0-9, whether or not it currently contains text. It may be the same text set as the source text set, which will cause it to be replaced by its word list. Previous destination text set contents, if any, are lost.

SourceTextSet must be an existing text set, 0-9.

LineNumber is optional. If given, it will translate only the specified line from the source text set. Line numbers are always numbered from 1, not 0. Giving a line number of 0 is the same as not giving one at all, and it causes the entire text set to be converted. Giving a line number greater than the number of lines in the source text set causes an error and no conversion is done.

Case - is optional. If given, all words will be converted to the same case. This is needed if you want the hash number to be the same for the same words, regardless of whether they are capitalized.
0 (default) has no effect,
1 converts to upper case, and
2 converts to lower case.

Remove is optional. It is a string of characters (must be in quotes, or a string variable) that will be removed from the word list text. The default remove characters are: ,.?!:;'#()[]". Use this parameter to change the default remove list string to anything you want. Any characters given will be removed from the word list. Specify a null string of two quote marks together ("") to not remove any characters. Since quotation marks are string delimiters, to specify a double quote, use a single quote to delimit the string, or to specify a single quote (apostrophe), use the normal double quotes to delimit the string.

TxtHash(TextSet, [Fold], [Ordering]) - creates a table of numbers that are unique for each line in the text set, with options to fold-limit the maximum value, and to change the ordering. Returns 0 for success, 1 on error.

The purpose of this function is to convert text patterns into numeric patterns that can be used by other modules in SoftStep. For example, you might want to treat a poem with algorithmic patterns that have some discernible relationship to the word patterns in the poem. Just treating the characters in the words as pitch values yields little sense of the words used, or their patterns. But by assigning each word a unique number, the number can then be mapped to pitches that represent whole words - when the same word is repeated, the same pitch sounds. The HSort button in the Fill utility is especially useful for this mapping.

In addition to simply mapping numbers to words, it would be helpful if the word patterns were assigned numbers that represent usage, with words most used given lower numbers so they can be mapped to a pitch translation table with (for example) more harmonic notes at the head of the table representing the words that get used most often.

A typical way of creating text hash mappings is to read a document into a text set with TxtOpen() then convert all the lines of the document into individual words with TxtWordList(), then create the hash table with TxhHash() and finally send the hash values to a Table or File sequencer with TxtHashFileSeq() or TxtHashTable(); or you can read the hash value directly with the TxtGetHash() function.

TxtSet must be an existing text set, 0-9.

Fold is an optional parameter that limits the maximum hash value by folding (modulus) around the given value. Any positive number greater than 0 causes the hash to be limited to that value. The default value of 0 disables folding, and the hash values will range from 0 to the maximum number of unique lines (words).

Ordering is an optional parameter that specifies how the hash numbers are ordered in relation to the words. Values should be -1 or 0 or 1. The default is 0, which orders hash values in word usage order, with the most often used words given the lowest numbers. Words that have the same usage count are in first-use order. Use 1 to reverse the order for the words that have the same usage count. For direct first-usage order of all words, regardless of usage count, use -1.

TxtGetHash(TextSet, LineNumber) - Returns the hash value at given text set (0-9) and line number. Text line numbers start with 1, not 0.

TxtHashFileSeq(mID, TextSet) - copies the hash values of the given text set (0-9) into a File sequencer module, identified by the given mID (module ID), which is the same as the module's number minus 1. See Sequencer Cell Access for additional information. This function automatically folds hash values at 255, and it copies only up to the maximum address range the File sequencer has been previously set to. Returns 0 for success, 1 on error.

TxtHashTable(TableNumber, TextSet) - copies the hash values of the given text set (0-9) into a Table sequencer slot (0-127), that is accessible by Table, TWrite and Probability modules. This function automatically folds hash values at 127, and it copies only up to 128 hash values. Returns 0 for success, 1 on error.

TxtInfoBox(mID, TextSet, [LineNumber]) - displays text of the given text set (0-9) and optional line number in an existing Info Box module, identified by the given mID (module ID), which is the same as the module's number minus 1 (i.e. module Info-2 would have an mID value of 1). Returns 0 for success, 1 on error.

LineNumber is optional. If given, only the specified line from the source text set is displayed. Line numbers are always numbered from 1, not 0. Giving a line number of 0 is the same as not giving one at all, and it causes the entire text set to be displayed. Giving a line number greater than the number of lines in the source text set causes an error.

InfoBox(mID, "Any Text") - displays text in an existing Info Box module, identified by the given mID (module ID), which is the same as the module's number minus 1 (i.e. module Info-1 would have an mID value of 0). Returns 0 for success, 1 on error.

GetInfoBox(VarName, mID) - copies text from an InfoBox, as above, to named text variable VarName.

SetFileNameList("directory", "ext", List) - create list of filenames from directory of type ext, in List 0-9; returns # files, 0 if error. All parameters are optional. Directory defaluts to "c:\"; ext defaults to "*" (all files), and List defaults to 0. Use this function to create a list of files in a directory that you can then access with GetFileName() by index. Useful with graphics processes to load picture files by index number.

GetFileName(VarName, Index, List) - Get file name name from Index in previously set List (0-9) to named variable VarName; returns # files in list, 0 if error. The file name only is returned, minus path and ext.

SoftStep is Copyright © 1999-2004 by John Dunn and Algorithmic Arts. All Rights Reserved.