Text Menu

ArtWonk modules can handle text as well as numbers. While most modules process numeric values, many - such as the switches - can process either numeric values or text strings. The String modules process text strings.


FileName ParseFName FilePath FindFile CombineFN GetFNames MakePath

TxOpen TxSave TxNote TxClone TxParse TxWord TxCSV TxStack TxQueue

TxLine TxInsert TxDelete TxReplace TxSort TxFind

StrFind StrMerge StrInsert StrDelete StrTrim StrSubstr StrCase

StrInfo StrChange StrRand StrNumber StrGenKey StrTime SysTime


FileName

Supply a valid complete Windows file name for use in any module that requires one. Can be used interactively in real time by triggering the Strobe input, which causes a standard Windows File Open or Save dialog; or it can be preset with a file name set by a file dialog called from the Properties box, available by clicking on the top right blue-letter button on the module.

Output:

Out: Complete Windows path and file name.

Input:

Strb: Strobe to trigger a Windows file name dialog. Set whether it will be an open or save dialot, and what the file filters should be with the Properties button. Optionally, this input can be hidden by un-clicking the Properties box option, "Allow Dialog to be opened with input strobe."


ParseFName

Parses a full Windows path and file name into its parts: Disk drive, path, name, and extension.

Outputs:

Drive: Disk or Netwonk Drive or UNC part of file name.

Path: Path part of file name.

Name: Name part of file name.

Ext: Extension part of file name.

Inputs:

Text: Full file name to be parse.

Strb: Strobe to parse the file name.


FilePath

Returns a file path and name.  Use for special path names, such as ArtWonk\Patches or My Documents, or you can enter an arbitary text name.

Output:

TxOut: Completed full file path name.

Inputs:

Path: Text of arbitary path name, or enter a number for special path name: 0=ArtWonk, 1=current, 2=Patch, 3=Macro, 4=Function, 5=Array, 6=Graphics, 7=Data, 8=Names.

Name: Text of arbitary file name or enter 0 for the current patch name.

Ext: Text of file extension.


FindFile

Find a file, or report if not found. Can be used in two ways: 1. to find and return a complete file path within the current folder or any of the the ArtWonk special folders given just the file name, or 2. to test if a complete path+file name anywhere on the computer is found.

Outputs:

Path: Full path name of file, if found.

Found: Folder found in: 0=Not Found, 1=current, 2=Patch, 3=Macro, 4=Function, 5=Array, 6=Graphics, 7=Data, 8=Names, -1=Full path file found.

Inputs:

Name: File name to find; if full path given, only tests if file exists and returns -1 if found. Folder names within the special folders can be used. For example "EmuSoundFonts\P1Inst.txt" will find the file, "P1Inst.txt," and report it as in the Names folder (Found=8).

Ext: Text of file extension. Do not include the dot. Leave empty (0) if the ext is part of the file name.

Strb: Strobe to find file, or to test if file exists.


CombineFN

Create a full file name from its components.

Output:

FN: Full file name.

Inputs:

Chng: Any change to create full file name.

Drive: Disk drive part of Path name (optional, if not supplied with Path).

Path: Path part of file name.

Name: Name part of file name.

Ext: Extension part of file name.


GetFNames

Returns an array of matching file names within a directory.

Outputs:

Name: File name at current index, or error message if none found.

Found: Number of matching file names found.

Max: Max array index (names found -1).

Inputs:

Strb: Strobe to load file names from given directory into the text array.

Drive: Disk drive part of Path name (optional, if not supplied with Path).

Path: Directory path name to read file names from.

Name: Matching file name: use '*' for any (as 'name*') and '?' for characters to match.

Ext: Matching file extension: use '*' for any and '?' for characters to match.

Index: Index address into the file name array, to access a file name.


MakePath

Create a directory path, including sub directories as needed.

Output:

Path: Path created, or error message.

Inputs:

Strb: Strobe to create path.

Path: Path to create; also creates intermediate directories if they do not exist.


TxOpen

Opens a text file and reads it into an array of text lines. This module becomes the source for many of the other String modules. A text file is read into the module's internal text array (which is saved with the module, so you don't need to open the file after the first time), one line per array element. Other string manipulation modules can access this text array by means of the Hand output.

Outputs:

TxOut: Selected Text Line (0 based).

Max: Last line read, maximum text array address.

Hand: Handle for other text modules to use, to access the text array.

Inputs:

Line: Line address to output (update on change or reset).

Path: Path and name of text file to be opened.

Strb: Strobe to read the file.


TxSave

Saves a text file of the text array in another text source module (TxOpen, TxNote, TxClone or TxParse). Each element of the source text is saved as a line in the text file, which mirrors how the file is read with TxOpen, above.

Caution: This module overwrites any existing file of the same name, and the previous file contents will be lost.

Outputs:

Stat: Status - non zero if error saving; 0 if OK.

Inputs:

Path: Path and name of text file to be saved.

Hand: Handle of the text modules to use, to save the text array.

Strb: Strobe to save the file.


TxNote

Creates a text array from a text note pad, which is available when you open the Property dialog. You can type text into the pad, or paste it from the clipboard. Each line will become a line in the module's internal text array (which is saved with the module), one line per array element. Other string manipulation modules can access this text array by means of the Hand output.

Outputs:

TxOut: Selected Text Line (0 based).

Max: Maximum text array address.

Hand: Handle for other text modules to use, to access the text array.

Input:

Line: Line address to output (update on change or reset).


TxClone

Makes a copy of the text array from another text source module (TxOpen, TxNote, TxClone or TxParse). A text array is copied to the module's own internal text array (which is saved with the module), one line per array element. Other string manipulation modules can access this text array by means of the Hand output.

Outputs:

TxOut: Selected Text Line (0 based).

Max: Maximum text array address.

Hand: Handle for other text modules to use, to access the text array.

Inputs:

Line: Line address to output (update on change or reset).

Hand: Handle of module to clone.

Strb: Strobe to copy text array from target.


TxParse

Parses a line of text into a word array of one word per element. The resulting text array is stored in the module's own internal text array (which is saved with the module), one line per array element. Other string manipulation modules can access this text array by means of the Hand output.

Outputs:

TxOut: Selected text array element (0 based).

Max: Maximum text array address.

Hand: Handle for other text modules to use, to access the text array.

Inputs:

Word: Line/word address to output (update on change or reset).

Text: Text string to be parsed.

Strb: Strobe to parse text line into a word array.


TxWord

Fetch a word from a text line. Unlike TxParse, above, which also can return a single word from a text line, TxWord operates on a text string input, not on a text array from a text module with a Handle output; and with TxParse you can set the punctuation mark characters to ignore.

Outputs:

TxOut:Selected Text Word.

Max: Maximum word address for current line.

Inputs:

Line: Line of text from which to pick the output word. Note that Max, which is the line word count-1, is updated when the Line input changes, but the TxOut word value does not change until the Chng input changes. This is to allow modules to know the word count max of the new text input before they need to select the output word.

Word: Word number to select from line (0-Max), or -1 for random.

Punct: Punctuation marks or characters to ignore. Need not be actual punction mark characters, any characters entered here are ignored. Defaults to: ()<>{}[],.'!?:;

Chng: Any change to output a new word from the input line.


TxCSV

Return a field from a .csv (Comma Separated Value) file. Uses one of the text source modules such as TxOpen to supply the flat file contents. Address the Row as the Line input of the text source module, and the Colm input for the column.

If the first character of a line is "#" the entire line is treated as a comment, and is sent to the TxOut output regardless of the Colm value. Comment lines set the IsNum output to 0, non numeric, and the nOut to -1.

Outputs:

TxOut: Text output of selected field of .csv file.

nOut: Numeric output of selected field of .csv file or 0 if field is non numeric, -1 if a comment row (line starts with "#").

IsNum: True (1) if field is numeric, otherwise False (0).

MaxC: Max columns, numbered from 0 (get max rows from source text module).

Inputs:

Row: Row (line) address of field to output.

Colm: Column address of field to output.

Hand: Handle of text source module containing the .csv file data.

Chng: Any change to output row, column field from the .csv file.


TxStack

Stack for text string storage, last in first out (LIFO). This is the basic computer stack, like plates in a cafeteria stack. Items are put on top, and they are taken off the top. So the last one put in is the first one taken off. This stack is for text strings, there is a corresponding Stack for numerical values. The stack is 1024 elements deep; when the limit is reached it simply stops placing items into the stack until some are removed to make space. Stack values and pointers are stored with the patch.

Outputs:

Top: Top of stack, last item Pushed.

Next: Next to top of stack:

Nth: Nth item on stack, selected by Nth input below.

Depth: Number of items currently on the stack.

Inputs:

InTxt: Text string to push to stack.

Push: Any change to push input to top of stack.

Pop: Any change to pop top of stack (last in), discarding previous.

Nth: Random address to return Nth item on stack. If address is > depth or <0, nothing ("-") is returned.

Clear: Strobe to clear the stack.


TxQueue

Queue text string storage, first in first out (FIFO). Like a line of people at a restaurant, with new arrivals going to the end of the line, and those who finally get a table leaving from the front of the line. Queues are handy for creating buffers when you have items being created and then consumed but the rates of creation and consumption are irregular. So the queue acts as temporary storage, with data placed in the queue, then removed again in the same sequence order. This queue is for text string values, there is a corresponding Queue module for numerical values. The queue is 1024 elements deep; when full, the Enqueue change input is ignored until some items are dequeued to make additional room. The queue data and pointers are stored with the patch.

Outputs:

Queue: Least recent string entered (first in).

Depth: Current queue depth. When 0, the last valid item is in the Queue output; additional Dequeues set the Depth to -1 and the Queue output to "-".

Inputs:

InTxt: Value to enqueue.

Enque: Any change to enqueue InTxt (push to end of queue).

Deque: Any change to dequeue (first in), discarding previous.

Clear: Strobe to clear queue.


TxLine

Fetch a text line from a text source module.

Outputs:

TxOut: Selected Text Line (0 based).

Inputs:

Line: Line address to output (update on change or reset).

Hand: Handle of text source module.


TxInsert

Insert a text line into a text source module.

Outputs: (none)

Inputs:

Text: Text to insert into source module.

Line: Line address to insert text line (inserts ahead of existing text line).

Hand: Handle of text source module.

Strb: Strobe to insert the text line.


TxDelete

Delete a text line from a text source module.

Outputs: (none)

Inputs:

Line: Line address to delete in text source module.

Hand: Handle of text source module.

Strb: Strobe to delete the text line.


TxReplace

Replace a text line in a text source module.

Outputs: (none)

Inputs:

Text: Text to replace in source module.

Line: Line address to replace with text line.

Hand: Handle of text source module.

Strb: Strobe to replace the text line.


TxSort

Sort text lines in a text source module.

Outputs: (none)

Inputs:

Desc: 1 = descending sort direction, 0 = ascending.

Case: 1 = case sensitive, 0 = ingore case.

Hand: Handle of text source module.

Strb: Strobe to sort the text lines in the source module.


TxFind

Find a sub string within a text source module.

Outputs:

Line: Line address of string if found.

Posn: 1 based character position within line, 0 if not found.

Inputs:

Patrn: String pattern to search for.

Start: Line number to start the search.

Case: 1 = case sensitive, 0 = ingore case.

Hand: Handle of text source module.

Chng: Any change causes module to run the search.


StrFind

Reports position of a string within a string.

Output:

Posn: 1 based character position within line, 0 if not found.

Inputs:

Text: Text string to search in.

Patrn: String pattern to search for.

Start: 1 based start of search.

Case: 1 = case sensitive, 0 = ingore case.

Back: 1 = search backward from end of string, 0 = forward from begining

Chng: Any change causes module to run the search.


StrMerge

Merge (concatenate) two strings.

Output:

TxOut: Concatenated string from TxIn1 + TxIn2.

Inputs:

Text1: 1st string to be concatenated.

Text2: 2nd string to be concatenated.

Chng: Any change causes input strings to be concatenated and sent to output.


StrInsert

Inserts string at position given into target string.

Output:

TxOut: New string.

Inputs:

TxSrc: Source string to receive insertion.

TxIns: Sub string to insert.

Posn: 1 based position to insert, negative values to start from end of string.

Chng: Any change causes input at TxIns to be inserted into TxSrc at Posn.


StrDelete

Deletes characters at given position in target string.

Output:

TxOut: New string.

Clip: Clipped sub string.

Inputs:

Text: Source string.

Posn: 1 based position to start clipping, negative values to start from end of string.

Num: Number of characters to delete.

Chng: Any change causes deletion of Num characters starting at Posn.


StrTrim

Trim white space from string.

Output:

TxOut: New string.

Inputs:

Text: Source string to be trimmed.

Trim: 0=trim left, 1=trim right, 2 = trim left & right.

Chng: Any change to do the trim.


StrSubstr

Extracts a sub string at given position in target string.

Outputs:

TxOut: New string, substring extracted.

Size: Size of substring extracted..

Inputs:

Text: Source string.

Posn: 1 based position of start of substring to extract, negative values to start from end of string.

Num: Number of characters to extract.

Chng: Any change to extract substring.


StrCase

Change case of source string.

Output:

TxOut: New string.

Inputs:

Text: Source string.

Case: 0 = Upper, 1 = Lower, 2 = 1st char upper, others lower.

Chng: Any change produces specified case change.


StrInfo

Get information about a string.

Output:

Out: Specified string information.

Inputs:

Text: Source string.

Info: 0=length, 1=Xor checksum, 2=hashcode, 3=convert text number to numeric value, 4=ANSI Code.

0=length: returns the number of characters in the string.
1=Xor checksum: return the checksum derived by xoring each character. Useful for testing if a string is unique. This is the technique used in many MIDI SysEx checksums.
2=hashcode: returns a 16 bit hashcode. Useful for determining string uniqueness.
3=convert text number to numerical value: This will test the input string to determine if it can be converted to a decimal or hexadecimal number. If it can, the numeric value of the string is sent to the output. If the string cannot be converted to a number, the output is not changed. Use the StrNumber module to convert the other way, from a number to a string.
4=ANSI code: return ANSI code for 1st char in string.

Chng: Any change returns the specified string information.


StrChange

Produces strobe and change output whenever text input changes.

Outputs:

Strb: Strobe when there is a text or numerical change in Text input.

Chng: Increments when there is a text or numerical change in Text input.

Input:

Chng: Text (or number) input to test for change.


StrRand

Returns a string containing random, pronounceable text.

Output:

TxOut: Random string.

Inputs:

Num: Number of characters to return, 2 minimum.

Chng: Any change returns a new random string.


StrNumber

Converts a numeric value to a text string. Use the StrInfo module to convert the other way, from a string to a numeric value.

Output:

TxOut: Converted numeric value.

Inputs:

Num: Numeric value to be converted to a text string.

Hex: Type of conversion: 0=Decimal, 1=Hex, 2=Padded Hex, 3=ANSI Character, 99.99 = Format Decimal

To format decimal, enter the format number into the Hex input, with a "9" for each number place.  This will pad with 0's.  You may omit any combination of 9's to the left or right of the decimal point, and you may omit the decimal point for integer-only pading.


StrTime

Returns formatted time from seconds.

Output:

TxOut: New string.

Inputs:

Time: Time value in seconds.

Scale: Time scale: 1 for seconds, 1000 for milliseconds, etc.

Chng: Any change returns formatted time string.


SysTime

Returns System Time as an hh:mm:ss string.

Output:

Time: Time as hh:mm:ss string.


StrGenKey

Concatenates a number value with pre and post text to generate an indexed name key.

Output:

Key: Formatted key string.

Inputs:

Chng: Any change to create key.

Index: Index number to use for key.

Digts: Number of digits to use in key.

TxPre: Text in front of index number.

Post: Text following index number.

 

ArtWonk is Copyright 2003-2014 by John Dunn and Algorithmic Arts. All Rights Reserved.