strutils

A Strings object in Praat is an ordered list of strings that is most commonly used to represent either lists of files or directories in disk (as returned by the Create Strings as file list... and Create Strings as directory list... standard Praat commands), or the lines of a text file that was read with the Read Strings from raw text file... command.

“strutils” provides some new ways to create Strings (including the possibility of creating an empty Strings object, as well as making fully-specified file and directory lists), and some commands to manipulate existing objects.

Scripts

Create empty Strings: name$

There is no command regularly available in Praat to create empty Strings, which can only be created as listings of file contents or entries in the file structure. To make use of the full benefit of Strings, this command makes it possible to create Strings that are guarranteed to be empty.

All the processing done by this command is handled internally by the @createEmptyStrings procedure.

Extract strings: search$, match$, use_regex

Creates a Strings object which contains a subset of the strings of an original Strings object. The newly created object is selected after execution of this script.

Create Strings as file list (full path): name$, path$, glob$, keep

Same as Create Strings as file list... but with full paths. The processing of this script is handled internally by @fileListFullPath.

Create Strings as directory list (full path): name$, path$, glob$, keep

Same as Create Strings as directory list... but with full paths. The processing of this script is handled internally by @directoryListFullPath.

Create Strings as file list (recursive): name$, path$, glob$, depth, sort

Same as Create Strings as file list (full path)... but recursive. Makes a list of all matching files under the specified directory and any of its subdirectories (up to the specified depth). The processing of this script is handled internally by @fileListFullPath.

Create Strings as directory list (recursive): name$, path$, glob$, depth, sort

Same as Create Strings as directory list (full path)... but recursive. Makes a list of all matching directories under the specified directory and any of its subdirectories (up to the specified depth). The processing of this script is handled internally by @directoryListFullPath.

Replace strings: search$, replace$, how_many, regex

Takes a Strings object and performs a “search and replace” operation upon it. The modifications are done on a separate Strings object, leaving the original untouched. The newly generated Strings object is selected after execution.

The string matching can be done using string literals, which will match if the occur anywhere in the string or regular expression patterns. This can be controlled with the regex variable. The value of the how_many will determine the maximum number of replacements to perform.

Internally, this script calls @replaceStrings or @replaceStrings_regex as appropriate.

Find in Strings: search$, regex

Run on a single Strings object, this script performs a search for the specified string (interpreted either as a literal or as a regular expression pattern) and prints the index of the first found string to the Info window. If the string was not found, 0 is printed instead.

Sort (generic): numeric, case

Perform a generic sort on a Strings object.

The default Sort command for Strings sorts things ASCII-betically, such that uppercase letters come before lowercase, and numbers are ordered as if they were words. Since Strings often represent lists of files or directories, this is often not what one wants, specially in the case of names starting with numbers.

Ordered ASCII-betically, a list like

20, a10, Abc, 10, 1, a2, abc, abdce, 2, Ab, a1

would become

1, 10, 2, 20, Ab, Abc, a1, a10, a2, abc, abdce

A generic sort treats numbers like numbers, and strings like strings, such that the previous list would be ordered in a much more intuitive way:

1, 2, 10, 20, Ab, Abc, a1, a2, a10, abc, abdce

The specifics of the ordering can be adjusted with the two boolean parameters. The first one sets the relative position of numbers (or strings that look like numbers) as a group, while the second one allows one to do a case-insensitive sort. As an example, with both values set to false (the non-default value), the above list would become

a1, a2, a10, Ab, abc, Abc, abdce, 1, 2, 10, 20

with the relative position of the fifth and sixth terms being unspecified.

Procedures

create_empty_strings.proc

createEmptyStrings: name$

Creates an empty Strings object. It takes the name of the object to create, and stores the ID of the created object in the internal .id variable.

After execution of this procedure, the newly created object will be selected.

directory_list_full_path.proc

directoryListFullPath: name$, path$, glob$, keep

Same as Create Strings as directory list... but with full paths. This procedure internally calls that command, and the fate of the Strings object generated by it will depend on the value of .keep. If true, the object is kept and its ID stored in .relative. If false, it is removed and that variable set to undefined.

The selection will include all generated Strings, in which the one with full paths will be the most recent. The ID of this object will also be stored in .id, and in .absolute, for contrast with .relative.

file_list_full_path.proc

fileListFullPath: name$, path$, glob$, keep

Same as Create Strings as file list... but with full paths. This procedure internally calls that command, and the fate of the Strings object generated by it will depend on the value of .keep. If true, the object is kept and its ID stored in .relative. If false, it is removed and that variable set to undefined.

The selection will include all generated Strings, in which the one with full paths will be the most recent. The ID of this object will also be stored in .id, and in .absolute, for contrast with .relative.

find_in_strings.proc

findInStrings: search$, match

Searches for a literal string in a Strings object. For matching with regular expressions, use @findInStrings_regex.

findInStrings_regex: regex$, match

Searches a Strings object for matches to a regular expression pattern. For matches with literal strings, use @findInStrings.

replace_strings.proc

replaceStrings: search$, replace$, how_many

Takes a Strings object and performs a “search and replace” operation upon it. The modifications are done on a separate Strings object, leaving the original untouched.

The string matching is done using string literals (which will match if the occur anywhere in the string). To use regular expression patterns, use @replaceStrings_regex.

replaceStrings_regex: search$, replace$, how_many

Takes a Strings object and performs a “search and replace” operation upon it. The modifications are done on a separate Strings object, leaving the original untouched.

The string matching is done using regular expression patterns. To use literal strings, use @replaceStrings.

extract_strings.proc

extractStrings: query$

Creates a Strings object which contains a subset of the strings of an original Strings object. Search query is a literal string. For regular expression matching, use @extractStrings_regex.

The new Strings object will be selected after execution.

extractStrings_regex: regex$

Creates a Strings object which contains a subset of the strings of an original Strings object. Search query is a regular expression pattern. For matching with literal strings, use @extractStrings.

The new Strings object will be selected after execution.

array.proc

array

Creates a representation of an array using a Strings object. After calling this procedure, a new, empty Strings object will be selected.

push: .val

Append the provided numeric value to the end of the array

push$: .val$

Append the provided string value to the end of the array

pop

Remove the last item in the array

unshift: .val

Append the provided numeric value to the beginning of the array

unshift$: .val$

Append the provided string value to the beginning of the array

shift

Remove the first item in the array

slice: .from, .to

Creates a Strings object as a subset of the selected Strings, with the strings between the first and last provided. The original Strings object is not modified in the process.

excise: .from, .to

Similar to @slice, but this procedure also removes the extracted strings from the original.

splice: .at, .strings

Insert the contents of an existing array into the selected array

join: .glue$

Joins all elements of the array into a single string, using the string in .glue$ as a separator between them.

split: .sep$, .str$

Takes the contents of .str$ and separates it into a number of smaller strings using the string in .sep$ as the separator string. The separator can be longer than one character. The match is made using it as a string literal.

For compatibility with the version of this procedure in the “utils” plugin, split substrings are stored in the .return$[] indexed variable, which will have a length equal to the value in .length. Additionally, they are pushed to a Strings-array whose ID is stored in .id.

Including this file modifies the behaviour of the procedure from the utils plugin of the same name.