Writing perl scripts, The recommended way, to structure perl macros, Learn more about perl – Nisus Writer Pro User Manual

Page 436: Components of a perl script header, Nisus macro block, Ge 416

Advertising

416

Writing Perl Scripts

You can write your own macros using the well-known Perl script language. Perl is a very powerful
scripting language, particularly for manipulating text. It includes the full power of Regular
Expressions for finding and changing text based on patterns. Perhaps the most common form of a
Macro simply reads each text line, modifies it where necessary and writes it back to where it came
from.
A Perl Macro cannot work directly on text in a document. Instead, it must first copy the text from a
document, change it and then write it back to the same or a different document. In those cases
where the attributes of the changed text are not important, the results are the same as if the
changes were done directly to the text in the document. However, because Perl Macros are not yet
sensitive to the attributes of text, when the text is copied from the document all attributes are
removed. In practical terms this means if the text being changed has multiple fonts, styles or sizes
before the change, after the change all such attributes will be the same. Although Nisus Writer Pro
provides a way to maintain formatting when changing text in a Perl Macro (through the option of
including the RTF formatting in the copied text) only the advanced Perl connoisseurs will be able to
take advantage of the feature.
Perl scripts are commonly written to read the input from a disk file and write the output to a disk
file. Perl Macros can be written that way too. However, it is much more fun (and lets you see the
results immediately for possible adjustment) to watch the Macro at work on the currently open
document.

The recommended way, to structure Perl Macros

Perl macros are plain text files that contain Perl code.
Along with an optional block of directives that tell Nisus Writer Pro what data to send to the Perl
script and what to do with data sent back from it. Directives are placed, one per line, beginning with
a ‘#’ character so that Perl will treat them as comments.
Perl uses "<STDIN>" to designate the default input and simple “print” statement will print to the
default output. If you don’t re-define the default input, it is assumed to be the active document
window. The default output (unless you re-define it) is a new document which will automatically
open when there is any output printed by a Macro. You can use the first lines of a Perl Macro, called
the “Header” to re-define these defaults.
The header can be additionally used for executing Nisus Writer Pro Menu Macro commands. This is
quite useful for preparing for the execution of a Perl macro and for finishing off after a Perl macro
executes.
You can define the default input to be any one of front, next, Clipboard, and none. Front and next
refer to active open windows. Clipboard is obvious and none means that no data will be available as
default input. If you omit the default specification, the contents of the current active window will be
sent to the Perl Macro as the default input. This sending occurs whether you will be using it or not,
and so if you are not going to be needing a default input (for example, you might be reading a disk
file to get your input, or no input is needed) you should declare none as the input.
Define the default input and output as the Clipboard and to use the header to execute the Copy
menu command before executing the Macro and the Paste menu command after executing the
Macro.
Such a macro will work on the selected text, first copying it to the Clipboard, then pasting it back
into the selection.