360Works Scribe/Documentation

360Works Scribe User Guide

Scribe is a multi-purpose plugin for reading and manipulating documents, and working with text. See the 'How to use Scribe.fp7' file for step-by-step tutorials.

360Works Plugin Setup Guides

See Plugins_101 for Error reporting, installation, registration, and more.

Function Summary

• ScribeConvert ( input ; format { ; key1=value1 ; ... } ) —
• ScribeDifferenceReport ( someText ; otherText ) — Returns a report on the types of differences between two blocks of text.
• ScribeDifferencesBetween ( someText ; otherText { ; options } ) — Returns the highlighted differences between two blocks of text.
• ScribeDocListFields — Lists all fields in the loaded document.
• ScribeDocReadValue ( name { ; key=value ; ... } ) — Reads a field value from the currently loaded file.
• ScribeDocSaveContainer ( newName {; flatten=true ; type=file } ) — Returns the currently loaded file as a container field, applying any modifications.
• ScribeDocSaveFile ( path {; flatten=true } ) — Saves the currently loaded file to disk, applying any modifications.
• ScribeFileAsKeywords ( fileOrContainer ) — Returns a unique list of keywords for the file.
• ScribeFileAsText ( fileOrContainer{; param1=value1; param2=value2} ) — Returns the plain text content of the file.
• ScribeHighlight ( text; highlightPattern {; param1=value1 ; param2=value2 ; ...} ) — Highlights all occurrences of highlightPattern in text.
• ScribeLastError — Returns the last Scribe-related error which occurred.
• ScribeLicenseInfo — Returns information about the license used.
• ScribePatternMatchAll ( text; regex {; flags=flag1+flag2+flag3+...} ) — Returns a newline-delimited list containing pattern matches.
• ScribePatternReplaceAll ( text; regex; replacement {; param1=value1 ; param2=value2 ; ...} ) — Replace all occurrences of a regex pattern with some replacement text.
• ScribeVersion — Returns the version of the plugin which is installed.

Function Detail

ScribeConvert ( input ; format { ; key1=value1 ; ... } )

Parameters:

ScribeDifferenceReport ( someText ; otherText )

Returns a report on the types of differences between two blocks of text. This will always return three return-separated values: additions, modifications, deletions. Each line consists of a label, edit count, and character count.

For example, the following report:

additions: 2 214
modifications: 0 0
deletions: 1 47

Indicates that:

• 2 blocks were added, for a total of 214 characters
• No modifications
• 1 deletion, of 47 characters

Parameters:

someText

initial text

otherText

modified text

Returns: report on the number of differences between the two blocks of text.

ScribeDifferencesBetween ( someText ; otherText { ; options } )

Returns the highlighted differences between two blocks of text. Any text which is in 'otherText' but not in 'someText' is considered an addition, and is styled according to the ScribeStyleAddedText style. Any block of text which has changed from 'someText' to 'otherText' is considered modified text, and is styled according to the ScribeStyleModifiedText style. Any text which is in 'someText' but not in 'otherText' is considered a deletion, and is styled according to the ScribeStyleDeletedText style.

Custom Options

Pass "verbose=true" as a custom option to cause modifications to be displayed as a delete then an insert, instead of a modification.

Parameters:

someText

intial text

otherText

revised text

options

options

Returns: Styled text which displays the differences between the two strings, according to highlighting parameters.

ScribeDocListFields

Lists all fields in the loaded document.

PDF Support

Returns any named acrofields.

Word Support (Office 2007 format or later. Works with .docx files only.)

Returns any named placeholder tags.

Excel Support (Office 2007 format or later. Works with .xlsx files only.)

Returns a list of sheets in the excel document.

See also: ScribeDocReadValue, ScribeDocWriteValue

Returns: return-separated list of field names. For Excel documents, this returns the bottom-right cell coordinate.

ScribeDocReadValue ( name { ; key=value ; ... } )

Reads a field value from the currently loaded file. The behavior of this function depends on the type of document currently loaded (see ScribeDocLoad).

PDF Support

To read an acrofield from a PDF, pass the name of the acrofield whose value you wish to retrieve.

To read metadata values, use the respective name parameter:

• PDFPageCount - The number of pages.
• PDFTitle - The document's title.
• PDFAuthor - The name of the person who created the document.
• PDFSubject - The Subject of the document.
• PDFKeywords - Keywords associated with the document.
• PDFCreator - The name of the application that created the document.
• PDFProducer - If the document was converted to PDF from another format, the name of the application that converted it to PDF.
• PDFCreationDate - The date and time the document was created, in human-readable form.
• PDFModDate - The date and time the document was most recently modified, in human-readable form.
• PDFImageCount - The Number of images in the PDF.
• PDFImage[n] - The nth image in the PDF file.
• PDFMetadata - The XMP metadata associated with this PDF, if applicable.
• PDFAttachmentNames - A return-separated list of attachments in the PDF.
• PDFAttachment - A single attachment. You must pass in a 'filename' parameter indicating the name of the attachment you want.

Note: the descriptions for the fields above are suggested by PDF standards community, but may not strictly represent the values in those fields.

Word Support (Office 2007 format or later. Works with .doc and .docx files.)

Microsoft Word supports named placeholders in word documents called Content Control Fields. Pass the tag name of the Content Control Field as the parameter. Content control fields can only be created on Office 2007 on Windows, but can be read and written on both Windows and Mac. More information about how to make content control fields can be found here.

Table Support

Read values from a specific table cell in Microsoft Word using Excel-style syntax, e.g. to read the 3rd column of the 15th row of the first table in a Word document:

ScribeDocReadValue("Table1!C15")

Excel Support (Office 2007 format or later)

To read values from an excel sheet, pass the coordinates of a single cell, e.g. "A5".

To specify a sheet other than the first sheet, include the sheet name followed by an exclamation point, e.g. "Sheet 2!BB42".

New Excel Features in Scribe 2.0

To read a range of values as CSV, specify the start and end columns delimited by a colon, e.g. A1:C15. Optionally, pass "invert=true" as an additional parameter to read rows-first instead of column-first. Optionally, pass "rowSeparator=x" or "fieldSeparator=y" as additional parameter to specify custom delimiters.

ScribeDocReadValue("A1:C15" ; "fieldSeparator=|")

To get the maximum bounds of a worksheet, request MaxRow( ) or MaxCol ( ). Optionally, pass in worksheet=... as an additional parameter, for example:

ScribeDocReadValue("MaxRow()" ; "worksheet=Second Sheet" )

To read a cell's formula (instead of the formula result), pass "formula" as an optional parameter, e.g.

$c3Formula = ScribeDocReadValue( "C3" ; "formula" ) // SUM(A1,B1)

This will return the formula text, if one is specified on the cell.

To read cell comments, pass "commentText" as an optional parameter, e.g.

$c3Comment = ScribeDocReadValue( "C3" ; "commentText" )

This will return the color as a numeric value, which you can pass to FileMaker as a

To read cell background colors, pass "background" as an optional parameter, e.g. to read a cell value and then style some FileMaker text the same color:

$c3BackgroundColor = ScribeDocReadValue( "C3" ; "background" )
# $c3BackgroundColor is a numeric color value, we can use it to style some text
TextColor ( myTable::sampleField ; $c3BackgroundColor )

XML Support

To read values from an XML document, pass an XPath expression identifying the node to be modified as the first parameter.

Parameters:

name

attribute name to read.

See also: ScribeDocListFields, ScribeDocWriteValue

Returns: value of the named attribute in the currently loaded file, or "ERROR" if an error occurs.

ScribeDocSaveContainer ( newName {; flatten=true ; type=file } )

Returns the currently loaded file as a container field, applying any modifications. This closes the document after saving it to a temporary folder.

The newName parameter tells Scribe what to name the container field value. This can take two forms:

• It can be empty, like this: ScribeDocSaveContainer(""). That tells Scribe to keep the original filename.
• It can be just a filename, like this: ScribeDocSaveContainer("MyNewFile.doc"). That tells Scribe to return a container field with this new filename.

The optional flatten parameter can be used with PDF forms to save a "flattened" version of the form, this would make the form fields unenterable.

The optional type parameter can be set to "file" to explicitly save a file container instead of an image.

PDF Password support (new in Scribe 2.0), pass a "password" parameter to password-protect the saved PDF. You can optionally specify separate "userPassword" and "ownerPassword" parameters. For example, if you've done a find and replace operation on a Word document and would like to store it into a container field called 'ResultContainer' while retaining the original filename, you would do it this way: Set Field[ ResultContainer; ScribeDocSaveContainer("") ]

Parameters:

Returns: A container field value which can be inserted into any container field with a Set Field script step.

ScribeDocSaveFile ( path {; flatten=true } )

Saves the currently loaded file to disk, applying any modifications. This closes the document after saving it.

The path parameter tells Scribe where to save the file to. This can take several forms:

• It can be empty, like this: ScribeDocSaveFile(""). That tells Scribe to save the modified file into a temporary directory, keeping the original filename.
• It can be just a filename, like this: ScribeDocSaveFile("MyNewFile.doc"). That tells Scribe to save the modified file into a temporary directory, with a new filename.
• It can be just a directory, like this: ScribeDocSaveFile( Get (DesktopPath) ). That tells Scribe to save the modified file into the specified directory, keeping the original filename.
• It can be a full path with a filename, like this: ScribeDocSaveFile( Get(DesktopPath) & "MyNewFile.doc" ). That tells Scribe to save the modified file into the specified directory with a new filename.

The optional flatten parameter can be used with PDF forms to save a "flattened" version of the form, this would make the form fields unenterable.

PDF Password support (new in Scribe 2.0), pass a "password" parameter to password-protect the saved PDF. You can optionally specify separate "userPassword" and "ownerPassword" parameters.

Parameters:

Returns: FileMaker file path to the saved file, for example 'file:/Macintosh HD/Users/jesse/Desktop/Letter_to_clients.docx'. This can be used with the 'Insert File' script step to insert the file into a container field in FileMaker.

ScribeFileAsKeywords ( fileOrContainer )

Returns a unique list of keywords for the file. Unlike ScribeFileAsText, this only returns unique names, and strips out common "stop words" like "a", "and", "the", etc. This can reduce storage requirements if you are performing text searches against the contents of files, but don't need the extracted text to be human-readable.

Parameters:

file

file or container field to extract index from

See also: ScribeFileAsText

Returns: A unique list of keywords in the currently loaded document, or "ERROR" if an error occurs.

ScribeFileAsText ( fileOrContainer{; param1=value1; param2=value2} )

Returns the plain text content of the file.

For binary file document formats such as Word, PDF, etc. this attempts to return a human-readable presentation of the document. XML documents are returned as-is. Any unrecognized file will have its raw text contents returned (see optional parameters to customize this).

You can pass in optional additional parameters to customize the behavior of this function. A list of customizations follows:

• onlyKnownTypes=0 or 1. If this is set to 1, then Scribe will return an empty value "" for unknown file types, instead of returning their raw contents. The default is 0.

Here is a list of supported file types for reading text from:

• pdf
• doc, docx
• xls, xlsx
• ppt, pptx
• xml, xsd
• rtf
• htm, html
• JPEG (will read EXIF metadata)
• csv, txt, tab
• msg (Outlook emails)
• pages, key (Apple's Pages and Keynote documents '08 & '09)

Parameters:

file

file or container field to extract text from

Returns: plain text content of the currently loaded document, or an empty string if the input is empty, or "ERROR" if an error occurs.

ScribeHighlight ( text; highlightPattern {; param1=value1 ; param2=value2 ; ...} )

Highlights all occurrences of highlightPattern in text.

Unlike the substitute function, this is case-insensitive by default. The highlightPattern function supports regular expression patterns.

Regular Expression Pattern Processing

Using the flags optional parameter, you may set the following options, each of which influences the way patterns are matched.

caseInsensitive

Enables case-insensitive matching for US-ASCII characters.

multiline

Does not match line-terminating characters. This means that when the input text is a return-separated list, each line is matched independently.

literal

Treats metacharacters like ^ and $ and escape sequences like \t as literals.

includeLineEndings

Matches line-terminating characters, which means that a return-separated list would be treated as a single text block.

ignoreWhitespace

Ignores whitespace characters.

Example

Example of a highlight operation to match the string "file://" at the beginning of each line of a return-separated list.

Set Field [ Globals::highlighted_text =
    ScribeHighlight(
    "file://temp/doc.txt" & ¶ &
    "file://documents/doc.txt" & ¶ &
    "http://my.site.com/home" & ¶ &
    "ftp://my.ftpsite.com/upload" ;
        "^file://" ;
        "flags=multiline"
    )
]

This matches "file://temp/doc.txt" & ¶ & "file://documents/doc.txt"

Style, color and size

Highlighting style is determined by the three optional parameters: colorRGB, styles, and size. Consult the Filemaker TextStyleAdd and TextColor documentation for more details about named Filemaker text styles and colors.

Example

Example of a highlight operation to make any occurrences of "atlanta" blue and bold (the default highlight style is bold, blue text):

Set Field [ Globals::highlighted_text =
    ScribeHighlight(Documents::body ; "atlanta")
]

Example of a highlight operation to highlight runs of 1 or more sequential numbers as green italic text:

Set Field [ Globals::highlighted_text =
    ScribeHighlight(
        Documents::body ;
        "[0-9]+" ;
        "colorRGB=" & RGB(0;255;0) ;
        "styles=" + Italic"
    )
]

Parameters:

text

The input text

highlightPattern

the word or regular expression pattern to highlight

additionalParameters

Additional parameters are specified using a name=value syntax. The parameters colorRGB, size and styles control the look of the replaced text. The parameter flags controls the way in which pattern matching is performed.

See also: ScribePatternReplaceAll

Returns: The input text with all occurrences of highlightPattern highlighted with the current styles.

ScribeLastError

Returns the last Scribe-related error which occurred. This should be called any time that a plugin function returns "ERROR" to get a user-readable description of the error.

Returns: Error text, or "" if there was no error.

ScribeLicenseInfo

Returns information about the license used.

ScribePatternMatchAll ( text; regex {; flags=flag1+flag2+flag3+...} )

Returns a newline-delimited list containing pattern matches. Any text that is not a pattern match will be omitted.

Example of a function to extract a return-separated list of numbers from a string.

ScribePatternMatchAll("123 and 5321 are open, but 0121 is closed" ; "[0-9]+")
/* returns the following:
123
5321
0121
*/

Regular Expression Pattern Processing

Using the flags optional parameter, you may set the following options, each of which influences the way patterns are matched.

caseInsensitive

Enables case-insensitive matching for US-ASCII characters.

multiline

Does not match line-terminating characters. This means that when the input text is a return-separated list, each line is matched independently.

literal

Treats metacharacters like ^ and $ and escape sequences like \t as literals.

includeLineEndings

Matches line-terminating characters, which means that a return-separated list would be treated as a single text block.

ignoreWhitespace

Ignores whitespace characters.

The default behavior of this function uses the caseInsensitive and includeLineEndings flags, so the following function calls are equivalent:

ScribePatternMatchAll(
    "Wilhelm¶wilson¶Williams¶Zander" ;
    "wil.*" ;
    "flags=includeLineEndings+caseInsensitive"
)
ScribePatternMatchAll(
    "Wilhelm¶wilson¶Williams¶Zander" ;
    "wil.*"
)

Parameters:

text

input text

regex

regular expression pattern.

flags

An additional parameter used to specify flags that control how pattern matching is performed. To specify multiple flags, separate each with a plus sign (e.g., ..."flags=literal+ignoreWhitespace")

Returns: Any pattern matches, separated by line breaks.

ScribePatternReplaceAll ( text; regex; replacement {; param1=value1 ; param2=value2 ; ...} )

Replace all occurrences of a regex pattern with some replacement text. The replacement text can optionally be styled.

Highlighting style is determined by the three optional parameters: colorRGB, styles, and size. Consult the FileMaker TextStyleAdd and TextColor documentation for more details about named Filemaker text styles and colors.

Backreferences can also be used with the regular expression. Replacement text can use dollar sign syntax ($1, $2, etc.) to refer to these groups.

Regular Expression Pattern Processing

Using the flags optional parameter, you may set the following options, each of which influences the way patterns are matched.

caseInsensitive

Enables case-insensitive matching for US-ASCII characters.

multiline

Does not match line-terminating characters. This means that when the input text is a return-separated list, each line is matched independently.

literal

Treats metacharacters like ^ and $ and escape sequences like \t as literals.

includeLineEndings

Matches line-terminating characters, which means that a return-separated list would be treated as a single text block.

ignoreWhitespace

Ignores whitespace characters.

Example of simple replace, converting two or more consecutive line breaks to a single line break:

ScribePatternReplaceAll(
    "Line one¶Line Two¶¶¶Line Three¶Line Four" ;
    "\n+" ;
    "¶"
)
// returns "Line one¶Line Two¶Line Three¶Line Four"

Example of a highlighting replace operation, highlighting the literal string "quick" by using styles:

ScribePatternReplaceAll("The quick brown fox" ;
    "quick" ;
    "quick" ;
    "colorRGB=" & RGB(128 ; 128 ; 255) ;
    "styles=" + Bold
)
// returns The quick brown fox

Parameters:

text

The input text

regex

The regular expression

replacement

The text to replace the found occurrences with

additionalParameters

Additional parameters are specified using a name=value syntax. The parameters colorRGB, size and styles control the look of the replaced text. The parameter flags controls the way in which pattern matching is performed.

See also: ScribeHighlight

Returns: The input text with all occurrences of regex replaced with replacement

ScribeVersion

Returns the version of the plugin which is installed.