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 formatting 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 formatting of text, when the text is copied from the document all formatting is 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 formatting 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.
☞ Perl macros have a file extension of “pl”.
• <https://en.wikipedia.org/wiki/Perl>
Components of a Perl script header
This tells Nisus Writer Pro to start reading directives
#source ( front | next | none | clipboard)
This tells Nisus Writer Pro where to get the text that will be sent to the Perl Script. Choose one of the options, e.g. '#source front'. Front is the front document, next is the document behind the front document, none is no data and Clipboard is whatever text is on the Clipboard.
#destination ( front | next | none | clipboard | new) [replace]
Destination tell Nisus Writer Pro what to do with any data returned from the Perl script. The options are the same as for source, except 'new' which creates a new document. The replace option is used if you want to overwrite the destination, otherwise any text returned from the Perl script is appended to the destination. Replace only has an effect if destination is front or next.
#(send text as rtf | send rtf | rtf | text as rtf)
If any variant of this option is present, then the text will be sent to Perl as RTF. Anything returned from the Perl script will be treated as RTF and an attempt will be made to convert it back into styled text before putting it into the destination.
This tells Nisus Writer Pro to treat the following lines (minus the leading '#') as menu macros to be run before execution of the Perl script. Any other directive will stop collection of menu macro lines.
This tells Nisus Writer Pro to treat the following lines (minus the leading '#') as menu macros to be run after the execution of the Perl script. Any other directive will stop collection of menu macro lines.
This tells Nisus Writer Pro to stop looking for directives.
| Previous Chapter Perl Macros |
<< index >> |
Next Chapter Write AppleScripts |