< Appendix B | Appendix D >

529 Appendix C. Macro Command Quick Reference

This appendix provides a list of all the commands, functions, operators, and other vocabulary of the Macro Programming Dialect, and also some of the important commands from the Menu Command Dialect. It is intended as a “quick reference,” which is to say that it’s complete but not terribly detailed. If you’d like a more thorough explanation of any of these commands, or additional examples of their use, please consult manual included with Nisus Writer.

The Menu Command Dialect

Every command that appears on a menu can be used on a line by itself in a macro. When the macro gets to that line, it will execute the menu command named there. Any menu command can be used this way, including menu items you add yourself to the Macros, Glossary, Jump To, File Access, Style, or ruler name menus. In addition to this normal use, some menu commands take arguments (see Chapter 12) which further specify how they behave. And there are a few commands in the 530 Menu Command Dialect that don’t actually appear on a menu anywhere. This section will list these unusual commands.

Menu Commands that Take Arguments

Each command is listed with its optional arguments. Arguments are evaluated from left to right, so if you leave out one or more arguments, it will be assumed that the missing ones would have been rightmost in the expression, and default values will be used for them. To see what the possible values are for each argument, see Chapter 12. Find/Replace options are also listed in Appendix B.

Copy "ToClipboard#" "Text" (if preceded by “Shift key” character, becomes Append Copy)
Cut "ToClipboard#" (if preceded by “shift key” character, becomes Append Cut)
Find/Replace "Find Pattern" "Replace Pattern" "options" "windows"
Find Next "Find Pattern" "options" "windows"
Find All "Find Pattern" "options" "windows"
Find in Selection "Find Pattern" "options"
Replace With "Replace Pattern" "options" "windows"
Replace All "Find Pattern" "Replace Pattern" "options" "windows"
Replace in Selection "Find Pattern" "Replace Pattern" "options"
New "Pathname:Filename" "Pathname:StationeryName" or New ":Foldername:Filename"
Open "Pathname:Filename" "option" or Open "Filename" "option" or Open ":Foldername" "option"
options are A (add to search list), R (remove from search list), C (change to this folder)
Paste "FromClipboard#" "Text" (if preceded by “Shift key” character, becomes Swap Paste
531 Quit "ApplictionToTransferTo" (must be preceded by “Shift key” character)
Save As "Filename" or Save As "Pathname:Filename"
Show Catalog "Pathname:Filename" "option" or Show Catalog "Filename" "option" or Show Catalog ":Foldername" "option"
options are A (add to search list), R (remove from search list), C (change to this folder)

On/Off as Arguments

The following menu commands can take "on" or "off" as an argument, corresponding to the presence or absence of a checkmark next to that command on the menu.

532 Other Menu Command Dialect Items

beep

Plays the currently-selected System alert sound.

:1 "Message"

Displays a dialog box containing the message indicated and an OK button to dismiss it.

:1 "Message" ""

As above, but includes text entry box. Response is placed on the current Clipboard.

:1 "Message" "DefaultAnswer"

As above, but pre-enters a default answer in the text entry box.

Key

“Types” the keystroke(s) indicated after the word Key. The word Key must always be followed by a space. If no other characters follow the space, a return will be inserted.

Click x,y

Performs a mouse click at the given coordinates, measured in pixels from the top left corner of the active window.

533 Programming Dialect Commands

The terms listed below are of several types. The type of term determines how and where it can be used, and what result it will produce. Here are the types and their meanings.

Command: A statement that can appear on a line by itself and perform a specific activity.
Function: A statement that takes some input, processes it, and gives some output as a result.
Operator: A method by which two variables are to interact.
Property Keyword: A word, placed in brackets, that refers to a property of the preceding object.
Variable: A name given to a container whose contents can change.

Many of the functions here take variables as arguments. The type of variable required is indicated in the listing by one of the following letters:

For example, the command length(S) requires a string argument, as in length(Mississippi), while the command qpush(I) requires an integer argument, as in qpush(9). An Expression can be any type of variable or a math or logic statement.

534 Operators

The following symbols and words are used as logical or mathematical operators in macro statements:

Operator

Name

Example

Returns

Notes

!

Not

If(!error) GoTo test
!=

Not equal

x=5<>4

TRUE

same as <>

&&

logical AND

If(a>1 && b<3) exit

same as AND

->

method

s->qpush(3)
<

less than

x=3<2

FALSE

<=

less than or equal

x=4<=4

TRUE

>

greater than

x=3>2

TRUE

>=

greater than or equal

x=5>=6

FALSE

<>

not equal

x=5<>4

TRUE

same as !=

=

set equal to

var="Surf's up!"
==

equals

If(x==3) exit
||

OR

If(x>4 || y<6) exit

same as OR

AND

logical AND

If(a>1 AND b<3) exit

same as &&

OR

OR

If(x>4 OR y<6) exit

same as ||

Not

Not

If(Not error) Goto test

same as !

true true If((x>5)==true) GoTo calc
false

false

If((y<5)==false) exit

535 Variables and Variable Commands

NOTE: All variable names, including predefined variables, are case-sensitive.

clipboard

A string variable containing the contents of the current clipboard
Ex.: clipboard="Save the Planet"

DoubleLock

Boolean variable. If set to TRUE, converts every constant number to a floating-point number. Defaults to FALSE. Ex.: DoubleLock=TRUE. Thereafter, the integer 5 will be converted to 5.0.

free VarName

Deletes the first instance of the variable VarName. First checks local variable space then global space. Ex.: free Willy

FreeAll

Deletes all local and global variables.

FreeGlobal

Deletes all global variables.

FreeLocal

Deletes all local variables.

global VarName

Declares a global variable. Ex.: global warming

local VarName

Declares a local variable. Ex.: local PhoneCall

type

Returns a string indicating the type of a variable.
Ex.: Jerry = 9.5; clipboard = Jerry->type would place the word DOUBLE on the clipboard.

UpdateVariables()

Variable recounting command. See Chapter 15 for usage example.

The following two data format variables can be set equal to a string specifying justification, field size, number of digits, and so on. Consult your Nisus Writer manual for complete details.

DOUBLE

Specifies format of floating-point numbers. Ex.: DOUBLE="%8.3lG"

LONG

Specifies format of long integers. Ex.: LONG="%-5ld"

536 Storage Methods and Storage Variables

To create or append a storage variable (which can be treated as a stack or queue), use one of the following storage methods:

create(I)

Creates a storage variable containing I empty elements. If the variable already exists, I empty elements are appended to its beginning (the “stack” method). Ex.: Pat=create(42)

qcreate(I)

Creates a storage variable containing I empty elements. If the variable already exists, I empty elements are appended to its end (the “queue” method). Ex.: Glenn=qcreate(18)

push(E)

Creates a storage variable with contents E. If the variable already exists, the value of E is appended to its beginning (the “stack” method). Ex.: Kerry->push("I'm a string")

qpush(E)

Creates a storage variable with contents E. If the variable already exists, the value of E is appended to its end (the “queue” method). Ex.: Jean->qpush(99.9)

To retrieve an element from a storage variable, use one of these storage methods:

pop

Removes the first element from a storage variable (the “stack” method), and passes the result to the variable associated with it. Ex.: clipboard=Mel->pop

first

Returns the value of the first element in a storage variable without removing it from the stack or queue. Ex.: clipboard=Dana->first

last

Returns the value of the last element in a storage variable without removing it from the stack or queue. Ex.: clipboard=Alice->last

537 The following terms are used as keyword operators of push or qpush. They place information about the current selection(s) into a storage variable.

Operator

Data placed in storage variable

starts

Start points of the current selection(s). Ex.: Chris=push(starts)

ends

End points of the current selection(s). Ex.: Sam=qpush(ends)

StartEnds

Start and end points of the current selection(s). Ex.: Marty=push(StartEnds)

floats

Value of each selection as a floating point number in a separate element of a storage variable. Ex.: Fran->qpush(floats)

ints

Value of each selection as an integer in a separate element of a storage variable.
Ex.: Hilary->push(ints)

strings

Value of each selection as a string in a separate element of a storage variable.
Ex.: Al->push(strings)

Other storage variable terms:

error

Boolean variable representing the error state of the last storage variable operation. If an error has occurred, has a value of TRUE. Ex.: If(Carol->error) GoTo Problem

shuffle

Randomly rearranges elements in a storage variable. Ex.: Stevie->shuffle

538 size

Returns the number of elements in a storage variable. Ex.: clipboard=Kelly->size

swap(I1, I2)

Swaps the contents of elements I1 and I2 in a storage variable. Ex.: Cy->swap(3,5)

String Functions

In the following functions, S can be either a string or a variable whose value is a string.

left(S, I)

Returns the leftmost I characters in string S. Ex.: clipboard=left("Coffee",3)

right(S, I)

Returns the rightmost I characters in string S. Ex.: clipboard=right("Tea",2)

mid(S, I1, I2)

Returns I2 characters from the middle of string S, beginning with character I1.
Ex.: clipboard=mid("Milk",2,3)

CharToNum(S)

Returns an integer representing the decimal ASCII value of the first character of string S.
Ex.: clipboard=CharToNum("Beer") (places 66 on the clipboard)

NumToChar(I)

Returns a string containing the character corresponding to ASCII number I.
Ex.: clipboard=NumToChar(80) (places P on the clipboard)

length(S) Returns the number of characters in string S. Ex.: clipboard=length(beverage)
offset(S1, S2)

Returns the character number representing the beginning of the first occurrence of S1 within S2.
Ex.: clipboard=offset("on", "Lemonade") (places 4 on the clipboard)

539 LowerRoman(I)

Returns a string that is the lowercase Roman numeral equivalent of I.
Ex.: clipboard=LowerRoman(5) (puts v on the clipboard)

UpperRoman(I)

Returns a string that is the uppercase Roman numeral equivalent of I.
Ex.: clipboard=UpperRoman(5) (puts V on the clipboard)

The following clipboard strings are normally placed inside single quotes so that they are not taken literally:

\CC

Contents of current clipboard. Use when a string, rather than a variable, is needed.

\C0\C9

Contents of clipboard 0 through 9

To determine which clipboard is currently active, use this property keyword:

CurrentClipboardNum

Number of currently active clipboard.
Ex.: ClipNum=Nisus[CurrentClipboardNumber]

Date and Time

Function

returns

date

Current date/time

day

Current day of month (an integer from 1 through 31)

DayOfWeek

Current day of week (a string, like "Thursday")

hour

Current hour of day (an integer 0 through 23)

MakeDate(I1, I2, I3)

Creates a “date/time” variable based on day I1, month I2, and year I3

540 minute

Current minute (an integer from 0 through 59)

month

Current month (an integer from 1 through 12)

OneMonth

The length of a month. The exact value of this data offset (which can be used like a variable) depends on the context in which it is used—such as adding or subtracting months, or portions thereof, from other dates.
Ex.: NextMeeting=date+OneMonth

OneYear

The length of a year. Usage is the same as OneMonth.

RoundDownMonth(D)

Returns a date such that the day of the month is “rounded down” to the last possible date. Used to fix impossible dates like February 30, April 39.

second

Current second (an integer from 0 through 59)

time

Current time

WhatDay(D)

Returns a number from 1 to 7, representing the day of week indicated by D (based on Sunday as the first day of the week)

year

Current year (possible values 1904–2040)

Document Functions

The following document functions are used to assign values to variables. Ex.: var=DocPath

541 Function

Returns

CharNum

Number of characters from beginning of document to insertion point

DateCreated

Creation date of current file or (if in Catalog) selected file or folder

DocName

Frontmost document’s name

DocPath

Frontmost document’s complete pathname

EndCharNum

Number of characters in entire document

LastDateSaved

Modification date of the frontmost document

LineCharNum

Number of characters from start of current line to insertion point

LineNum

Line number (from beginning of document) where insertion point is located

NextRulerStart

Number of characters from beginning of the document to the next ruler following the insertion point

PageLineNum

Line number (from top of current page) where insertion point is located

PageNum

Number of the page where the insertion point is located

RulerName

Name of the ruler (if named) governing the paragraph that contains the insertion point

RulerStart

Number of characters from beginning of the document to the ruler governing the paragraph containing the insertion point

SelectEnd

Number of characters from beginning of document to last character of last selection

SelectStart

Number of characters from beginning of document to first character of last selection

TimeModified

Modification time of the frontmost document


542 The next four terms are used to select text in your document

SelectRuler(I)

Counts I characters from the beginning of the document and selects the ruler governing the paragraph that contains that character

SetSelect(I1, I2)

Selects the text in your document between character offsets I1 and I2. If the two values are identical, it will move the insertion point to the position right after character I.

SetSelectMore(I1, I2)

Noncontiguous selection function. Just like SetSelect, but you must always use at least two consecutive SetSelectMore statements or nothing will be selected.

SelectWithRuler

Boolean variable. Set it to TRUE, and any following SetSelect or SetSelectMore commands will also select a ruler that immediately precedes the selection.

Window Functions

A number of property keywords make reference to a particular window in Nisus Writer. Since they are properties, there must be something for them to be properties of. That something is Nisus:

Nisus A “dummy” command that serves as a hitching post for several property keywords (such as windows and sounds). Ex.: Nisus[FrontWindow]->SendWindowBack()

Each of these keywords must be placed immediately after something it can logically be a property of. If the keyword is a window, it is placed after Nisus.

543 But if the keyword refers to something in a window, it must follow a window keyword.

property keyword

refers to

FrontDocumentWindow

Frontmost document window

FrontWindow

Frontmost window (of any type)

HeaderFooterIconDisplayState

Whether header/footer icons are visible in the document window

MicroRulerIconoDisplayState

Whether ruler icons are visible in the document window

NeedsSaveAs

Whether a document has ever been saved

WindowRect

Coordinates of a window’s boundaries, measured in pixels from top left corner of screen. Used in conjunction with four other keywords (RectBottom, RectLeft, RectRight, RectTop) as shown:
WinSize=Nisus[FrontWindow][WindowRect]
WinSize[RectLeft]=0; WinSize[RectRight]=300
WinSize[RectTop]=30; WinSize[RectBottom]=200
Nisus[FrontWindow][WindowRect]=WinSize

The following window procedures are methods that must be applied to variables representing specific windows. For example:

BringWindowFront()

Brings a window to the front.

SendWindowBack()

Sends a window to the back.

544 Sound Functions

Sound keywords, like window keywords, must appear to the right of something of which they can be properties. CanRecord and CanSpeak are properties of Nisus Writer. Ex.: If(Nisus[CanRecord]) GoTo RecordIt

Sound group keywords are properties of specific windows, while sound names and sound group names are properties of sound groups, so you may have to string several together to get the desired effect.

property keyword

refers to
CanRecord

Whether Nisus Writer is currently able to record sounds

CanSpeak

Whether Nisus Writer is currently able to speak sounds

CurrentSoundGroup

Current sound group

DefaultSoundGroup

Default sound group

FollowingMacro

Causes calling of next macro to wait until any sounds or movies currently playing have finished. Ex.: Nisus[FollowingMacro] = "Speak Again"

LastRecordedSound

Last sound recorded in current session

SoundGroupName

Name of current sound group (used after CurrentSoundGroup, for example)

545 OffsetTime

A global data offset used to trick PlayTimedSoundStack into thinking the time is different. Ex.: global OffsetTime; OffsetTime=time+15

PauseSoundStack

Boolean variable. If TRUE, stops currently playing PlaySoundStack.

PauseTimedSoundStack

Boolean variable. If TRUE, stops currently playing PlayTimedSoundStack.

PlaySoundStack

Global storage variable. Plays a sound.
Ex.: PlaySoundStack->push(MyTone)

PlayTimedSoundStack

Global storage variable. Plays a sound at a specified time.
Ex.: MyTone[SoundPlayTime]=time+10; PlayTimedSoundStack->push(MyTone)

SndFileName

A property of a variable, used to assign the pathname of a sound file to that variable. Ex.: tone[SndFileName]="Mac HD:folder:MySound"

SoundName

Name of current sound (property of sound or sound group)

SoundPlayTime

Time at which PlayTimedSoundStack will play a sound

546 SoundRandomTime

A time limit such that a sound will play at some random time before it expires. If 0, sound will play only once. Requires SoundRepeatAgainAfter to be set to 0.

SoundRepeatAgainAfter

Amount of time between each repetition of a sound. If set to 0, time will be determined by SoundRandomTime.

SoundNumberOfRepeats

Number of times a sound will repeat after initial playback (defaults to 0)

SndResourceName

Loads a sound resource by name (if it has already been opened either by SndFileName or by another application).
Ex.: tone[SndResourcename]="bell"

Other Macro Terms

//

Comment. Everything after the // on a line is ignored by the macro.

error

Error function. Returns a Boolean value of TRUE if the last command produced an error state; FALSE by default.

eval

Evaluate As Macro function. Evaluates the expression that follows it (normally in single quotes) then executes it as a macro command. Ex.: eval 'var=\CC'

547 exit

Stops the current macro and returns control to the macro that called it, if any.

GoTo label

Jumps to the line following the label indicated. Ex.: GoTo Egypt

if(E)

Conditional test. Evaluates expression E, and if the result is TRUE, executes any statement(s) following this command on the same line. Ex.: If(4<5) GoTo Texas

label:

Any line containing just one word followed by a colon is considered a label. This serves as a marker for the GoTo command.

NumFound

Function (not a variable) which returns number of items found (or replaced) by a Find/Replace command. Ex.: Find All "cows" … clipboard=NumFound

ReportErrors

Boolean variable. If FALSE, syntax warning dialog box will not appear in case of an error. Defaults to TRUE.

stop

Stops the current macro and any other macro(s) that may have called it.

The following two commands can be used to copy and paste within Programming Dialect lines.

MacroCopy

Like Copy except no style or formatting information is copied, and it’s much faster.

MacroPaste

Like Paste except no style or formatting information is pasted, and it’s much faster.

548 Math and Trigonometry

operator

Name

Example

Returns

Notes

%

modulus

12 % 5

2

same as mod

*

multiplication

2 * 3

6

+

addition

5 + 2

7

math or strings

ab + c

abc

-

subtraction

5 - 2

3

math or strings

abc - b

ac

/

division

9 / 3

3

math or strings

abcabc / a

bcbc

^

exponentiation

2 ^ 3

8

same as pow

square root

9

3

same as sqrt

div

integer division

12 div 5

2

complements mod

mod

modulus

12 % 5

2

complements div

549 Math Function

Name

Example

Returns

Notes

ceil(F)

ceiling

ceil(8.5)

9

complements floor

exp(F)

base of natural log exponentiation

exp(1)

2.71828

base of natural logs to the F power

fabs(F)

absolute value

fabs(-7)

7

floor(F)

floor

floor(12.5)

12

complements ceil

fmod(F1, F2)

floating modulus

fmod(12,-5)

2

log(F)

natural logarithm

log(8)

2.07944

F>0

log10(F)

logarithm base 10

log10(8)

0.90309

F>0

modf(F)

fractional modulus

modf(-1.234)

-0.234

pow(F1, F2)

exponentiation

pow(2, 3)

8

same as ^

random

random number

x=random

an integer from –32,767 through 32,767

x=random%10

an integer from 0 through 10

rrandom(F1, F2)

random number with range

x=rrandom(1.3,8.2)

a number from

floating point result 1.3 through 8.2

seed(I)

seed

seed(7)

1

sqrt(F)

square root

sqrt(9)

3

same as

Note:
1The seed function sets the starting seed value of the random function to I. The effect is that for any given value of I, every series of random numbers generated will be the same.

550 Trig Function

Name

Example

Returns

Notes

acos(F)

arc cosine

acos(0)

1.5708

asin(F)

arc sine

asin(1)

1.5708

atan(F)

arc tangent

atan(1)

0.785398

atan2(F1, F2)

arc tangent w/range

atan2(10,20)

0.463648

arc tangent of F1 divided by F2

cos(F)

cosine

cos(-1)

0.540302

cosh(F)

hyperbolic cosine

cosh(-1)

1.54308

sin(F)

sine

sin(45)

0.850904

sinh(F)

hyperbolic sine

sinh(45)

1.74671E+19

tan(F)

tangent

tan(1)

1.55741

tanh(F)

hyperbolic tangent

tanh(1)

0.761594

Copyright © 1995, 1996, 1999 by Joe Kissell

< Appendix B | Appendix D >