Belle Nuit Montage - Editing etc. - Lausanne - Suisse - e-mail: matti@belle-nuit.com

Homepage : Textfilter [ Index - API - Examples - FAQ - Maillist - Plugins - Script - Userguide - Win32 ] - Search - Sitemap

Textfilter Script Language

• Introduction
• Language Reference
  • Variables and Constants
  • Arrays
  • Operators
  • Comments
  • Control Structures
  • Functions
  • Error Messages

Introduction

Textfilter uses the Realbasic Script language for its scripts and for the plugins, expanded with Textfilter functions. The following text will only explain the most important functions. For full documentation, refer to the Realsoftware website: http://www.realsoftware.com.

There are two main functions which interact with the application, so you will always use them:

• gettext to get the text
• print expression to print the text to the output

The script is one main function, for which you do not define a header and a footer. Inside the script, however, you can define functions before the code of the main function.

While you are writing the script, you may want to put the script filter on bypass, so that it is not executed with invalid code.

This simple script will just return the input

print gettext

Now, lets make it a bit more usuable

dim in,out as string
in = gettext
out = in
print out

Now you have everything to write your code. You just need to analyze the in variable and set the out variable. The following script removes all lines starting with an asterisk.

dim in,out, theline as string
dim i ,rc as integer
in = gettext
rc = countfields(in,chr(13))
for i = 1 to rc
theline = nthfield(in,chr(13),i)
if left(theline,1)<>"*" then
out = out + theline + chr(13)
end if
next
print out

The script code is executed for the whole text or a selection in it, if the application is in text mode, or for every cell and a selection of columns, if the application is in list mode (in the order of the rows and inside the row in the order of the columns). However, the script can know which row or column it is in at the moment with the getrow, getcolumn and getcolumnname commands. Also, the script can use the getkey and the setkey methods to store intermediate values between the cells.

Language Reference

Variables and Constants

Variables can be of the type integer, double, boolean and string. All variables have to be defined at the beginning of the code. Variables are defined with the Dim statement, constants with the Const statement.

Examples:

dim i as integer
dim t as text
const parselength=1024

Do not use any reserved word for variable names or you will have a severe parsing error. Reserved words are the names of the operators, the control structures and of all built-in functions.

Variable names are not case-sensitive.

Variables are automatically initialized (integer and double: 0, string: ""; boolean: false).

Arrays

You can define arrays of variables in single and multiple dimensions like

dim lines(5) as string
dim cells(5,10) as string

where lines is an array of 6 elements going from 0 to 5. You can also define an empty array with

dim lines(-1) as string

Later in the code, you can either use the redim statement

redim cells(10,20) as string
redim lines(0) as string

If you try to access an array element which is not in the dimension, you will get an "Out of Bounds Exception".

Operators

The following operators are supported:

• +
• -
• *
• /
• \ (integer division)
• mod
• <
• >
• = (assignment or comparision dependend on context)
• >=
• <=
• <>
• and
• not
• or

Paranthesises can be used to define the execution order.

You can use the operators + , <, <=, >, >= and = for the strings.

Comments

Text after ' or // are ignored by the interpreter until the next line.

Control structures

The following control structures are supported:

• if condition then
  statement
  [elseif condition then
  statement]
  [else
  statement]
  end if
• select case expression
  [case expression:
  statement]
  [else
  statement]
  end select
• for counter = start to / downto end [step stepvalue]
  statement
  [exit]
  statement
  next
• while condition
  expression
  wend
• do
  expression
  loop until
• return

The "if" in "end if" and the "select" in "end select" are not optional.

You can also write functions and subroutines.

• function name ([parameterlist]) as type
  statement
  [return [value of type]]
  [statement]
  end function
• Sub([parameterlist]
  statement
  [return [value of type]]
  [statement]
  end sub

Functions and subroutines must be defined before they are used.

Parameters in functions and subroutines can be defined byref or byval, byval being the default, except for arrays.

Notes:

• You cannot use function within functions. Also, the functions defined by Textfilter which expand the RBscript language cannot be used in a function. (These functions are implemented as a header to your script.)
• Do not write endless loops, as this will block your computer. In longer loops, use the usercancelled function to allow the user to exit a loop.
• Avoid to create very big text strings within your loops or your programm will crash.

Functions

In the following list of functions, only the textfunctions are explained. For full documentation, refer to the Realsoftware website.

Note that all string functions return a copy of the string and leave the input string unchanged.

abs(double) as double

acos(double) as double

asc(string) as integer

Returns the Ascii-value for the first character of a string.

ascb(string) as string

Returns the Ascii-value for the first byte of a string. This makes a difference for double-byte languages like japanese.

asin(double) as double

atan(double) as double

atan2(double,double) as double

bitwiseand(integer,integer) as integer

bitwiseor(integer,integer) as integer

bitwisexor(integer,integer) as integer

cdbl(string) as double

Returns the numerical value of a string

ceil(double) as double

chr(double) as string

Returns the character of a given Ascii-value.

Newline is chr(13) and tabulator is chr(9). While Windows textfiles use chr(13)+chr(10) for newline, for the filters only chr(13) is used. The parsing of the correct line separator should be done with the input and the output filters. To write platform independent code, you should better use getnewline than chr(13).

chrb(double) as string

Returns a singlebyte-character of a given Ascii-value.

closeprogress

Makes the progress bar invisible.

cos(double) as double

countfields(string1,string2) as integer

Returns the number of fields in string1, given the separator string2. The separator is not case-sensitive.

Returns 1 if the separator is not present, and 0 if the string1 is empty.

cstr(double) as string

Converts a number to a string using local conventions.

exp(double) as double

false

floor(double) as double

format(double,string) as string

Converts a number to a string using a given formatstring. The following characters are allowed:

• # placeholder showing digit, when it is present
• 0 placeholder showing digit anyway
• . placeholder for decimal point
• , placeholder for thousands separator
• % percentage whith number multiplied by 100
• ( open parenthesis
• ) close paranthesis
• + diplays plus sign, if number is positive or minus, if it is negative.
• - dsplays minus sign, if a number is negative
• E or e scientific notation
• \character any character

Use the following format for integers:

format(5958020,"0") = 595820

Use the following format for timecodes:

format(5958020,"00\:00\:00:\00") = 00:59:58:20

framestoTC(frames as integer, framerate as double) as string

Converts a frame count to timecode.

getcolumn as integer

Returns the active column (1-based), if the input is in listmode.

getcolumname as integer

Returns the name of the active column, if the input is in listmode.

getfilename as string

Returns the filename of the current text. May be a path if the file is in a subfolder.

getfolderseparator as string

Returns the character of the system defining the folder separator (":" for MacOS, "/" for Windows). Use this method to write platform independent plugins.

getkey(thekey as string) as string

Returns the value of a given key. You can set key values which are persistent with the setkey method.

getmaccreator as string

Returns the mac creator string of the current text.

getmactype as string

Returns the mac type of the current text.

getnewline as string

Returns the characters sequence of the system defining newline (chr(13) for MacOS, chr(13)+chr(10) for Windows). Use this method to write platform independent plugins.

getothertext(n as integer) as string

Returns another text than the current to be filtered. n must be between 1 and gettextcount.By calling this method, the alternative text becomes the current text, so functions calling the properties of the text (setkey,getfilename,getmactype,getmaccreator...) are calling this text. However, this will not affect the output text.

getparameter(theparameter as string) as string

Returns the parameter value (plugins only).

getrow as integer

Returns the active row (1-based), if the input is in listmode.

gettext as string

Returns the input text depending on the selection.

gettextcount as integer

Returns the count of text files to be filtered. Use this with getothertext to access other text files than the current one.

hex(integer) as string

Formats the number using hexadecimal notation.

instr(integer,string1,string2) as integer

Looks for an occurence of string2 in string1, starting at position of integer. If it finds one, it returns the position, if it doesn't, it returns zero.

Instr is not case-sensitive.

instrb(integer,string1,string2) as integer

Looks for an occurence of string2 in string1, starting at position of integer, using raw bytes. If it finds one, it returns the position, if it doesn't, it returns zero.

left(string,integer) as string

Returns the leftmost characters of a string.

leftb(string,integer) as string

Returns the leftmost characters of a string, using bytecount.

log(double) as double)

lowercase(string) as string

Returns the string with all lowercase characters.

ltrim(string) as string

Removes the spaces at the beginning of the string

max(double,double) as double

microseconds

mid(string,integer1,integer2)

Returns a substring of string starting at position integer2 and with a length of integer2.

midb(string,integer1,integer2)

Returns a substring of string starting at position integer2 and with a length of integer2, using byte count.

min(double,double) as double

nthfield(string1,string2,integer) as string

Returns the nth field in string1, using string2 as a separator. The string2 is not case-sensitive.

oct(integer) as string

Formats the number using octal (base 8) notation.

openprogress

Makes the progress bar visible. Use with setprogress and closeprogress.

pow(double,double) as double

print string

Returns strings to the output. Multiple occurences of string will append the text to the output.

redim array(integer)

replace(thestring,oldstring,newstring) as string

Replaces the first occurence of oldstring in thestring with newstring. The replace is not case-sensitive.

replaceall(thestring,oldstring,newstring) as string

Replaces all occurences of oldstring in thestring with newstring. The replace is not case-sensitive.

right(string,integer) as string

Returns the rightmost characters of a string

rightb(string,integer) as string

Returns the rightmost characters of a string, suing byte count

rnd as double

round(double) as double

rtrim(string) as string

Removes spaces at the end of the string

setkey(thekey as string, thevalue as string)

You can set key values which are invisible, but will be part of the text. You can set key to communicate values to another script or you can also set key to keep values betweens the cell of a list, as the script is executed for every cell.

setprogress(n as value)

Sets the progress bar to the value n (the minimum being 0 and the maximum 100). You must call openprogress first to make the progress bar visible, and closeprogress at the end.

sin(double) as double)

sqrt(double) as double

str(double) as string

Converts a number to a string, using default formats. Is fast coded, but for big numbers, format(double,"0") does a better job.

strcomp(string1,string2,integer) as integer

Compares string1 with string2, using criterium integer

• 0: binary mode
• 1: text mode (lexicographic)

It returns -1, if the string2 is later in the alphabet, +1 if it is before, and 0, if both strings are the same. This function with criterium 0 is more exact than the operator =, which is case-insensitive

tan(double) as double

TCdiv(timecode as string, factor as double, framerate as double) as integer

Divides a timecode through a factor

TCminus(timecode1 as string, timocode2 as string, framerate as double) as integer

Substracts two timecodes.

TCmult(timecode as string, factor as double, framerate as double) as integer

Multiplies a timecode with a factor

TCplus(timecode1 as string, timocode2 as string, framerate as double) as integer

Adds two timecodes.

TCtoframes(timecode as string, framerate as double) as integer

Converts a timecode to framenumbers.

ticks as integer

titlecase(string) as string

Returns the string with every first character of a word in capitals.

trim(string) as string

Removes spaces at both the beginning and the end of the character

true

ubound(array)

Returns the highest index of a single-dimensioned array.

uppercase(string) as string

Returns the string all letters in capitals

usercancelled as boolean

Returns true if the user has cancelled (command-period). Use this command in loops so that the user can stop a long rendering

Example:

for i = 1 to 100
if usercancelled then
exit
end if
// your code goes here
next

val(string) as double)

Returns the numeric value of a string, using the point as decimal separator.

Error messages

Error messages are displayed in the console window.

• 1 Syntax error
• 2 Type mismatch
• 3 Can't select that type
• 4 Unimplemented compiler error
• 5 The parser's stack has overflowed
• 6 This function call has more parameter than it needs
• 7 This function call does not have enough arguments
• 8 The number of arguments supplied is incorrect
• 9 The kind of data cannot be assigned to this kind of variable
• 10 The identifier is not defined
• 11 This operator does not apply to these operands
• 12 Logic operations require boolean operands
• 13 The array bounds must be integers
• 14 This isn't a function, but you are calling it like one
• 15 This isn't an array, but you are accessing it like one
• 16 Not enough dimensions were specified in this array acess
• 17 Too many dimensions were specified for this array
• 18 The array subscript is not an integer
• 19 You can't assign a value to an entire array at once
• 20 Can't pass an array as som other type of parameter
• 21 Byref arguments must receive variables, not expressions.

Textfilter was written with REALbasic http://www.realsoftware.com

Homepage : Textfilter [ Index - API - Examples - FAQ - Maillist - Plugins - Script - Userguide - Win32] - Search - Sitemap

e-mail: matti@belle-nuit.com - www.belle-nuit.com - 6.1.02