How it Works
autocad
Loading...
#
M
Loading...
Loading...
2013
Customization Guide
194 pgs1.02 Mb0
Developers Guide
178 pgs1.23 Mb0
Installation Guide
12 pgs176.37 Kb0
Manuel d’installation
14 pgs200.62 Kb0
Manuel d’utilisation
940 pgs16.52 Mb0
Reference Guide
298 pgs1.35 Mb0
Reference Guide
1636 pgs17.02 Mb0
User Guide
872 pgs16.54 Mb0
User Manual
210 pgs1.07 Mb0
User Manual
13 pgs470.36 Kb0
Table of contents
Loading...

autocad 2013 Reference Guide

Download
AutoCAD 2013
AutoLISP Reference Guide
January 2012
©
2012 Autodesk, Inc. All Rights Reserved. Except as otherwise permitted by Autodesk, Inc., this publication, or parts thereof, may not
be reproduced in any form, by any method, for any purpose.
Certain materials included in this publication are reprinted with the permission of the copyright holder.
Trademarks
All other brand names, product names or trademarks belong to their respective holders.
Disclaimer
THIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY AUTODESK, INC. "AS IS." AUTODESK, INC. DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS.

Contents

Chapter 1 AutoLISP Functions . . . . . . . . . . . . . . . . . . . . . . . . . 1
AutoLISP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
+ (add) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
- (subtract) . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
* (multiply) . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
/ (divide) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
= (equal to) . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
/= (not equal to) . . . . . . . . . . . . . . . . . . . . . . . . 6
< (less than) . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
<= (less than or equal to) . . . . . . . . . . . . . . . . . . . . 8
> (greater than) . . . . . . . . . . . . . . . . . . . . . . . . . 9
>= (greater than or equal to) . . . . . . . . . . . . . . . . . . 9
~ (bitwise NOT) . . . . . . . . . . . . . . . . . . . . . . . . 10
1+ (increment) . . . . . . . . . . . . . . . . . . . . . . . . 11
1- (decrement) . . . . . . . . . . . . . . . . . . . . . . . . . 12
A Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
acad-pop-dbmod . . . . . . . . . . . . . . . . . . . . . . . 13
acad-push-dbmod . . . . . . . . . . . . . . . . . . . . . . . 13
acad_strlsort . . . . . . . . . . . . . . . . . . . . . . . . . . 14
acad_truecolorcli . . . . . . . . . . . . . . . . . . . . . . . 15
acad_truecolordlg . . . . . . . . . . . . . . . . . . . . . . . 16
acdimenableupdate . . . . . . . . . . . . . . . . . . . . . . 17
iii
acet-layerp-mode . . . . . . . . . . . . . . . . . . . . . . . 18
acet-layerp-mark . . . . . . . . . . . . . . . . . . . . . . . 19
alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
angle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
angtof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
angtos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
append . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
arx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
arxload . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
arxunload . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
ascii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
assoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
atan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
atof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
atoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
atom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
atoms-family . . . . . . . . . . . . . . . . . . . . . . . . . 33
autoarxload . . . . . . . . . . . . . . . . . . . . . . . . . . 33
autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
B Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Boole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
boundp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
C Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
caddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
cadr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
car . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
cdr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
chr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
command . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
command-s . . . . . . . . . . . . . . . . . . . . . . . . . . 43
cond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
cons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
cvunit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
D Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
defun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
defun-q . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
defun-q-list-ref . . . . . . . . . . . . . . . . . . . . . . . . 54
defun-q-list-set . . . . . . . . . . . . . . . . . . . . . . . . 55
dictadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
dictnext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
dictremove . . . . . . . . . . . . . . . . . . . . . . . . . . 59
iv | Contents
dictrename . . . . . . . . . . . . . . . . . . . . . . . . . . 60
dictsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
distof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
dumpallproperties . . . . . . . . . . . . . . . . . . . . . . . 64
E Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
entdel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
entget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
entlast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
entmake . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
entmakex . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
entmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
entnext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
entsel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
entupd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
eq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
*error* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
expt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
F Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
findfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
foreach . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
G Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
gc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
gcd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
getangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
getcfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
getcname . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
getcorner . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
getdist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
getenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
getfiled . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
getint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
getkword . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
getorient . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
getpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
getpropertyvalue . . . . . . . . . . . . . . . . . . . . . . . 103
getreal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
getstring . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Contents | v
getvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
graphscr . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
grclear . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
grdraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
grread . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
grtext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
grvecs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
H Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
handent . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
I Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
initcommandversion . . . . . . . . . . . . . . . . . . . . 116
initdia . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
initget . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
ispropertyreadonly . . . . . . . . . . . . . . . . . . . . . . 123
inters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
itoa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
L Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
layoutlist . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
layerstate-addlayers . . . . . . . . . . . . . . . . . . . . . 128
layerstate-compare . . . . . . . . . . . . . . . . . . . . . . 129
layerstate-delete . . . . . . . . . . . . . . . . . . . . . . . 130
layerstate-export . . . . . . . . . . . . . . . . . . . . . . . 130
layerstate-getlastrestored . . . . . . . . . . . . . . . . . . . 131
layerstate-getlayers . . . . . . . . . . . . . . . . . . . . . . 131
layerstate-getnames . . . . . . . . . . . . . . . . . . . . . 132
layerstate-has . . . . . . . . . . . . . . . . . . . . . . . . . 132
layerstate-import . . . . . . . . . . . . . . . . . . . . . . . 133
layerstate-importfromdb . . . . . . . . . . . . . . . . . . . 133
layerstate-removelayers . . . . . . . . . . . . . . . . . . . 134
layerstate-rename . . . . . . . . . . . . . . . . . . . . . . 134
layerstate-restore . . . . . . . . . . . . . . . . . . . . . . . 135
layerstate-save . . . . . . . . . . . . . . . . . . . . . . . . 135
length . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
listp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
logand . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
logior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
lsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
M Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
mapcar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
vi | Contents
mem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
member . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
menucmd . . . . . . . . . . . . . . . . . . . . . . . . . . 147
min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
minusp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
N Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
namedobjdict . . . . . . . . . . . . . . . . . . . . . . . . 149
nentsel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
nentselp . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
nth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
numberp . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
O Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
osnap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
P Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
polar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
prin1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
princ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
progn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Q Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
quote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
R Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
read-char . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
read-line . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
regapp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
rem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
rtos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
S Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
setcfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
setenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
setpropertyvalue . . . . . . . . . . . . . . . . . . . . . . . 175
setq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
setvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
setview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Contents | vii
snvalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
ssadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
ssdel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
ssget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
ssgetfirst . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
sslength . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
ssmemb . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
ssname . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
ssnamex . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
sssetfirst . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
startapp . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
strcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
strcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
strlen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
subst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
T Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
tblnext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
tblobjname . . . . . . . . . . . . . . . . . . . . . . . . . . 203
tblsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
terpri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
textbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
textpage . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
textscr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
trans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
U Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
untrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
V Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
ver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
vl-acad-defun . . . . . . . . . . . . . . . . . . . . . . . . 214
vl-acad-undefun . . . . . . . . . . . . . . . . . . . . . . . 215
vl-bb-ref . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
vl-bb-set . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
vl-catch-all-apply . . . . . . . . . . . . . . . . . . . . . . 216
vl-catch-all-error-message . . . . . . . . . . . . . . . . . . 218
vl-catch-all-error-p . . . . . . . . . . . . . . . . . . . . . . 219
vl-cmdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
vl-consp . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
vl-directory-files . . . . . . . . . . . . . . . . . . . . . . . 222
vl-doc-ref . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
vl-doc-set . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
vl-every . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
vl-exit-with-error . . . . . . . . . . . . . . . . . . . . . . . 226
viii | Contents
vl-exit-with-value . . . . . . . . . . . . . . . . . . . . . . 227
vl-file-copy . . . . . . . . . . . . . . . . . . . . . . . . . . 227
vl-file-delete . . . . . . . . . . . . . . . . . . . . . . . . . 229
vl-file-directory-p . . . . . . . . . . . . . . . . . . . . . . 229
vl-file-rename . . . . . . . . . . . . . . . . . . . . . . . . 230
vl-file-size . . . . . . . . . . . . . . . . . . . . . . . . . . 231
vl-file-systime . . . . . . . . . . . . . . . . . . . . . . . . 231
vl-filename-base . . . . . . . . . . . . . . . . . . . . . . . 232
vl-filename-directory . . . . . . . . . . . . . . . . . . . . 233
vl-filename-extension . . . . . . . . . . . . . . . . . . . . 234
vl-filename-mktemp . . . . . . . . . . . . . . . . . . . . . 234
vl-list* . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
vl-list->string . . . . . . . . . . . . . . . . . . . . . . . . . 237
vl-list-length . . . . . . . . . . . . . . . . . . . . . . . . . 237
vl-load-all . . . . . . . . . . . . . . . . . . . . . . . . . . 238
vl-mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
vl-member-if . . . . . . . . . . . . . . . . . . . . . . . . . 239
vl-member-if-not . . . . . . . . . . . . . . . . . . . . . . . 240
vl-position . . . . . . . . . . . . . . . . . . . . . . . . . . 241
vl-prin1-to-string . . . . . . . . . . . . . . . . . . . . . . . 242
vl-princ-to-string . . . . . . . . . . . . . . . . . . . . . . . 243
vl-propagate . . . . . . . . . . . . . . . . . . . . . . . . . 243
vl-registry-delete . . . . . . . . . . . . . . . . . . . . . . . 244
vl-registry-descendents . . . . . . . . . . . . . . . . . . . 245
vl-registry-read . . . . . . . . . . . . . . . . . . . . . . . . 246
vl-registry-write . . . . . . . . . . . . . . . . . . . . . . . 246
vl-remove . . . . . . . . . . . . . . . . . . . . . . . . . . 247
vl-remove-if . . . . . . . . . . . . . . . . . . . . . . . . . 248
vl-remove-if-not . . . . . . . . . . . . . . . . . . . . . . . 249
vl-some . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
vl-sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
vl-sort-i . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
vl-string->list . . . . . . . . . . . . . . . . . . . . . . . . . 253
vl-string-elt . . . . . . . . . . . . . . . . . . . . . . . . . . 254
vl-string-left-trim . . . . . . . . . . . . . . . . . . . . . . 254
vl-string-mismatch . . . . . . . . . . . . . . . . . . . . . . 255
vl-string-position . . . . . . . . . . . . . . . . . . . . . . 256
vl-string-right-trim . . . . . . . . . . . . . . . . . . . . . . 257
vl-string-search . . . . . . . . . . . . . . . . . . . . . . . . 258
vl-string-subst . . . . . . . . . . . . . . . . . . . . . . . . 258
vl-string-translate . . . . . . . . . . . . . . . . . . . . . . 260
vl-string-trim . . . . . . . . . . . . . . . . . . . . . . . . . 260
vl-symbol-name . . . . . . . . . . . . . . . . . . . . . . . 261
vl-symbol-value . . . . . . . . . . . . . . . . . . . . . . . 262
vl-symbolp . . . . . . . . . . . . . . . . . . . . . . . . . . 262
vports . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Contents | ix
W Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
wcmatch . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
while . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
write-char . . . . . . . . . . . . . . . . . . . . . . . . . . 268
write-line . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
X Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
xdroom . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
xdsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Z Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
zerop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Chapter 2 Externally Defined Commands . . . . . . . . . . . . . . . . . 273
Externally Defined Commands . . . . . . . . . . . . . . . . . . . . . 273
align . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
cal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
mirror3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
rotate3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
solprof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
x | Contents

AutoLISP Functions

AutoLISP Functions

The following is a catalog of the AutoLISP® functions available in AutoCAD®. The functions are listed alphabetically.
In this chapter, each listing contains a brief description of the function's use and a function syntax statement showing the order and the type of arguments required by the function.
Note that any functions, variables, or features not described here or in other parts of the documentation are not officially supported and are subject to change in future releases.
For information on syntax, see AutoLISP Function Syntax in the AutoLISP Developer's Guide.
1
Note that the value returned by some functions is categorized as unspecified. This indicates you cannot rely on using the value returned from this function.

Operators

+ (add)
Returns the sum of all numbers.
(+
[number number]
...)
1
Arguments
number A number.
Return Values
The result of the addition. If you supply only one number argument, this function returns the result of adding it to zero. If you supply no arguments, the function returns 0.
Examples
(+ 1 2)
returns
3
(+ 1 2 3 4.5)
returns
10.5
(+ 1 2 3 4.0)
returns
10.0
- (subtract)
Subtracts the second and following numbers from the first and returns the difference
(-
[number number]
...)
Arguments
number A number.
Return Values
The result of the subtraction. If you supply more than two number arguments, this function returns the result of subtracting the sum of the second through the last numbers from the first number. If you supply only one number argument, this function subtracts the number from zero, and returns a negative number. Supplying no arguments returns 0.
Examples
2 | Chapter 1 AutoLISP Functions
(- 50 40)
returns
10
(- 50 40.0)
returns
10.0
(- 50 40.0 2.5)
returns
7.5
(- 8)
returns
-8
* (multiply)
Returns the product of all numbers
(*
[number number]
...)
Arguments
number A number.
Return Values
The result of the multiplication. If you supply only one number argument, this function returns the result of multiplying it by one; it returns the number. Supplying no arguments returns 0.
Examples
(* 2 3)
returns
6
(* 2 3.0)
returns
6.0
(* 2 3 4.0)
AutoLISP Functions | 3
returns
24.0
(* 3 -4.5)
returns
-13.5
(* 3)
returns
3
/ (divide)
Divides the first number by the product of the remaining numbers and returns the quotient
(/
[number number]
...)
Arguments
number A number.
Return Values
The result of the division. If you supply more than two number arguments, this function divides the first number by the product of the second through the last numbers, and returns the final quotient. If you supply one number argument, this function returns the result of dividing it by one; it returns the number. Supplying no arguments returns 0.
Examples
(/ 100 2)
returns
50
(/ 100 2.0)
returns
50.0
(/ 100 20.0 2)
returns
4 | Chapter 1 AutoLISP Functions
2.5
(/ 100 20 2)
returns
2
(/ 4)
returns
4
= (equal to)
Compares arguments for numerical equality
(=
numstr [numstr]
...)
Arguments
numstr A number or a string.
Return Values
T, if all arguments are numerically equal; otherwise nil . If only one argument
is supplied, = returns T.
Examples
(= 4 4.0)
returns
T
(= 20 388)
returns
nil
(= 2.4 2.4 2.4)
returns
T
(= 499 499 500)
returns
nil
(= "me" "me")
returns
AutoLISP Functions | 5
T
(= "me" "you")
returns
nil
See also:
The eq (page 80) and equal (page 81) functions.
/= (not equal to)
Compares arguments for numerical inequality
(/=
numstr [numstr]
...)
Arguments
numstr A number or a string.
Return Values
T, if no two successive arguments are the same in value; otherwise nil. If only
one argument is supplied, /= returns T.
Note that the behavior of /= does not quite conform to other LISP dialects. The standard behavior is to return T if no two arguments in the list have the same value. In AutoLISP, /= returns T if no successive arguments have the same value; see the examples that follow.
Examples
(/= 10 20)
returns
T
(/= "you" "you")
returns
nil
(/= 5.43 5.44)
returns
6 | Chapter 1 AutoLISP Functions
T
(/= 10 20 10 20 20)
returns
nil
(/= 10 20 10 20)
returns
T
NOTE In the last example, although there are two arguments in the list with the same value, they do not follow one another; thus /= evaluates to T.
< (less than)
Returns T if each argument is numerically less than the argument to its right; otherwise nil
(<
numstr [numstr]
...)
Arguments
numstr A number or a string.
Return Values
T, if each argument is numerically less than the argument to its right; otherwise
returns nil . If only one argument is supplied, < returns T.
Examples
(< 10 20)
returns
T
(< "b" "c")
returns
T
(< 357 33.2)
returns
nil
(< 2 3 88)
AutoLISP Functions | 7
returns
T
(< 2 3 4 4)
returns
nil
<= (less than or equal to)
Returns T if each argument is numerically less than or equal to the argument to its right; otherwise returns nil
(<=
numstr [numstr]
...)
Arguments
numstr A number or a string.
Return Values
T, if each argument is numerically less than or equal to the argument to its
right; otherwise returns nil. If only one argument is supplied, <= returns T.
Examples
(<= 10 20)
returns
T
(<= "b" "b")
returns
T
(<= 357 33.2)
returns
nil
(<= 2 9 9)
returns
T
(<= 2 9 4 5)
returns
nil
8 | Chapter 1 AutoLISP Functions
> (greater than)
Returns T if each argument is numerically greater than the argument to its right; otherwise returns nil
(>
numstr [numstr]
...)
Arguments
numstr A number or a string.
Return Values
T, if each argument is numerically greater than the argument to its right;
otherwise nil. If only one argument is supplied, > returns T.
Examples
(> 120 17)
returns
T
(> "c" "b")
returns
T
(> 3.5 1792)
returns
nil
(> 77 4 2)
returns
T
(> 77 4 4)
returns
nil
>= (greater than or equal to)
Returns T if each argument is numerically greater than or equal to the argument to its right; otherwise returns nil
AutoLISP Functions | 9
(>=
numstr [numstr]
...)
Arguments
numstr A number or a string.
Return Values
T, if each argument is numerically greater than or equal to the argument to
its right; otherwise nil. If only one argument is supplied, >= returns T.
Examples
(>= 120 17)
returns
T
(>= "c" "c")
returns
T
(>= 3.5 1792)
returns
nil
(>= 77 4 4)
returns
T
(>= 77 4 9)
returns
nil
~ (bitwise NOT)
Returns the bitwise NOT (1's complement) of the argument
(~
int
)
Arguments
10 | Chapter 1 AutoLISP Functions
int An integer.
Return Values
The bitwise NOT (1's complement) of the argument.
Examples
(~ 3)
returns
-4
(~ 100)
returns
-101
(~ -4)
returns
3
1+ (increment)
Increments a number by 1
(1+
number
)
Arguments
number Any number.
Return Values
The argument, increased by 1.
Examples
(1+ 5)
returns
6
(1+ -17.5)
returns
-16.5
AutoLISP Functions | 11
1- (decrement)
Decrements a number by 1
(1-
number
)
Arguments
number Any number.
Return Values
The argument, reduced by 1.
Examples
(1- 5)
returns
4
(1- -17.5)
returns
-18.5

A Functions

abs
Returns the absolute value of a number
(abs
number
)
Arguments
number Any number.
Return Values
12 | Chapter 1 AutoLISP Functions
The absolute value of the argument.
Examples
(abs 100)
returns
100
(abs -100)
returns
100
(abs -99.25)
returns
99.25
acad-pop-dbmod
Restores the value of the DBMOD system variable to the value that was most recently stored with acad-push-dbmod
(acad-pop-dbmod)
This function is used with acad-push-dbmod to control the DBMOD system variable. The DBMOD system variable tracks changes to a drawing and triggers save-drawing queries.
This function is implemented in acapp.arx, which is loaded by default. This function pops the current value of the DBMOD system variable off an internal stack.
Return Values
Returns T if successful; otherwise, if the stack is empty, returns nil.
acad-push-dbmod
Stores the current value of the DBMOD system variable
(acad-push-dbmod)
This function is used with acad-pop-dbmod to control the DBMOD system variable. You can use this function to change a drawing without changing
AutoLISP Functions | 13
the DBMOD system variable. The DBMOD system variable tracks changes to a drawing and triggers save-drawing queries.
This function is implemented in acapp.arx, which is loaded by default. This function pushes the current value of the DBMOD system variable onto an internal stack. To use acad-push-dbmod and acad-pop-dbmod, precede operations
with acad-push-dbmod and then use acad-pop-dbmod to restore the original value of the DBMOD system variable.
Return Values
Always returns T.
Examples
The following example shows how to store the modification status of a drawing, change the status, and then restore the original status.
(acad-push-dbmod) (setq new_line '((0 . "LINE") (100 . "AcDbEntity") (8 . "0")
(100 . "AcDbLine") (10 1.0 2.0 0.0) (11 2.0
1.0 0.0) (210 0.0 0.0 1.0)))
(entmake new_line) ; Set DBMOD to flag 1 (command "_color" "2") ; Set DBMOD to flag 4 (command "_-vports" "_SI") ; Set DBMOD to flag 8 (command "_vpoint" "0,0,1") ; Set DBMOD to flag 16 (acad-pop-dbmod) ; Set DBMOD to original value
acad_strlsort
Sorts a list of strings in alphabetical order
(acad_strlsort
list
)
Arguments
list The list of strings to be sorted.
Return Values
14 | Chapter 1 AutoLISP Functions
The list in alphabetical order. If the list is invalid or if there is not enough memory to do the sort, acad_strlsort returns nil.
Examples
Sort a list of abbreviated month names:
Command: (setq mos '("Jan" "Feb" "Mar" "Apr" "May" "Jun" "Jul" "Aug" "Sep" "Oct" "Nov" "Dec"))
("Jan" "Feb" "Mar" "Apr" "May" "Jun" "Jul" "Aug" "Sep" "Oct" "Nov" "Dec")
Command: (acad_strlsort mos) ("Apr" "Aug" "Dec" "Feb" "Jan" "Jul" "Jun" "Mar" "May" "Nov" "Oct" "Sep")
acad_truecolorcli
Prompts for colors at the command line
(acad_truecolorcli
color [allowbylayer] [alternatePrompt]
)
Arguments
color A dotted pair that describes the default color. The first element of the dotted pair must be one of the color-related DXF group codes (62, 420, or
430); for example, (62 . ColorIndex), (420 . TrueColor), or (430 .
"colorbook$colorname").
allowbylayer Omitting the allowbylayer argument or setting it to a non-nil value enables entering bylayer or byblock to set the color. If set to nil, an error results if bylayer or byblock is entered.
alternateprompt An optional prompt string. If this string is omitted, the default value is “New color”.
Return Values
When the operation is successful, the function returns a list of one or more dotted pairs (depending on the tab on which the color is selected) describing the color selected. The last dotted pair in the list indicates the color selected. The function returns nil if the user cancels the function.
Color book color If the last item in the returned list is a 430 pair, then the specified color originates from a color book. This returned list will also contain
AutoLISP Functions | 15
a 420 pair that describes the corresponding true color and a 62 pair that describes the closest matching color index value.
True color If the returned list contains a 420 pair as the last item, then a true color was specified (as “Red,Green,Blue”). The list will also contain a 62 pair that indicates the closest matching color index. No 430 pair will be present.
Color index If the last item in the list is a 62 pair, then a colorindex was chosen. No other dotted pairs will be present in the returned list.
Examples
Prompt for a color selection at the command line with a purple color index default selection and alternative text for the command prompt:
Command: (acad_truecolorcli '(62 . 215) 1 "Pick a color") New Color [Truecolor/COlorbook] <215>: ((62 . 215))
Prompt for a color selection at the command line with a yellow color index default selection, then set the color by layer:
Command: (acad_truecolorcli '(62 . 2)) New Color [Truecolor/COlorbook] <2 (yellow)>: bylayer ((62 . 256))
acad_truecolordlg
Displays the AutoCAD color selection dialog box with tabs for index color, true color, and color books
(acad_truecolordlg
color [allowbylayer] [currentlayercolor]
)
Arguments
color A dotted pair that describes the default color. The first element of the dotted pair must be one of the color-related DXF group codes (62, 420, or
430); for example, (62 . ColorIndex), (420 . TrueColor), or (430 .
"colorbook$colorname").
allowbylayer If set to nil, disables the ByLayer and ByBlock buttons. Omitting the allowbylayer argument or setting it to a non-nil value enables the ByLayer and ByBlock buttons.
16 | Chapter 1 AutoLISP Functions
currentlayercolor Optional dotted pair in the same form as color that sets the value of the bylayer/byblock color in the dialog.
Return Values
When the operation is successful, the function returns a list of one or more dotted pairs (depending on the tab on which the color is selected) describing the color selected. The last dotted pair in the list indicates the color selected. The function returns nil if the user cancels the dialog box.
Color book color If the last item in the returned list is a 430 pair, then the specified color originates from a color book. This returned list will also contain a 420 pair that describes the corresponding true color and a 62 pair that describes the closest matching color index value.
True color If the returned list contains a 420 pair as the last item, then a true color was specified (as “Red,Green,Blue”). The list will also contain a 62 pair that indicates the closest matching color index. No 430 pair will be present.
Color index If the last item in the list is a 62 pair, then a color index was chosen. No other dotted pairs will be present in the returned list.
Examples
Open the color selection dialog to the Color Index tab and accept the purple default selection:
Command: (acad_truecolordlg '(62 . 215)) ((62 . 215))
Open the color selection dialog to the True Color tab with a green default selection and with the By Layer and By Block buttons disabled:
Command: (acad_truecolordlg '(420 . 2686760) nil) ((62 . 80) (420 . 2686760))
Open the color selection dialog to the Color Books tab and accept the mustard default selection:
Command: (acad_truecolordlg '(430 . "RAL CLASSIC$RAL 1003")) ((62 . 40) (420 . 16235019) (430 . "RAL CLASSIC$RAL 1003"))
acdimenableupdate
Controls the automatic updating of associative dimensions
(acdimenableupdate nil | T)
AutoLISP Functions | 17
The acdimenableupdate function is intended for developers who are editing geometry and don't want the dimension to be updated until after the edits are complete.
Arguments
nil Associative dimensions will not update (even if the geometry is modified) until the DIMREGEN command is entered.
T Enable automatic updating of associative dimensions when the geometry is modified.
Return Values
nil
Examples
Disable the automatic update of associative dimensions in the drawing:
Command: (acdimenableupdate nil)
Enable the automatic update of associative dimensions in the drawing:
Command: (acdimenableupdate T)
acet-layerp-mode
Queries and sets the LAYERPMODE setting
(acet-layerp-mode [
status
])
Arguments
status Specifying T turns LAYERPMODE on, enabling layer-change tracking.
Nil turns LAYERPMODE off.
If this argument is not present, acet-layerp-mode returns the current status of LAYERPMODE.
Return Values
T if current status of LAYERPMODE is on; nil if LAYERPMODE is off.
Examples
Check the current status of LAYERPMODE:
Command: (acet-layerp-mode)
18 | Chapter 1 AutoLISP Functions
T
Turn LAYERPMODE off:
Command: (acet-layerp-mode nil) nil
Check the current status of LAYERPMODE:
Command: (acet-layerp-mode) nil
See also:
The LAYERP and LAYERPMODE commands in the Command Reference.
acet-layerp-mark
Places beginning and ending marks for Layer Previous recording
(acet-layerp-mark [
status
])
The acet-layerp-mark function allows you to group multiple layer commands into a single transaction so that they can be undone by issuing LAYERP a single time. LAYERPMODE must be on in order to set marks.
Arguments
status Specifying T sets a begin mark. Specifying nil sets an end mark, clearing the begin mark.
If status is omitted, acet-layerp-mark returns the current mark status for layer settings.
Return Values
T if a begin mark is in effect; otherwise nil.
Examples
The following code changes layer 0 to blue, and then makes several additional layer changes between a set of begin and end marks. If you issue LAYERP after running this code, layer 0 reverts to blue.
(defun TestLayerP ()
AutoLISP Functions | 19
;; Turn LAYERPMODE on, if it isn't already (if (not (acet-layerp-mode))
(acet-layerp-mode T) ) ;; Set layer 0 to the color blue (command "_.layer" "_color" "blue" "0" "") ;; Set a begin mark (acet-layerp-mark T)
;; Issue a series of layer commands, and then set an end
mark
(command "_.layer" "_color" "green" "0" "") (command "_.layer" "_thaw" "*" "") (command "_.layer" "_unlock" "*" "") (command "_.layer" "_ltype" "hidden" "0" "") (command "_.layer" "_color" "red" "0" "") ;; Set an end mark (acet-layerp-mark nil)
)
See also:
The LAYERP command in the Command Reference.
alert
Displays a dialog box containing an error or warning message
(alert
string
)
Arguments
string The string to appear in the alert box.
Return Values
nil
Examples
Display a message in an alert box:
(alert "That function is not available.")
20 | Chapter 1 AutoLISP Functions
Display a multiple line message, by using the newline character in string:
(alert "That function\nis not available.")
NOTE
Line length and the number of lines in an alert box are platform, device, and window dependent. AutoCAD truncates any string that is too long to fit inside an alert box.
alloc
Sets the size of the segment to be used by the expand function
(alloc n-alloc)
Arguments
n-alloc An integer indicating the amount of memory to be allocated. The integer represents the number of symbols, strings, usubrs, reals, and cons cells.
Return Values
The previous setting of n-alloc.
Examples
_$
(alloc 100)
1000
See also:
The expand (page 85) function.
and
Returns the logical AND of the supplied arguments
(and
AutoLISP Functions | 21
[expr
...
]
)
Arguments
expr Any expression.
Return Values
Nil, if any of the expressions evaluate to nil; otherwise T. If and is issued
without arguments, it returns T.
Examples
Command: (setq a 103 b nil c "string") "string" Command: (and 1.4 a c) T Command: (and 1.4 a b c) nil
angle
Returns an angle in radians of a line defined by two endpoints
(angle
pt1 pt2
)
Arguments
pt1 An endpoint.
pt2 An endpoint.
Return Values
An angle, in radians.
The angle is measured from the X axis of the current construction plane, in radians, with angles increasing in the counterclockwise direction. If 3D points are supplied, they are projected onto the current construction plane.
Examples
22 | Chapter 1 AutoLISP Functions
Command: (angle '(1.0 1.0) '(1.0 4.0))
1.5708 Command: (angle '(5.0 1.33) '(2.4 1.33))
3.14159
See also:
The topic in the Angular Conversion AutoLISP Developer's Guide.
angtof
Converts a string representing an angle into a real (floating-point) value in radians
(angtof
string [units]
)
Arguments
string A string describing an angle based on the format specified by the mode argument. The string must be a string that angtof can parse correctly to the specified unit. It can be in the same form that angtos returns, or in a form that AutoCAD allows for keyboard entry.
units Specifies the units in which the string is formatted. The value should correspond to values allowed for the AutoCAD system variable AUNITS in the Command Reference. If unit is omitted, angtof uses the current value of AUNITS. The following units may be specified:
0 -- Degrees
1 -- Degrees/minutes/seconds
2 -- Grads
3 -- Radians
4 -- Surveyor's units
Return Values
A real value, if successful; otherwise nil.
The angtof and angtos functions are complementary: if you pass angtof a string created by angtos, angtof is guaranteed to return a valid value, and vice versa (assuming the unit values match).
AutoLISP Functions | 23
Examples
Command: (angtof "45.0000")
0.785398 Command: (angtof "45.0000" 3)
1.0177
See also:
The angtos (page 24) function.
angtos
Converts an angular value in radians into a string
(angtos
angle [unit [precision]]
)
Arguments
angle A real number, in radians.
unit An integer that specifies the angular units. If unit is omitted, angtos uses
the current value of the AutoCAD system variable AUNITS. The following units may be specified:
0 -- Degrees
1 -- Degrees/minutes/seconds
2 -- Grads
3 -- Radians
4 -- Surveyor's units
precision An integer specifying the number of decimal places of precision to be returned. If omitted, angtos uses the current setting of the AutoCAD system variable AUPREC in the Command Reference.
The angtos function takes angle and returns it edited into a string according to the settings of unit, precision, the AutoCAD UNITMODE system variable, and the DIMZIN dimensioning variable in the Command Reference.
The angtos function accepts a negative angle argument, but always reduces it to a positive value between zero and 2 pi radians before performing the specified conversion.
24 | Chapter 1 AutoLISP Functions
The UNITMODE system variable affects the returned string when surveyor's units are selected (a unit value of 4). If UNITMODE = 0, spaces are included in the string (for example, “N 45d E”); if UNITMODE = 1, no spaces are included in the string (for example, “N45dE”).
Return Values
A string, if successful; otherwise nil.
Examples
Command: (angtos 0.785398 0 4) "45.0000" Command: (angtos -0.785398 0 4) "315.0000" Command: (angtos -0.785398 4) "S 45d E"
NOTE Routines that use the angtos function to display arbitrary angles (those not relative to the value of ANGBASE) should check and consider the value of ANGBASE.
See also:
The angtof (page 23) function and String Conversions in the AutoLISP
Developer's Guide.
append
Takes any number of lists and appends them together as one list
(append
[list
...
]
)
Arguments
list A list.
Return Values
A list with all arguments appended to the original. If no arguments are supplied, append returns nil.
AutoLISP Functions | 25
Examples
Command: (append '(a b) '(c d)) (A B C D) Command: (append '((a)(b)) '((c)(d))) ((A) (B) (C) (D))
apply
Passes a list of arguments to, and executes, a specified function
(apply '
function list
)
Arguments
'function A function. The function argument can be either a symbol identifying a defun, or a lambda expression.
list A list. Can be nil, if the function accepts no arguments.
Return Values
The result of the function call.
Examples
Command: (apply '+ '(1 2 3)) 6 Command: (apply 'strcat '("a" "b" "c")) "abc"
arx
Returns a list of the currently loaded ObjectARX applications
(arx)
Return Values
A list of ObjectARX® application file names; the path is not included in the file name.
Examples
26 | Chapter 1 AutoLISP Functions
Command: (arx) ("layermanager.bundle" "mtextformat.bundle" "opm.bundle")
See also:
The arxload (page 27) and arxunload (page 28) functions.
arxload
Loads an ObjectARX application
(arxload
application [onfailure]
)
Arguments
application A quoted string or a variable that contains the name of an executable file. You can omit the .bundle extension from the file name.
You must supply the full path name of the ObjectARX executable file, unless the file is in a directory that is in the AutoCAD support file search path.
onfailure An expression to be executed if the load fails.
Return Values
The application name, if successful. If unsuccessful and the onfailure argument is supplied, arxload returns the value of this argument; otherwise, failure results in an error message.
If you attempt to load an application that is already loaded, arxload issues an error message. You may want to check the currently loaded ObjectARX applications with the arx function before using arxload.
Examples
Load the acbrowser.bundle file supplied in the AutoCAD installation directory:
Command: (arxload "/Applications/Autodesk/AutoCAD 2013/AutoCAD 2013.app/acbrowser.bundle")
"/Applications/Autodesk/AutoCAD 2013/AutoCAD
2013.app/acbrowser.bundle"
See also:
The arxunload (page 28) function.
AutoLISP Functions | 27
arxunload
Unloads an ObjectARX application
(arxunload
application [onfailure]
)
Arguments
application A quoted string or a variable that contains the name of a file that was loaded with the arxload function. You can omit the .bundle extension and the path from the file name.
onfailure An expression to be executed if the unload fails.
Return Values
The application name, if successful. If unsuccessful and the onfailure argument is supplied, arxunload returns the value of this argument; otherwise, failure results in an error message.
Note that locked ObjectARX applications cannot be unloaded. ObjectARX applications are locked by default.
Examples
Unload the acbrowse application that was loaded in the arxload function example:
Command: (arxunload "acbrowser") "acbrowser"
See also:
The arxload (page 27) function.
ascii
Returns the conversion of the first character of a string into its ASCII character code (an integer)
(ascii
string
28 | Chapter 1 AutoLISP Functions
)
Arguments
string A string.
Return Values
An integer.
Examples
Command: (ascii "A") 65 Command: (ascii "a") 97 Command: (ascii "BIG") 66
assoc
Searches an association list for an element and returns that association list entry
(assoc
element alist
)
Arguments
element Key of an element in an association list.
alist An association list to be searched.
Return Values
The alist entry, if successful. If assoc does not find element as a key in alist, it returns nil.
Examples
Command: (setq al '((name box) (width 3) (size 4.7263) (depth 5))) ((NAME BOX) (WIDTH 3) (SIZE 4.7263) (DEPTH 5)) Command: (assoc 'size al) (SIZE 4.7263) Command: (assoc 'weight al) nil
AutoLISP Functions | 29
atan
Returns the arctangent of a number in radians
(atan
num1 [num2]
)
Arguments
num1 A number.
num2 A number.
Return Values
The arctangent of num1, in radians, if only num1 is supplied. If you supply both num1 and num2 arguments, atan returns the arctangent of num1/num2, in radians. If num2 is zero, it returns an angle of plus or minus 1.570796 radians (+90 degrees or -90 degrees), depending on the sign ofnum1. The range of angles returned is -pi/2 to +pi/2 radians.
Examples
Command: (atan 1)
0.785398 Command: (atan 1.0)
0.785398 Command: (atan 0.5)
0.463648 Command: (atan 1.0)
0.785398 Command: (atan -1.0)
-0.785398 Command: (atan 2.0 3.0)
0.588003 Command: (atan 2.0 -3.0)
2.55359 Command: (atan 1.0 0.0)
1.5708
30 | Chapter 1 AutoLISP Functions
atof
Converts a string into a real number
(atof
string
)
Arguments
string A string to be converted into a real number.
Return Values
A real number.
Examples
Command: (atof "97.1")
97.1 Command: (atof "3")
3.0 Command: (atof "3.9")
3.9
atoi
Converts a string into an integer
(atoi
string
)
Arguments
string A string to be converted into an integer.
Return Values
An integer.
Examples
Command: (atoi "97") 97 Command: (atoi "3")
AutoLISP Functions | 31
3 Command: (atoi "3.9") 3
See also:
The itoa (page 125) function.
atom
Verifies that an item is an atom
(atom
item
)
Arguments
item Any AutoLISP element.
Some versions of LISP differ in their interpretation of atom, so be careful when converting from non-AutoLISP code.
Return Values
Nil if item is a list; otherwise T. Anything that is not a list is considered an
atom.
Examples
Command: (setq a '(x y z)) (X Y Z) Command: (setq b 'a) A Command: (atom 'a) T Command: (atom a) nil Command: (atom 'b) T Command: (atom b) T Command: (atom '(a b c)) nil
32 | Chapter 1 AutoLISP Functions
atoms-family
Returns a list of the currently defined symbols
(atoms-family
format [symlist]
)
Arguments
format An integer value of 0 or 1 that determines the format in which
atoms-family returns the symbol names:
0 Return the symbol names as a list
1 Return the symbol names as a list of strings
symlist A list of strings that specify the symbol names you want atoms-family to search for.
Return Values
A list of symbols. If you specify symlist, then atoms-family returns the specified symbols that are currently defined, and returns nil for those symbols that are not defined.
Examples
Command: (atoms-family 0) (BNS_PRE_SEL FITSTR2LEN C:AI_SPHERE ALERT DEFUN C:BEXTEND REM_GROUP B_RESTORE_SYSVARS BNS_CMD_EXIT LISPED FNSPLITL...
The following code verifies that the symbols CAR, CDR, and XYZ are defined, and returns the list as strings:
Command: (atoms-family 1 '("CAR" "CDR" "XYZ")) ("CAR" "CDR" nil)
The return value shows that the symbol XYZ is not defined.
autoarxload
Predefines command names to load an associated ObjectARX file
(autoarxload
AutoLISP Functions | 33
filename cmdlist
)
The first time a user enters a command specified in cmdlist, AutoCAD loads the ObjectARX application specified in filename, then continues the command.
If you associate a command with filename and that command is not defined in the specified file, AutoCAD alerts you with an error message when you enter the command.
Arguments
filename A string specifying the .bundle file to be loaded when one of the commands defined by the cmdlist argument is entered at the Command prompt. If you omit the path from filename, AutoCAD looks for the file in the support file search path.
cmdlist A list of strings.
Return Values
nil
Examples
The following code defines the C:APP1, C:APP2, and C:APP3 functions to load the bonusapp.bundle file:
(autoarxload "BONUSAPP" '("APP1" "APP2" "APP3"))
autoload
Predefines command names to load an associated AutoLISP file
(autoload
filename cmdlist
)
The first time a user enters a command specified in cmdlist, AutoCAD loads the application specified in filename, then continues the command.
Arguments
filename A string specifying the .lsp file to be loaded when one of the commands defined by the cmdlist argument is entered at the Command
34 | Chapter 1 AutoLISP Functions
prompt. If you omit the path from filename, AutoCAD looks for the file in the Support File Search Path.
cmdlist A list of strings.
Return Values
nil
If you associate a command with filename and that command is not defined in the specified file, AutoCAD alerts you with an error message when you enter the command.
Examples
The following causes AutoCAD to load the bonusapp.lsp file the first time the APP1, APP2, or APP3 commands are entered at the Command prompt:
(autoload "BONUSAPP" '("APP1" "APP2" "APP3"))

B Functions

Boole
Serves as a general bitwise Boolean function
(Boole
operator int1 [int2
...
]
)
Arguments
operator An integer between 0 and 15 representing one of the 16 possible Boolean functions in two variables.
int1, int2... Integers.
Note that Boole will accept a single integer argument, but the result is unpredictable.
AutoLISP Functions | 35
Successive integer arguments are bitwise (logically) combined based on this function and on the following truth table:
Boolean truth table
operator bitInt2Int1
800
410
201
111
Each bit of int1 is paired with the corresponding bit of int2, specifying one horizontal row of the truth table. The resulting bit is either 0 or 1, depending on the setting of the operator bit that corresponds to this row of the truth table.
If the appropriate bit is set in operator, the resulting bit is 1; otherwise the resulting bit is 0. Some of the values for operator are equivalent to the standard Boolean operations AND, OR, XOR, and NOR.
Boole function bit values
Return Values
An integer.
Examples
The following specifies a logical AND of the values 12 and 5:
36 | Chapter 1 AutoLISP Functions
Resulting bit is 1 ifOperationOperator
Both input bits are 1AND1
Only one of the two input bits is 1XOR6
Either or both of the input bits are 1OR7
Both input bits are 0 (1's complement)NOR8
Command: (Boole 1 12 5) 4
The following specifies a logical XOR of the values 6 and 5:
Command: (Boole 6 6 5) 3
You can use other values of operator to perform other Boolean operations for which there are no standard names. For example, if operator is 4, the resulting bits are set if the corresponding bits are set in int2 but not in int1:
Command: (Boole 4 3 14) 12
boundp
Verifies if a value is bound to a symbol
(boundp
sym
)
Arguments
sym A symbol.
Return Values
T if sym has a value bound to it. If no value is bound to sym, or if it has been
bound to nil, boundp returns nil. If sym is an undefined symbol, it is automatically created and is bound to nil.
Examples
Command: (setq a 2 b nil) nil Command: (boundp 'a) T Command: (boundp 'b) nil
The atoms-family function provides an alternative method of determining the existence of a symbol without automatically creating the symbol.
AutoLISP Functions | 37
See also:
The atoms-family (page 33) function.

C Functions

caddr
Returns the third element of a list
(caddr
list
)
In AutoLISP, caddr is frequently used to obtain the Z coordinate of a 3D point (the third element of a list of three reals).
Arguments
list A list.
Return Values
The third element in list; otherwise nil, if the list is empty or contains fewer than three elements.
Examples
Command: (setq pt3 '(5.25 1.0 3.0)) (5.25 1.0 3.0) Command: (caddr pt3)
3.0 Command: (caddr '(5.25 1.0)) nil
See also:
The Point Lists topic in the AutoLISP Developer's Guide.
cadr
Returns the second element of a list
38 | Chapter 1 AutoLISP Functions
(cadr
list
)
In AutoLISP, cadr is frequently used to obtain the Y coordinate of a 2D or 3D point (the second element of a list of two or three reals).
Arguments
list A list.
Return Values
The second element in list; otherwise nil, if the list is empty or contains only one element.
Examples
Command: (setq pt2 '(5.25 1.0)) (5.25 1.0) Command: (cadr pt2)
1.0 Command: (cadr '(4.0)) nil Command: (cadr '(5.25 1.0 3.0))
1.0
See also:
The Point Lists topic in the AutoLISP Developer's Guide.
car
Returns the first element of a list
(car
list
)
Arguments
list A list.
Return Values
AutoLISP Functions | 39
The first element in list; otherwise nil, if the list is empty.
Examples
Command: (car '(a b c)) A Command: (car '((a b) c)) (A B) Command: (car '()) nil
See also:
The Point Lists topic in the AutoLISP Developer's Guide.
cdr
Returns a list containing all but the first element of the specified list
(cdr
list
)
Arguments
list A list.
Return Values
A list containing all the elements of list, except the first element (but see Note below). If the list is empty, cdr returns nil.
NOTE When the list argument is a dotted pair, cdr returns the second element without enclosing it in a list.
Examples
Command: (cdr '(a b c)) (B C) Command: (cdr '((a b) c)) (C) Command: (cdr '()) nil Command: (cdr '(a . b)) B
40 | Chapter 1 AutoLISP Functions
Command: (cdr '(1 . "Text")) "Text"
See also:
The Point Lists topic in the AutoLISP Developer's Guide.
chr
Converts an integer representing an ASCII character code into a single-character string
(chr
integer
)
Arguments
list An integer.
Return Values
A string containing the ASCII character code for integer. If the integer is not in the range of 1-255, the return value is unpredictable.
Examples
Command: (chr 65) "A" Command: (chr 66) "B" Command: (chr 97) "a"
close
Closes an open file
(close
file-desc
)
Arguments
AutoLISP Functions | 41
file-desc A file descriptor obtained from the open function.
Return Values
Nil if file-desc is valid; otherwise results in an error message.
After a close, the file descriptor is unchanged but is no longer valid. Data added to an open file is not actually written until the file is closed.
Examples
The following code counts the number of lines in the file somefile.txt and sets the variable ct equal to that number:
(setq fil "SOMEFILE.TXT") (setq x (open fil "r") ct 0) (while (read-line x)
(setq ct (1+ ct))
) (close x)
command
Executes an AutoCAD command
(command
[arguments]
...)
Arguments
arguments AutoCAD commands and their options.
The arguments to the command function can be strings, reals, integers, or points, as expected by the prompt sequence of the executed command. A null string ("") is equivalent to pressing Enter on the keyboard. Invoking command with no argument is equivalent to pressing Esc and cancels most AutoCAD commands.
The command function evaluates each argument and sends it to AutoCAD in response to successive prompts. It submits command names and options as strings, 2D points as lists of two reals, and 3D points as lists of three reals. AutoCAD recognizes command names only when it issues a Command prompt.
Return Values
42 | Chapter 1 AutoLISP Functions
nil
Examples
The following example sets two variables pt1 and pt2 equal to two point values 1,1 and 1,5. It then uses the command function to issue the LINE command in the Command Reference and pass the two point values.
Command: (setq pt1 '(1 1) pt2 '(1 5)) (1 5) Command: (command "line" pt1 pt2 "") line From point: To point: To point: Command: nil
Restrictions and Notes
Also, if you use the command function in an acad.lsp or .mnl file, it should be called only from within a defun statement. Use the S::STARTUP function to define commands that need to be issued immediately when you begin a
drawing session.
For AutoCAD commands that require the selection of an object (like the BREAK and TRIM commands in the Command Reference), you can supply a list obtained with entsel instead of a point to select the object. For examples, see Passing Pick Points yo AutoCAD Commands in the AutoLISP Developer's Guide.
Commands executed from the command function are not echoed to the command line if the CMDECHO system variable (accessible from setvar and
getvar) is set to 0.
NOTE When using the SCRIPT command with the command function, it should be the last function call in the AutoLISP routine.
See also:
initcommandversion (page 116)
vl-cmdf (page 219) under Command Submission in the AutoLISP Developer's
Guide
command-s
Executes an AutoCAD command and the supplied input.
AutoLISP Functions | 43
(command-s
cmdname [arguments]
)
Arguments
cmdname Name of the command to execute.
arguments The command input to supply to the command being executed.
The arguments to the command function can be strings, reals, integers, or points, as expected by the prompt sequence of the executed command. A null string ("") is equivalent to pressing Enter on the keyboard.
Return Values
nil is returned by the function when the command is done executing on the
provided arguments. An *error* is returned when the function fails to complete successfully.
Examples
The following example demonstrates how to execute the CIRCLE command and create a circle with a diameter of 2.75.
Command: (command-s "_circle" "5,4" "_d" 2.75) nil
The following example demonstrates how to prompt the user for the center point of the circle.
Command: (setq cPt (getpoint "\nSpecify center point: ")) (5.0 4.0 0.0)
Command: (command-s "_circle" cPt "_d" 2.75) nil
The following is an invalid use of prompting for user input with the command-s function.
Command: (command-s "_circle" (getpoint "\nSpecify center point: ") "_d" 2.75)
Differences from the Command Function
The command-s function is a variation of the command function which has some restrictions on command token content, but is both faster than command and can be used in *error* handlers due to internal logic differences.
44 | Chapter 1 AutoLISP Functions
A command token is a single argument provided to the command-s function. This could be a string, real, integer, point, entity name, list, and so on. The following example shows the LINE command and three command tokens:
(command-s "_line" "0,0" "5,7" "")
The "-s" suffix stands for "subroutine" execution of the supplied command tokens. In this form, AutoCAD is directly called from AutoLISP, processes the supplied command tokens in a temporary command processor distinct from the main document command processor, and then returns, thus terminating the temporary command processor. The command that is being executed must be started and completed in the same command-s function.
In contrast, the command function remains a "co-routine" execution of the supplied command tokens, where AutoLISP evaluates the tokens one at a time, sending the result to AutoCAD, and then returning to allow AutoCAD to process that token. AutoCAD then calls AutoLISP back, and AutoLISP resumes evaluation of the expression in progress. In this logic flow, subsequent token expressions can query AutoCAD for the results of previous token processing and use it.
In summary, the "co-routine" style of command token processing is more functionally powerful, but is limited in when it can be used when running. The "subroutine" style of command token processing can be used in a much wider range of contexts, but processes all command tokens in advance, and actual execution is non-interactive. For the same set of command tokens,
command-s function is significantly faster.
Known Considerations
When using the command-s function, you must take the following into consideration:
■ Token streams fed in a single command-s expression must represent a full
command and its input. Any commands in progress when command tokens
are all processed will be cancelled. The following is not valid with the
command-s function:
(command-s "_line") (command-s "2,2" "12.25,9" "")
■ All command tokens will be evaluated before they are handed over to
AutoCAD for execution. In contrast, the command function actually performs
each command token evaluation and then feeds the result to AutoCAD,
which processes it before the next command token is processed.
AutoLISP Functions | 45
■ No "Pause" command tokens may be used. Expressions that interact with
the drawing area or Command Window may be used, but will all be processed before AutoCAD receives and processes any of them.
The following is not valid with the command-s function:
(command-s "_line" "0,0" PAUSE "")
IMPORTANT Although the command-s function is similar to the command function, caution should be taken when using U or UNDO to roll back the system state if there is an AutoCAD command already in progress when the AutoLISP expression is entered. In that case, the results of running UNDO may cause the command in progress to fail or even crash AutoCAD.
*error* Handler
If your *error* handler uses the command function, consider updating the way you define your custom *error* handlers using the following methods:
■ Substitute command-s for command in *error* handler
For typical *error* handler cases where the previous state of the program needs to be restored and a few batch commands are executed, you can substitute (command-s <...>) for (command <...>). The *error* handler is called from the same context as it always has been.
The following demonstrates a based *error* handler using the command-s function:
(defun my_err(s)
(prompt "\nERROR: mycmd failed or was cancelled") (setvar "clayer" old_clayer) (command-s "_.UNDO" "_E") (setq *error* mv_oer)
)
(defun c:mycmd ()
(setq old_err *error*
*error* my_err old_clayer (getvar "clayer")
)
(setq insPt (getpoint "\nSpecify text insertion: "))
(if (/= insPt nil)
(progn
46 | Chapter 1 AutoLISP Functions
(command-s "_.UNDO" "_BE") (command-s "-_LAYER" "_M" "Text" "_C" "3" "" "") (command-s "_-TEXT" insPt "" "0" "Sample Text") (command-s "_.UNDO" "_E")
)
)
(setvar "clayer" old_clayer) (setq *error* mv_oer)
(princ)
)
■ Retaining the use of the command function in *error* handler
If using the command-s function is not viable option, then the command function can still be used, but only at the expense of losing access to any local symbols that would normally be on the AutoLISP call stack at the time of the *error* processing.
The following is an overview of what is required to continue to use the
command function in the *error* handler.
■ When overriding the *error* symbol with a custom *error* handler,
invoke the *push-error-using-command* function to inform AutoLISP that error handling will be used with the proceeding command functions.
NOTE Whenever an AutoLISP expression evaluation begins, the AutoLISP
engine assumes that the command function will not be allowed within an
*error* handler.
■ If the *error* handler refers to local symbols that are on the AutoLISP
stack at the point where AutoLISP program failed or was cancelled, you must remove those references, or make the referenced symbols global symbols.
All local symbols on the AutoLISP call stack are pushed out of scope because the AutoLISP evaluator is reset before entering the *error* handler.
Now the command function can be used within the *error* handler.
However, if your program actually pushes and pops error handlers as part
of its operations, or your AutoLISP logic can be invoked while other
AutoLISP Functions | 47
unknown AutoLISP logic is invoked, there are a couple more steps you may have to make.
■ When restoring an old error handler, also invoke the *pop-error-mode*
function to reverse the effects of any call to the
*push-error-using-command* or *push-error-using-stack* functions.
■ If your logic has nested pushes and pops of the *error* handler, and
an *error* handler has been set up to use the command function by invoking *push-error-using-command*, while the nested handler will not use it, you can provide access to the locally defined symbols on the AutoLISP stack by invoking *push-error-using-stack* at the same point where you set *error* to the current handler. If this is done, you must also invoke *pop-error-mode* after the old *error* handler is restored.
See also:
Command (page 42)
cond
Serves as the primary conditional function for AutoLISP
(cond
[
(
test result
...) ...
]
)
The cond function accepts any number of lists as arguments. It evaluates the first item in each list (in the order supplied) until one of these items returns a value other than nil. It then evaluates those expressions that follow the test that succeeded.
Return Values
The value of the last expression in the sublist. If there is only one expression in the sublist (that is, if result is missing), the value of the test expression is returned. If no arguments are supplied, cond returns nil.
48 | Chapter 1 AutoLISP Functions
Examples
The following example uses cond to perform an absolute value calculation:
(cond
((minusp a) (- a)) (t a)
)
If the variable a is set to the value-10, this returns 10.
As shown, cond can be used as a case type function. It is common to use T as the last (default) test expression. Here's another simple example. Given a user response string in the variable s, this function tests the response and returns 1 if it is Y or y, 0 if it is N or n; otherwise nil.
(cond
((= s "Y") 1) ((= s "y") 1) ((= s "N") 0) ((= s "n") 0) (t nil)
)
cons
Adds an element to the beginning of a list, or constructs a dotted list
(cons
new-first-element list-or-atom
)
Arguments
new-first-element Element to be added to the beginning of a list. This element can be an atom or a list.
list-or-atom A list or an atom.
Return Values
The value returned depends on the data type of list-or-atom. If list-or-atom is a list, cons returns that list with new-first-element added as the first item in the
AutoLISP Functions | 49
list. If list-or-atom is an atom, cons returns a dotted pair consisting of new-first-element and list-or-atom.
Examples
Command: (cons 'a '(b c d)) (A B C D) Command: (cons '(a) '(b c d)) ((A) B C D) Command: (cons 'a 2) (A . 2)
See also:
The List Handling topic in the AutoLISP Developer's Guide.
cos
Returns the cosine of an angle expressed in radians
(cos
ang
)
Arguments
ang An angle, in radians.
Return Values
The cosine of ang, in radians.
Examples
Command: (cos 0.0)
1.0 Command: (cos pi)
-1.0
cvunit
Converts a value from one unit of measurement to another
50 | Chapter 1 AutoLISP Functions
(cvunit
value from-unit to-unit
)
Arguments
value The numeric value or point list (2D or 3D point) to be converted.
from-unit The unit that value is being converted from.
to-unit The unit that value is being converted to.
The from-unit and to-unit arguments can name any unit type found in the acad.unt file.
Return Values
The converted value, if successful; otherwise nil, if either unit name is unknown (not found in the acad.unt file), or if the two units are incompatible (for example, trying to convert grams into years).
Examples
Command: (cvunit 1 "minute" "second")
60.0 Command: (cvunit 1 "gallon" "furlong") nil Command: (cvunit 1.0 "inch" "cm")
2.54 Command: (cvunit 1.0 "acre" "sq yard")
4840.0 Command: (cvunit '(1.0 2.5) "ft" "in") (12.0 30.0) Command: (cvunit '(1 2 3) "ft" "in") (12.0 24.0 36.0)
NOTE
If you have several values to convert in the same manner, it is more efficient to convert the value 1.0 once and then apply the resulting value as a scale factor in your own function or computation. This works for all predefined units except temperature, where an offset is involved as well.
See also:
The Unit Conversion topic in the AutoLISP Developer's Guide.
AutoLISP Functions | 51

D Functions

defun
Defines a function
(defun
sym ([arguments] [/ variables...]
) expr...)
Arguments
sym A symbol naming the function.
arguments The names of arguments expected by the function.
/ variables The names of one or more local variables for the function.
The slash preceding the variable names must be separated from the first local name and from the last argument, if any, by at least one space.
expr Any number of AutoLISP expressions to be evaluated when the function executes.
If you do not declare any arguments or local symbols, you must supply an empty set of parentheses after the function name.
If duplicate argument or symbol names are specified, AutoLISP uses the first occurrence of each name and ignores the following occurrences.
Return Values
The result of the last expression evaluated.
WARNING Never use the name of a built-in function or symbol for the sym argument to defun. This overwrites the original definition and makes the built-in function or symbol inaccessible. To get a list of built-in and previously defined functions, use the atoms-family function.
Examples
(defun myfunc (x y) ...)
Function takes two arguments
52 | Chapter 1 AutoLISP Functions
(defun myfunc (/ a b) ...)
Function has two local variables
(defun myfunc (x / temp) ...)
One argument, one local variable
(defun myfunc () ...)
No arguments or local variables
See also:
The Symbol and Function Handling topic in the AutoLISP Developer's Guide.
defun-q
Defines a function as a list
(defun-q
sym ([arguments] [/ variables...]
) expr...)
The defun-q function is provided strictly for backward-compatibility with previous versions of AutoLISP, and should not be used for other purposes. You can use defun-q in situations where you need to access a function definition as a list structure, which is the way defun was implemented in previous, non-compiled versions of AutoLISP.
Arguments
sym A symbol naming the function.
arguments The names of arguments expected by the function.
/ variables The names of one or more local variables for the function.
The slash preceding the variable names must be separated from the first local name and from the last argument, if any, by at least one space.
expr Any number of AutoLISP expressions to be evaluated when the function executes.
If you do not declare any arguments or local symbols, you must supply an empty set of parentheses after the function name.
AutoLISP Functions | 53
If duplicate argument or symbol names are specified, AutoLISP uses the first occurrence of each name and ignores the following occurrences.
Return Values
The result of the last expression evaluated.
Examples
(defun-q my-startup (x) (print (list x)))
MY-STARTUP
(my-startup 5)
(5) (5)
Use defun-q-list-ref to display the list structure of my-startup:
(defun-q-list-ref 'my-startup)
((X) (PRINT (LIST X)))
See also:
The defun-q-list-ref (page 54) and defun-q-list-set (page 55) functions.
defun-q-list-ref
Displays the list structure of a function defined with defun-q
(defun-q-list-ref '
function
)
Arguments
function A symbol naming the function.
Return Values
The list definition of the function; otherwise nil, if the argument is not a list.
Examples
Define a function using defun-q:
(defun-q my-startup (x) (print (list x)))
MY-STARTUP
54 | Chapter 1 AutoLISP Functions
Use defun-q-list-ref to display the list structure of my-startup:
(defun-q-list-ref 'my-startup)
((X) (PRINT (LIST X)))
See also:
The defun-q (page 53) and defun-q-list-set (page 55) functions.
defun-q-list-set
Sets the value of a symbol to be a function defined by a list
(defun-q-list-set '
sym list
)
Arguments
sym A symbol naming the function
list A list containing the expressions to be included in the function.
Return Values
The sym defined.
Examples
(defun-q-list-set 'foo '((x) x))
FOO
(foo 3)
3
The following example illustrates the use of defun-q-list-set to combine two functions into a single function. First, from the Visual LISP Console window, define two functions with defun-q:
(defun-q s::startup (x) (print x))
S::STARTUP
(defun-q my-startup (x) (print (list x)))
MY-STARTUP
Use defun-q-list-set to combine the functions into a single function:
AutoLISP Functions | 55
(defun-q-list-set 's::startup (append
(defun-q-list-ref 's::startup)
(cdr (defun-q-list-ref 'my-startup))))
S::STARTUP
The following illustrates how the functions respond individually, and how the functions work after being combined using defun-q-list-set:
(defun-q foo (x) (print (list 'foo x)))
FOO
(foo 1)
(FOO 1) (FOO 1)
(defun-q bar (x) (print (list 'bar x)))
BAR
(bar 2)
(BAR 2) (BAR 2)
(defun-q-list-set
'foo
(append (defun-q-list-ref 'foo)
(cdr (defun-q-list-ref 'bar))
))
FOO
(foo 3)
(FOO 3) (BAR 3) (BAR 3)
See also:
The defun-q (page 53) and defun-q-list-ref (page 54) functions.
dictadd
Adds a nongraphical object to the specified dictionary
(dictadd
ename symbol newobj
)
Arguments
56 | Chapter 1 AutoLISP Functions
ename Name of the dictionary the object is being added to.
symbol The key name of the object being added to the dictionary; symbol must
be a unique name that does not already exist in the dictionary.
newobj A nongraphical object to be added to the dictionary.
As a general rule, each object added to a dictionary must be unique to that dictionary. This is specifically a problem when adding group objects to the group dictionary. Adding the same group object using different key names results in duplicate group names, which can send the dictnext function into an infinite loop.
Return Values
The entity name of the object added to the dictionary.
Examples
The examples that follow create objects and add them to the named object dictionary.
Create a dictionary entry list:
Command: (setq dictionary (list '(0 . "DICTIONARY") '(100 . "AcDbDictionary")))
((0 . "DICTIONARY") (100 . "AcDbDictionary"))
Create a dictionary object using the entmakex function:
Command: (setq xname (entmakex dictionary)) <Entity name: 1d98950>
Add the dictionary to the named object dictionary:
Command: (setq newdict (dictadd (namedobjdict) "MY_WAY_COOL_DICTIONARY" xname))
<Entity name: 1d98950>
Create an Xrecord list:
Command: (setq datalist (append (list '(0 . "XRECORD")'(100 . "AcDbXrecord")) '((1 . "This is my data") (10 1. 2. 3.) (70 . 33))))
((0 . "XRECORD") (100 . "AcDbXrecord") (1 . "This is my data") (10 1.0 2.0 3.0) (70 . 33))
Make an Xrecord object:
Command: (setq xname (entmakex datalist)) <Entity name: 1d98958>
Add the Xrecord object to the dictionary:
Command: (dictadd newdict "DATA_RECORD_1" xname)
AutoLISP Functions | 57
<Entity name: 1d98958>
See also:
The dictnext (page 58), dictremove (page 59), dictrename (page 60), dict-
search (page 61), and namedobjdict (page 149) functions.
dictnext
Finds the next item in a dictionary
(dictnext
ename [rewind]
)
Arguments
ename Name of the dictionary being viewed.
rewind If this argument is present and is not nil, the dictionary is rewound
and the first entry in it is retrieved.
Return Values
The next entry in the specified dictionary; otherwise nil, when the end of the dictionary is reached. Entries are returned as lists of dotted pairs of DXF-type codes and values. Deleted dictionary entries are not returned.
The dictsearch function specifies the initial entry retrieved.
Use namedobjdict to obtain the master dictionary entity name.
NOTE Once you begin stepping through the contents of a dictionary, passing a different dictionary name to dictnext will cause the place to be lost in the original dictionary. In other words, only one global iterator is maintained for use in this function.
Examples
Create a dictionary and an entry as shown in the example for dictadd. Then make another Xrecord object:
Command: (setq xname (entmakex datalist)) <Entity name: 1b62d60>
58 | Chapter 1 AutoLISP Functions
Add this Xrecord object to the dictionary, as the second record in the dictionary:
Command: (dictadd newdict "DATA_RECORD_2" xname) <Entity name: 1b62d60>
Return the entity name of the next entry in the dictionary:
Command: (cdr (car (dictnext newdict))) <Entity name: 1bac958>
dictnext returns the name of the first entity added to the dictionary.
Return the entity name of the next entry in the dictionary:
Command: (cdr (car (dictnext newdict))) <Entity name: 1bac960>
dictnext returns the name of the second entity added to the dictionary.
Return the entity name of the next entry in the dictionary:
Command: (cdr (car (dictnext newdict))) nil
There are no more entries in the dictionary, so dictnext returns nil.
Rewind to the first entry in the dictionary and return the entity name of that entry:
Command: (cdr (car (dictnext newdict T))) <Entity name: 1bac958>
Specifying T for the optional rewind argument causes dictnext to return the first entry in the dictionary.
See also:
The dictadd (page 56), dictremove (page 59), dictrename (page 60), dict-
search (page 61), and namedobjdict (page 149) functions.
dictremove
Removes an entry from the specified dictionary
(dictremove
ename symbol
)
AutoLISP Functions | 59
By default, removing an entry from a dictionary does not delete it from the database. This must be done with a call to entdel. Currently, the exceptions to this rule are groups and mlinestyles. The code that implements these features requires that the database and these dictionaries be up to date and, therefore, automatically deletes the entity when it is removed (with dictremove) from the dictionary.
Arguments
ename Name of the dictionary being modified.
symbol The entry to be removed from ename.
The dictremove function does not allow the removal of an mlinestyle from the mlinestyle dictionary if it is actively referenced by an mline in the database.
Return Values
The entity name of the removed entry. If ename is invalid or symbol is not found, dictremove returns nil.
Examples
The following example removes the dictionary created in the dictadd example:
Command: (dictremove (namedobjdict) "my_way_cool_dictionary") <Entity name: 1d98950>
See also:
The dictadd (page 56), dictnext (page 58), dictrename (page 60), dictsearch (page 61), and namedobjdict (page 149) functions.
dictrename
Renames a dictionary entry
(dictrename
ename oldsym newsym
)
Arguments
ename Name of the dictionary being modified.
oldsym Original key name of the entry.
60 | Chapter 1 AutoLISP Functions
newsym New key name of the entry.
Return Values
The newsym value, if the rename is successful. If the oldname is not present in the dictionary, or if ename or newname is invalid, or if newname is already present in the dictionary, then dictrename returns nil.
Examples
The following example renames the dictionary created in the dictadd sample:
Command: (dictrename (namedobjdict) "my_way_cool_dictionary" "An even cooler dictionary")
"An even cooler dictionary"
See also:
The dictadd (page 56), dictnext (page 58), dictremove (page 59), dictsearch
(page 61), and namedobjdict (page 149) functions.
dictsearch
Searches a dictionary for an item
(dictsearch
ename symbol [setnext]
)
Arguments
ename Name of the dictionary being searched.
symbol A string that specifies the item to be searched for within the dictionary.
setnext If present and not nil, the dictnext entry counter is adjusted so the
following dictnext call returns the entry after the one returned by this
dictsearch call.
Return Values
The entry for the specified item, if successful; otherwise nil, if no entry is found.
Examples
AutoLISP Functions | 61
The following example illustrates the use of dictsearch to obtain the dictionary added in the dictadd example:
Command: (setq newdictlist (dictsearch (namedobjdict) "my_way_cool_dictionary"))
((-1 . <Entity name: 1d98950>) (0 . "DICTIONARY") (5 . "52") (102 . "{ACAD_REACTORS") (330 . <Entity name: 1d98860>) (102 . "}") (330 . <Entity name: 1d98860>) (100 . "AcDbDictionary") (280 . 0) (281 . 1) (3 . "DATA_RECORD_1") (350 . <Entity name: 1d98958>))
See also:
The dictadd (page 56), dictnext (page 58), dictremove (page 59), and
namedobjdict (page 149) functions.
distance
Returns the 3D distance between two points
(distance
pt1 pt2
)
Arguments
pt1 A 2D or 3D point list.
pt1 A 2D or 3D point list.
Return Values
The distance.
If one or both of the supplied points is a 2D point, then distance ignores the Z coordinates of any 3D points supplied and returns the 2D distance between the points as projected into the current construction plane.
Examples
Command: (distance '(1.0 2.5 3.0) '(7.7 2.5 3.0))
6.7 Command: (distance '(1.0 2.0 0.5) '(3.0 4.0 0.5))
2.82843
62 | Chapter 1 AutoLISP Functions
See also:
The Geometric Utilities topic in the AutoLISP Developer's Guide.
distof
Converts a string that represents a real (floating-point) value into a real value
(distof
string [mode]
)
The distof and rtos functions are complementary. If you pass distof a string created by rtos, distof is guaranteed to return a valid value, and vice versa (assuming the mode values are the same).
Arguments
string A string to be converted. The argument must be a string that distof can parse correctly according to the units specified by mode. It can be in the same form that rtos returns, or in a form that AutoCAD allows for keyboard entry.
mode The units in which the string is currently formatted. The mode corresponds to the values allowed for the AutoCAD system variable LUNITS in the Command Reference. Specify one of the following numbers for mode:
1 Scientific
2 Decimal
3 Engineering (feet and decimal inches)
4 Architectural (feet and fractional inches)
5 Fractional
Return Values
A real number, if successful; otherwise nil.
NOTE The distof function treats modes 3 and 4 the same. That is, if mode specifies 3 (engineering) or 4 (architectural) units, and string is in either of these formats,
distof returns the correct real value.
AutoLISP Functions | 63
dumpallproperties
Retrieves an entity’s supported properties.
(dumpallproperties
ename [context]
)
Arguments
ename Name of the entity being queried. The ename can refer to either a graphical or non-graphical entity.
context Value expected is 0 or 1, the default is 0 when a value is not provided. When 1 is provided as the context, some property values such as Position, Normal, and StartPoint are promoted from a single value to individual X, Y, and Z values.
For example, the following displays the StartPoint first as not being promoted and then being as promoted:
■ Not promoted, context = 0
StartPoint (type: AcGePoint3d) (LocalName: StartPoint)
= 6.250000 8.750000 0.000000
■ Promoted, context = 1
StartPoint/X (type: double) (LocalName: Start X) =
6.250000
StartPoint/Y (type: double) (LocalName: Start Y) =
8.750000
StartPoint/Z (type: double) (LocalName: Start Z) =
0.000000
Return Values
nil is returned by the function while the properties and their current values
are output to the Command Window.
Examples
The following example demonstrates how to list the available properties for a line object with the properties Delta, EndPoint, Normal, and StartPoint promoted to individual values.
Command: (setq e1 (car (entsel "\nSelect a line: "))) Select a line:
64 | Chapter 1 AutoLISP Functions
<Entity name: 10e2e4b20> Command: (dumpAllProperties e1 1)
Begin dumping object (class: AcDbLine) Angle (type: double) (RO) (LocalName: Angle) = 5.159347 Annotative (type: bool) (LocalName: Annotative) = Failed
to get value to get value Area (type: double) (RO) (LocalName: Area) = 0.000000 BlockId (type: AcDbObjectId) (RO) = Ix CastShadows (type: bool) = 0 ClassName (type: AcString) (RO) = Closed (type: bool) (RO) (LocalName: Closed) = Failed to
get value CollisionType (type: AcDb::CollisionType) (RO) = 1 Color (type: AcCmColor) (LocalName: Color) = BYLAYER Delta/X (type: double) (RO) (LocalName: Delta X) =
3.028287 Delta/Y (type: double) (RO) (LocalName: Delta Y) =
-6.318026 Delta/Z (type: double) (RO) (LocalName: Delta Z) =
0.000000 EndParam (type: double) (RO) = 7.006281 EndPoint/X (type: double) (LocalName: End X) = 23.249243 EndPoint/Y (type: double) (LocalName: End Y) = 11.968958 EndPoint/Z (type: double) (LocalName: End Z) = 0.000000 ExtensionDictionary (type: AcDbObjectId) (RO) = Ix Handle (type: AcDbHandle) (RO) = 1b2 HasFields (type: bool) (RO) = 0 HasSaveVersionOverride (type: bool) = 0 Hyperlinks (type: AcDbHyperlink*) IsA (type: AcRxClass*) (RO) = AcDbLine IsAProxy (type: bool) (RO) = 0 IsCancelling (type: bool) (RO) = 0 IsEraseStatusToggled (type: bool) (RO) = 0 IsErased (type: bool) (RO) = 0 IsModified (type: bool) (RO) = 0 IsModifiedGraphics (type: bool) (RO) = 0 IsModifiedXData (type: bool) (RO) = 0 IsNewObject (type: bool) (RO) = 0 IsNotifyEnabled (type: bool) (RO) = 0 IsNotifying (type: bool) (RO) = 0 IsObjectIdsInFlux (type: bool) (RO) = 0 IsPeriodic (type: bool) (RO) = 0
AutoLISP Functions | 65
IsPersistent (type: bool) (RO) = 1 IsPlanar (type: bool) (RO) = 1 IsReadEnabled (type: bool) (RO) = 1 IsReallyClosing (type: bool) (RO) = 1 IsTransactionResident (type: bool) (RO) = 0 IsUndoing (type: bool) (RO) = 0 IsWriteEnabled (type: bool) (RO) = 0 LayerId (type: AcDbObjectId) (LocalName: Layer) = Ix Length (type: double) (RO) (LocalName: Length) = 7.006281 LineWeight (type: AcDb::LineWeight) (LocalName: Lineweight)
= -1 LinetypeId (type: AcDbObjectId) (LocalName: Linetype) = Ix LinetypeScale (type: double) (LocalName: Linetype scale)
= 1.000000 LocalizedName (type: AcString) (RO) = Line MaterialId (type: AcDbObjectId) (LocalName: Material) = Ix MergeStyle (type: AcDb::DuplicateRecordCloning) (RO) = 1 Normal/X (type: double) = 0.000000 Normal/Y (type: double) = 0.000000 Normal/Z (type: double) = 1.000000 ObjectId (type: AcDbObjectId) (RO) = Ix OwnerId (type: AcDbObjectId) (RO) = Ix PlotStyleName (type: AcString) (LocalName: Plot style) =
ByLayer ReceiveShadows (type: bool) = 0 Failed to get value StartParam (type: double) (RO) = 0.000000 StartPoint/X (type: double) (LocalName: Start X) =
20.220956 StartPoint/Y (type: double) (LocalName: Start Y) =
18.286984 StartPoint/Z (type: double) (LocalName: Start Z) = 0.000000 Thickness (type: double) (LocalName: Thickness) = 0.000000 Transparency (type: AcCmTransparency) (LocalName: Transparency) = 0 Visible (type: AcDb::Visibility) = 0 End object dump
See also:
GetPropertyValue (page 103)
IsPropertyReadOnly (page 123)
66 | Chapter 1 AutoLISP Functions
SetPropertyValue (page 175)

E Functions

entdel
Deletes objects (entities) or restores previously deleted objects
(entdel
ename
)
The entity specified by ename is deleted if it is currently in the drawing. The
entdel function restores the entity to the drawing if it has been deleted
previously in this editing session. Deleted entities are purged from the drawing when the drawing is exited. The entdel function can delete both graphical and nongraphical entities.
Arguments
ename Name of the entity to be deleted or restored.
Return Values
The entity name.
Usage Notes
The entdel function operates only on main entities. Attributes and polyline vertices cannot be deleted independently of their parent entities. You can use the command function to operate the ATTEDIT or PEDIT command in the Command Reference to modify subentities.
You cannot delete entities within a block definition. However, you can completely redefine a block definition, minus the entity you want deleted, with entmake.
Examples
Get the name of the first entity in the drawing and assign it to variable e1:
Command: (setq e1 (entnext)) <Entity name: 2c90520>
Delete the entity named by e1:
AutoLISP Functions | 67
Command: (entdel e1) <Entity name: 2c90520>
Restore the entity named by e1:
Command: (entdel e1) <Entity name: 2c90520>
See also:
The handent (page 114) function.
entget
Retrieves an object's (entity's) definition data
(entget
ename [applist]
)
Arguments
ename Name of the entity being queried. The ename can refer to either a graphical or a nongraphical entity.
applist A list of registered application names.
Return Values
An association list containing the entity definition of ename. If you specify the optional applist argument, entget also returns the extended data associated with the specified applications. Objects in the list are assigned AutoCAD DXF group codes for each part of the entity data.
Note that the DXF group codes used by AutoLISP differ slightly from the group codes in a DXF file. The AutoLISP DXF group codes are documented in the DXF Reference.
Examples
Assume that the last object created in the drawing is a line drawn from point (1,2) to point (6,5). The following example shows code that retrieves the entity name of the last object with the entlast function, and passes that name to
entget:
Command: (entget (entlast))
68 | Chapter 1 AutoLISP Functions
™
((-1 . <Entity name: 1bbd1d0>) (0 . "LINE") (330 . <Entity name: 1bbd0c8>) (5 . "6A") (100 . "AcDbEntity") (67 . 0) (410 . "Model") (8 . "0") (100 . "AcDbLine") (10 1.0 2.0 0.0) (11
6.0 5.0 0.0) (210 0.0 0.0 1.0))
See also:
The entdel (page 67), entlast (page 69), entmod (page 73), entmake (page
70), entnext (page 75), entupd (page 78), and handent (page 114) functions. The Entity Data Functions in the AutoLISP Developer's Guide.
entlast
Returns the name of the last nondeleted main object (entity) in the drawing
(entlast)
The entlast function is frequently used to obtain the name of a new entity that has just been added with the command function. To be selected, the entity need not be on the screen or on a thawed layer.
Return Values
An entity name; otherwise nil, if there are no entities in the current drawing.
Examples
Set variable e1 to the name of the last entity added to the drawing:
Command: (setq e1 (entlast)) <Entity name: 2c90538>
If your application requires the name of the last nondeleted entity (main entity or subentity), define a function such as the following and call it instead of entlast.
(defun lastent (/ a b)
(if (setq a (entlast))
Gets last main entity
(while (setq b (entnext a))
If subentities follow, loops
until there are no more
AutoLISP Functions | 69
(setq a b)
subentities
) ) a
Returns last main entity
)
or subentity
See also:
The entdel (page 67), entget (page 68), entmod (page 73), entnext (page
75), entsel (page 77), and handent (page 114) functions.
entmake
Creates a new entity in the drawing
(entmake
[elist]
)
The entmake function can define both graphical and nongraphical entities.
Arguments
elist A list of entity definition data in a format similar to that returned by the
entget function. The elist argument must contain all of the information
necessary to define the entity. If any required definition data is omitted,
entmake returns nil and the entity is rejected. If you omit optional definition
data (such as the layer), entmake uses the default value.
The entity type (for example, CIRCLE or LINE) must be the first or second field of the elist. If entity type is the second field, it can be preceded only by the entity name. The entmake function ignores the entity name when creating the new entity. If the elist contains an entity handle, entmake ignores that too.
Return Values
70 | Chapter 1 AutoLISP Functions
If successful, entmake returns the entity's list of definition data. If entmake is unable to create the entity, it returns nil.
Completion of a block definition (entmake of an endblk) returns the block's name rather than the entity data list normally returned.
Examples
The following code creates a red circle (color 62), centered at (4,4) with a radius of 1. The optional layer and linetype fields have been omitted and therefore assume default values.
Command: (entmake '((0 . "CIRCLE") (62 . 1) (10 4.0 4.0 0.0) (40 . 1.0))) ((0 . "CIRCLE") (62 . 1) (10 4.0 4.0 0.0) (40 . 1.0))
Notes on Using entmake
You cannot create viewport objects with entmake.
A group 66 code is honored only for insert objects (meaning attributes follow). For polyline entities, the group 66 code is forced to a value of 1 (meaning vertices follow), and for all other entities it takes a default of 0. The only entity that can follow a polyline entity is a vertex entity.
The group code 2 (block name) of a dimension entity is optional for the
entmake function. If the block name is omitted from the entity definition
list, AutoCAD creates a new one. Otherwise, AutoCAD creates the dimension using the name provided.
For legacy reasons, entmake ignores DXF group code 100 data for the following entity types:
■ AcDbText
■ AcDbAttribute
■ AcDbAttributeDefinition
■ AcDbBlockBegin
■ AcDbBlockEnd
■ AcDbSequenceEnd
■ AcDbBlockReference
■ AcDbMInsertBlock
■ AcDb2dVertex
■ AcDb3dPolylineVertex
■ AcDbPolygonMeshVertex
■ AcDbPolyFaceMeshVertex
AutoLISP Functions | 71
■ AcDbFaceRecord
■ AcDb2dPolyline
■ AcDb3dPolyline
■ AcDbArc
■ AcDbCircle
■ AcDbLine
■ AcDbPoint
■ AcDbFace
■ AcDbPolyFaceMesh
■ AcDbPolygonMesh
■ AcDbTrace
■ AcDbSolid
■ AcDbShape
■ AcDbViewport
NOTE In AutoCAD 2004 and later releases, the entmod function has a new behavior in color operations. DXF group code 62 holds AutoCAD Color Index (ACI) values, but code 420 holds true color values. If the true color value and ACI value conflict, AutoCAD uses the 420 value, so the code 420 value should be removed before attempting to use the code 62 value.
See also:
The entdel (page 67), entget (page 68), entmod (page 73), and handent (page 114) functions. In the AutoLISP Developer's Guide, refer to Entity Data Functions for additional information on creating entities in a drawing, Adding an Entity to a Drawing for specifics on using entmake, and Creating Complex Entities for information on creating complex entities.
entmakex
Makes a new object or entity, gives it a handle and entity name (but does not assign an owner), and then returns the new entity name
(entmakex
[elist]
72 | Chapter 1 AutoLISP Functions
)
The entmakex function can define both graphical and nongraphical entities.
Arguments
elist A list of entity definition data in a format similar to that returned by the
entget function. The elist argument must contain all of the information
necessary to define the entity. If any required definition data is omitted,
entmakex returns nil and the entity is rejected. If you omit optional definition
data (such as the layer), entmakex uses the default value.
Return Values
If successful, entmakex returns the name of the entity created. If entmakex is unable to create the entity, the function returns nil.
Examples
(entmakex '((0 . "CIRCLE") (62 . 1) (10 4.0 3.0 0.0) (40 . 1.0)))
<Entity name: 1d45558>
WARNING Objects and entities without owners are not written out to DWG or DXF files. Be sure to set an owner at some point after using entmakex. For
example, you can use dictadd to set a dictionary to own an object.
See also:
The entmake (page 70) and handent (page 114) functions.
entmod
Modifies the definition data of an object (entity)
(entmod
elist
)
The entmod function updates database information for the entity name specified by the -1 group in elist. The primary mechanism through which AutoLISP updates the database is by retrieving entities with entget, modifying the list defining an entity, and updating the entity in the database with
AutoLISP Functions | 73
entmod. The entmod function can modify both graphical and nongraphical
objects.
Arguments
elist A list of entity definition data in a format similar to that returned by the
entget function.
For entity fields with floating-point values (such as thickness), entmod accepts integer values and converts them to floating point. Similarly, if you supply a floating-point value for an integer entity field (such as color number), entmod truncates it and converts it to an integer.
Return Values
If successful, entmod returns the elist supplied to it. If entmod is unable to modify the specified entity, the function returns nil.
Examples
The following sequence of commands obtains the properties of an entity, and then modifies the entity.
Set the en1 variable to the name of the first entity in the drawing:
Command: (setq en1 (entnext)) <Entity name: 2c90520>
Set a variable named ed to the entity data of entity en1:
Command: (setq ed (entget en1)) ((-1 . <Entity name: 2c90520>) (0 . "CIRCLE") (5 . "4C") (100 . "AcDbEntity") (67 . 0) (8 . "0") (100 . "AcDbCircle") (10
3.45373 6.21635 0.0) (40 . 2.94827) (210 0.0 0.0 1.0))
Changes the layer group in ed from layer 0 to layer 1:
Command: (setq ed (subst (cons 8 "1") (assoc 8 ed) ed )) ((-1 . <Entity name: 2c90520>) (0 . "CIRCLE") (5 . "4C") (100 . "AcDbEntity") (67 . 0) (8 . "1") (100 . "AcDbCircle") (10
3.45373 6.21635 0.0) (40 . 2.94827) (210 0.0 0.0 1.0))
Modify the layer of the en1 entity in the drawing:
Command: (entmod ed) ((-1 . <Entity name: 2c90520>) (0 . "CIRCLE") (5 . "4C") (100 . "AcDbEntity") (67 . 0) (8 . "1") (100 . "AcDbCircle") (10
3.45373 6.21635 0.0) (40 . 2.94827) (210 0.0 0.0 1.0))
Restrictions on Using entmod
74 | Chapter 1 AutoLISP Functions
There are restrictions on the changes the entmod function can make:
■ An entity's type and handle cannot be changed. If you want to do this,
use entdel to delete the entity, and then make a new entity with the
command or entmake function.
■ The entmod function cannot change internal fields, such as the entity
name in the -2 group of a seqend entity. Attempts to change such fields
are ignored.
■ You cannot use the entmod function to modify a viewport entity.
You can change an entity's space visibility field to 0 or 1 (except for viewport objects). If you use entmod to modify an entity within a block definition, the modification affects all instances of the block in the drawing.
Before performing an entmod on vertex entities, you should read or write the polyline entity's header. If the most recently processed polyline entity is different from the one to which the vertex belongs, width information (the 40 and 41 groups) can be lost.
WARNING You can use entmod to modify entities within a block definition, but doing so can create a self-referencing block, which will cause AutoCAD to stop.
NOTE In AutoCAD 2004 and later releases, the entmod function has a new behavior in color operations. DXF group code 62 holds AutoCAD Color Index (ACI) values, but code 420 holds true color values. If the true color value and ACI value conflict, AutoCAD uses the 420 value, so the code 420 value should be removed before attempting to use the code 62 value. For more information, perform a full installation of AutoCAD and see the color-util.lsp file located in the \Sample\VisualLISP folder.
See also:
The entdel (page 67), entget (page 68), entmake (page 70), entnext (page
75), and handent (page 114) functions. In the AutoLISP Developer's Guide,
refer to Modifying an Entity and Entity Data Functions and the Graphics
Screen.
entnext
Returns the name of the next object (entity) in the drawing
AutoLISP Functions | 75
(entnext
[ename]
)
Arguments
ename The name of an existing entity.
Return Values
If entnext is called with no arguments, it returns the entity name of the first nondeleted entity in the database. If an ename argument is supplied to entnext, the function returns the entity name of the first nondeleted entity following
ename in the database. If there is no next entity in the database, it returns nil. The entnext function returns both main entities and subentities.
Examples
(setq e1 (entnext)) ;
Sets
e1
to the name of the first entity in
the drawing
(setq e2 (entnext e1)) ;
Sets
e2
to the name of the entity
following
e1
Notes
The entities selected by ssget are main entities, not attributes of blocks or vertices of polylines. You can access the internal structure of these complex entities by walking through the subentities with entnext. Once you obtain a subentity's name, you can operate on it like any other entity. If you obtain the name of a subentity with entnext, you can find the parent entity by stepping forward with entnext until a seqend entity is found, then extracting the -2 group from that entity, which is the main entity's name.
76 | Chapter 1 AutoLISP Functions
See also:
The entdel (page 67), entget (page 68), entmake (page 70), entnext (page
75), and handent (page 114) functions.
entsel
Prompts the user to select a single object (entity) by specifying a point
(entsel
[msg]
)
Arguments
msg A prompt string to be displayed to users. If omitted, entsel prompts with the message, "Select object."
Return Values
A list whose first element is the entity name of the chosen object and whose second element is the coordinates (in terms of the current UCS) of the point used to pick the object.
The pick point returned by entsel does not represent a point that lies on the selected object. The point returned is the location of the crosshairs at the time of selection. The relationship between the pick point and the object will vary depending on the size of the pickbox and the current zoom scale.
Examples
The following AutoCAD command sequence illustrates the use of the entsel function and the list returned:
Command: line From point: 1,1 To point: 6,6
To point: ENTER Command: (setq e (entsel "Please choose an object: ")) Please choose an object: 3,3 (<Entity name: 60000014> (3.0 3.0 0.0))
When operating on objects, you may want to simultaneously select an object and specify the point by which it was selected. Examples of this in AutoCAD can be found in Object Snap and in the BREAK, TRIM, and EXTEND commands
AutoLISP Functions | 77
in the Command Reference. The entsel function allows AutoLISP programs to perform this operation. It selects a single object, requiring the selection to be a pick point. The current Osnap setting is ignored by this function unless you specifically request it while you are in the function. The entsel function honors keywords from a preceding call to initget.
See also:
The entget (page 68), entmake (page 70), entnext (page 75), handent (page
114), and initget (page 118) functions.
entupd
Updates the screen image of an object (entity)
(entupd
ename
)
Arguments
ename The name of the entity to be updated on the screen.
Return Values
The entity (ename) updated; otherwise nil, if nothing was updated.
Examples
Assuming that the first entity in the drawing is a 3D polyline with several vertices, the following code modifies and redisplays the polyline:
(setq e1 (entnext)) ;
Sets
e1
to the polyline's entity name
(setq e2 (entnext e1)) ;
Sets
e2
to its first vertex
78 | Chapter 1 AutoLISP Functions
(setq ed (entget e2)) ;
Sets
ed
to the vertex data
(setq ed
(subst '(10 1.0 2.0)
(assoc 10 ed) ;
Changes the vertex's location in
ed
ed ;
to point (
1,2
)
) ) (entmod ed) ;
Moves the vertex in the drawing
(entupd e1) ;
Regenerates the polyline entity
e1
Updating Polylines and Blocks
When a 3D (or old-style) polyline vertex or block attribute is modified with
entmod, the entire complex entity is not updated on the screen. The entupd
function can be used to cause a modified polyline or block to be updated on the screen. This function can be called with the entity name of any part of the polyline or block; it need not be the head entity. While entupd is intended for polylines and blocks with attributes, it can be called for any entity. It always regenerates the entity on the screen, including all subentities.
NOTE If entupd is used on a nested entity (an entity within a block) or on a block that contains nested entities, some of the entities might not be regenerated. To ensure complete regeneration, you must invoke the REGEN command in the Command Reference.
AutoLISP Functions | 79
See also:
The entget (page 68), entmod (page 73), entnext (page 75), and handent (page 114) functions.
eq
Determines whether two expressions are identical
(eq
expr1 expr2
)
The eq function determines whether expr1 and expr2 are bound to the same object (by setq, for example).
Arguments
expr1 The expression to be compared.
expr2 The expression to compare with expr1.
Return Values
T if the two expressions are identical; otherwise nil.
Examples
Given the following assignments:
(setq f1 '(a b c)) (setq f2 '(a b c)) (setq f3 f2)
Compare f1 and f3:
Command: (eq f1 f3) nil
eq returns nil because f1 and f3, while containing the same value, do not
refer to the same list.
Compare f3 and f2:
Command: (eq f3 f2) T
eq returns T because f3 and f2 refer to the same list.
80 | Chapter 1 AutoLISP Functions
See also:
The = (equal to) (page 5) and equal (page 81) functions.
equal
Determines whether two expressions are equal
(equal
expr1 expr2 [fuzz]
)
Arguments
expr1 The expression to be compared.
expr2 The expression to compare with expr1.
fuzz A real number defining the maximum amount by which expr1 and expr2
can differ and still be considered equal.
When comparing two real numbers (or two lists of real numbers, as in points), the two identical numbers can differ slightly if different methods are used to calculate them. You can specify a fuzz amount to compensate for the difference that may result from the different methods of calculation.
Return Values
T if the two expressions are equal (evaluate to the same value); otherwise nil.
Examples
Given the following assignments:
(setq f1 '(a b c)) (setq f2 '(a b c)) (setq f3 f2) (setq a 1.123456) (setq b 1.123457)
Compare f1 to f3:
Command: (equal f1 f3) T
Compare f3 to f2:
Command: (equal f3 f2)
AutoLISP Functions | 81
T
Compare a to b:
Command: (equal a b) nil
The a and b variables differ by .000001.
Compare a to b:, with fuzz argument of .000001:
Command: (equal a b 0.000001) T
The a and b variables differ by an amount equal to the specified fuzz factor, so equal considers the variables equal.
Comparing the eq and equal Functions
If the eq function finds that two lists or atoms are the same, the equal function also finds them to be the same.
Any atoms that the equal function determines to be the same are also found equivalent by eq. However, two lists that equal determines to be the same may be found to be different according to the eq function.
See also:
The= (equal to) (page 5)and eq (page 80) functions.
*error*
A user-definable error-handling function
(*error*
string
)
If *error* is not nil, it is executed as a function whenever an AutoLISP error condition exists. AutoCAD passes one argument to *error*, which is a string containing a description of the error.
Your *error* function can include calls to the command function without arguments (for example, (command)). This will cancel a previous AutoCAD command called with the command function.
Return Values
82 | Chapter 1 AutoLISP Functions
This function does not return, except when using <Undefined Cross-Reference> (page 227).
Examples
The following function does the same thing that the AutoLISP standard error handler does. It prints the word “error,” followed by a description:
(defun *error* (msg)
(princ "error: ")
(princ msg)
(princ) )
See also:
The vl-exit-with-error (page 226), vl-exit-with-value (page 227), vl-catch-all-
apply (page 216), vl-catch-all-error-message (page 218), and vl-catch-all-error­p (page 219) functions.
eval
Returns the result of evaluating an AutoLISP expression
(eval
expr
)
Arguments
expr The expression to be evaluated.
Return Values
The result of the expression, after evaluation.
Examples
First, set some variables:
Command: (setq a 123) 123 Command: (setq b 'a) A
Now evaluate some expressions:
AutoLISP Functions | 83
Command: (eval 4.0)
4.0 Command: (eval (abs -10)) 10 Command: (eval a) 123 Command: (eval b) 123
exit
Forces the current application to quit
(exit)
If exit is called, it returns the error message quit/exit abort and returns to the AutoCAD Command prompt.
See also:
The quit (page 163) function.
exp
Returns the constant e (a real number) raised to a specified power (the natural antilog)
(exp
num
)
Arguments
num A real number.
Return Values
A real (num), raised to its natural antilogarithm.
Examples
Command: (exp 1.0)
2.71828
84 | Chapter 1 AutoLISP Functions
Command: (exp 2.2)
9.02501 Command: (exp -0.4)
0.67032
expand
Allocates additional memory for AutoLISP
(expand
n-expand
)
Arguments
n-expand An integer indicating the amount of additional memory to be allocated. Memory is allocated as follows:
■ n-alloc free symbols
■ n-alloc free strings
■ n-alloc free usubrs
■ n-alloc free reals
■ n-alloc * n-expand cons cells
where n-alloc is the current segment size.
Return Values
An integer indicating the number of free conses divided by n-alloc.
Examples
Set the segment size to 100:
(alloc 100)
1000
Allocate memory for two additional segments:
(expand 2)
82
This ensures that AutoLISP now has memory available for at least 200 additional symbols, strings, usubrs and reals each, and 8200 free conses.
AutoLISP Functions | 85
See also:
The alloc (page 21) function.
expt
Returns a number raised to a specified power
(expt
number power
)
Arguments
number Any number.
power The power to raise number to.
Return Values
If both arguments are integers, the result is an integer; otherwise, the result is a real.
Examples
Command: (expt 2 4) 16 Command: (expt 3.0 2.0)
9.0

F Functions

findfile
Searches the AutoCAD library path for the specified file or directory
(findfile
filename
)
86 | Chapter 1 AutoLISP Functions
The findfile function makes no assumption about the file type or extension of filename. If filename does not specify a drive/directory prefix, findfile searches the AutoCAD library path. If a drive/directory prefix is supplied,
findfile looks only in that directory.
Arguments
filename Name of the file or directory to be searched for.
Return Values
A string containing the fully qualified file name; otherwise nil, if the specified file or directory is not found.
The file name returned by findfile is suitable for use with the open function.
Examples
If the current directory is / MyUtilities/lsp and it contains the file abc.lsp, the following function call retrieves the path name:
Command: (findfile "abc.lsp") "/MyUtilities/Lsp/abc.lsp"
If you are editing a drawing in the / My Utilities/Support directory, and the ACAD system variable is set to / My Utilities/Support, and the file xyz.txt exists only in the / My Utilities/Support directory, then the following command retrieves the path name:
Command: (findfile "xyz.txt") "/MyUtilities/Support/xyz.txt"
If the file nosuch is not present in any of the directories on the library search path, findfile returns nil:
Command: (findfile "nosuch") nil
fix
Returns the conversion of a real number into the nearest smaller integer
(fix
number
)
The fix function truncates number to the nearest integer by discarding the fractional portion.
AutoLISP Functions | 87
Arguments
number A real number.
Return Values
The integer derived from number.
If number is larger than the largest possible integer (+2,147,483,647 or
-2,147,483,648 on a 32-bit platform), fix returns a truncated real (although integers transferred between AutoLISP and AutoCAD are restricted to 16-bit values).
Examples
Command: (fix 3) 3 Command: (fix 3.7) 3
float
Returns the conversion of a number into a real number
(float
number
)
Arguments
number Any number.
Return Values
The real number derived from number.
Examples
Command: (float 3)
3.0 Command: (float 3.75)
3.75
foreach
Evaluates expressions for all members of a list
88 | Chapter 1 AutoLISP Functions
(foreach
name list [expr
...
]
)
The foreach function steps through a list, assigning each element in the list to a variable, and evaluates each expression for every element in the list. Any number of expressions can be specified.
Arguments
name Variable that each element in the list will be assigned to.
list List to be stepped through and evaluated.
expr Expression to be evaluated for each element in list.
Return Values
The result of the last expr evaluated. If no expr is specified, foreach returns
nil.
Examples
Print each element in a list:
Command: (foreach n '(a b c) (print n)) A B C C
foreach prints each element in the list and returns C, the last element. This
command is equivalent to the following sequence of commands, except that
foreach returns the result of only the last expression evaluated:
(print a) (print b) (print c)
function
Tells the AutoLISP compiler to link and optimize an argument as if it were a built-in function
AutoLISP Functions | 89
(function
symbol | lambda-expr
)
The function function is identical to the quote function, except it tells the AutoLISP compiler to link and optimize the argument as if it were a built-in function or defun.
Arguments
symbol A symbol naming a function.
lambda-expr An expression of the following form:
(LAMBDA arguments {S-expression}* )
Return Values
The result of the evaluated expression.
Examples
The AutoLISP compiler cannot optimize the quoted lambda expression in the following code:
(mapcar
'(lambda (x) (* x x))
'(1 2 3))
After adding the function function to the expression, the compiler can optimize the lambda expression. For example:
(mapcar
(function (lambda (x) (* x x)))
'(1 2 3))

G Functions

gc
Forces a garbage collection, which frees up unused memory
90 | Chapter 1 AutoLISP Functions
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use