Latest revision as of 20:48, 9 May 2017

[edit] 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.

[edit] 360Works Plugin Setup Guides

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

[edit] Function Summary

[edit] Function Detail

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

[edit] 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

[edit] 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.

[edit] 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.

[edit] 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.

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".

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

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

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

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

$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.

[edit] 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.

• 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. <p class="version2">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("") ]

[edit] ScribeDocSaveFile ( path {; flatten=true } )

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

• 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. <p class="version2">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.

[edit] 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.

[edit] 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)

[edit] 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"
    )
]

[edit] 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.

[edit] ScribeLicenseInfo

Returns information about the license used.

[edit] 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.*"
)

[edit] 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

[edit] ScribeVersion