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