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

AutoCAD 2013
AutoLISP Developer's 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 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
AutoLISP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About Related AutoLISP Documents . . . . . . . . . . . . . . . . . 2
Chapter 2 Using the AutoLISP Language . . . . . . . . . . . . . . . . . . . 3
AutoLISP Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
AutoLISP Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 3
AutoLISP Function Syntax . . . . . . . . . . . . . . . . . . . 5
AutoLISP Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 6
Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Reals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Selection Sets . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Entity Names . . . . . . . . . . . . . . . . . . . . . . . . . . 8
File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . 9
Symbols and Variables . . . . . . . . . . . . . . . . . . . . 10
AutoLISP Program Files . . . . . . . . . . . . . . . . . . . . . . . 11
Formatting AutoLISP Code . . . . . . . . . . . . . . . . . . 11
Comments in AutoLISP Program Files . . . . . . . . . . . . 11
AutoLISP Variables . . . . . . . . . . . . . . . . . . . . . . . . . 12
Displaying the Value of a Variable . . . . . . . . . . . . . . 13
iii
Nil Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Predefined Variables . . . . . . . . . . . . . . . . . . . . . . 13
Number Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 14
String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Basic Output Functions . . . . . . . . . . . . . . . . . . . . . . . 16
Displaying Messages . . . . . . . . . . . . . . . . . . . . . 17
Control Characters in Strings . . . . . . . . . . . . . . . . . 18
Wild-Card Matching . . . . . . . . . . . . . . . . . . . . . 20
Equality and Conditional . . . . . . . . . . . . . . . . . . . . . . 21
List Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Point Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Dotted Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Symbol and Function Handling . . . . . . . . . . . . . . . . . . 28
Using defun to Define a Function . . . . . . . . . . . . . . 28
C:XXX Functions . . . . . . . . . . . . . . . . . . . . . . . 30
Local Variables in Functions . . . . . . . . . . . . . . . . . 34
Functions with Arguments . . . . . . . . . . . . . . . . . . 36
Error Handling in AutoLISP . . . . . . . . . . . . . . . . . . . . . 38
Using the *error* Function . . . . . . . . . . . . . . . . . . 39
Catching Errors and Continuing Program Execution . . . . 41
Using AutoLISP to Communicate with AutoCAD . . . . . . . . . . . . 42
Accessing Commands and Services . . . . . . . . . . . . . . . . . 42
Command Submission . . . . . . . . . . . . . . . . . . . . 43
System and Environment Variables . . . . . . . . . . . . . . 47
Configuration Control . . . . . . . . . . . . . . . . . . . . 47
Display Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Control of Graphics and Text Windows . . . . . . . . . . . 48
Control of Low-Level Graphics . . . . . . . . . . . . . . . . 48
Getting User Input . . . . . . . . . . . . . . . . . . . . . . . . . 49
The getxxx Functions . . . . . . . . . . . . . . . . . . . . . 49
Control of User-Input Function Conditions . . . . . . . . . 52
Geometric Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 55
Object Snap . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Text Extents . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
String Conversions . . . . . . . . . . . . . . . . . . . . . . 61
Angular Conversion . . . . . . . . . . . . . . . . . . . . . . 64
ASCII Code Conversion . . . . . . . . . . . . . . . . . . . . 65
Unit Conversion . . . . . . . . . . . . . . . . . . . . . . . 67
Coordinate System Transformations . . . . . . . . . . . . . 70
File Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
File Search . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Device Access and Control . . . . . . . . . . . . . . . . . . . . . 74
Accessing User Input . . . . . . . . . . . . . . . . . . . . . 74
Using AutoLISP to Manipulate AutoCAD Objects . . . . . . . . . . . . 74
Selection Set Handling . . . . . . . . . . . . . . . . . . . . . . . 75
iv | Contents
Selection Set Filter Lists . . . . . . . . . . . . . . . . . . . . 77
Passing Selection Sets between AutoLISP and ObjectARX
Applications . . . . . . . . . . . . . . . . . . . . . . . . . 85
Object Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Entity Name Functions . . . . . . . . . . . . . . . . . . . . 86
Entity Data Functions . . . . . . . . . . . . . . . . . . . . . 92
Entity Data Functions and the Graphics Screen . . . . . . . 102
Old-Style Polylines and Lightweight Polylines . . . . . . . 103
Non-Graphic Object Handling . . . . . . . . . . . . . . . 104
Extended Data - xdata . . . . . . . . . . . . . . . . . . . . . . . 106
Organization of Extended Data . . . . . . . . . . . . . . . 107
Registration of an Application . . . . . . . . . . . . . . . . 109
Retrieval of Extended Data . . . . . . . . . . . . . . . . . 110
Attachment of Extended Data to an Entity . . . . . . . . . 111
Management of Extended Data Memory Use . . . . . . . . 112
Handles in Extended Data . . . . . . . . . . . . . . . . . . 112
Xrecord Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Symbol Table and Dictionary Access . . . . . . . . . . . . . . . 114
Symbol Tables . . . . . . . . . . . . . . . . . . . . . . . . 114
Dictionary Entries . . . . . . . . . . . . . . . . . . . . . . 116
Chapter 3 Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
AutoLISP Function Synopsis . . . . . . . . . . . . . . . . . . . . . . . 119
Category Summary . . . . . . . . . . . . . . . . . . . . . . . . . 119
Basic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Application-Handling Functions . . . . . . . . . . . . . . 121
Arithmetic Functions . . . . . . . . . . . . . . . . . . . . 122
Equality and Conditional Functions . . . . . . . . . . . . 125
Error-Handling Functions . . . . . . . . . . . . . . . . . . 126
Function-Handling Functions . . . . . . . . . . . . . . . . 127
List Manipulation Functions . . . . . . . . . . . . . . . . 128
String-Handling Functions . . . . . . . . . . . . . . . . . 131
Symbol-Handling Functions . . . . . . . . . . . . . . . . . 133
Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Conversion Functions . . . . . . . . . . . . . . . . . . . . 134
Device Access Functions . . . . . . . . . . . . . . . . . . . 135
Display Control Functions . . . . . . . . . . . . . . . . . . 136
File-Handling Functions . . . . . . . . . . . . . . . . . . . 137
Geometric Functions . . . . . . . . . . . . . . . . . . . . 139
Query and Command Functions . . . . . . . . . . . . . . 139
User Input Functions . . . . . . . . . . . . . . . . . . . . 141
Selection Set, Object, and Symbol Table Functions . . . . . . . . 142
Extended Data-Handling Functions . . . . . . . . . . . . . 143
Object-Handling Functions . . . . . . . . . . . . . . . . . 143
Selection Set Manipulation Functions . . . . . . . . . . . . 145
Symbol Table and Dictionary-Handling Functions . . . . . 146
Contents | v
Memory Management Functions . . . . . . . . . . . . . . . . . 147
VLX Namespace Functions . . . . . . . . . . . . . . . . . . . . 147
Namespace Communication Functions . . . . . . . . . . . . . . 148
Property List (Plist) Functions . . . . . . . . . . . . . . . . . . . 149
AutoLISP Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
vi | Contents

Introduction

Introduction

For years, AutoLISP® has set the standard for customizing AutoCAD® on Windows®. AutoCAD also supports AutoLISP, but does not support many of
the Visual LISP functions or the Microsoft ActiveX® Automation interface. AutoCAD does not have an integrated development environment like AutoCAD on Windows does, so the creation and editing of LSP files must be done with text editor such as TextEdit.

AutoLISP

AutoLISP is a programming language designed for extending and customizing the functionality of AutoCAD. It is based on the LISP programming language, whose origins date back to the late 1950s. LISP was originally designed for use in Artificial Intelligence (AI) applications, and is still the basis for many AI applications.
1
AutoLISP was introduced as an application programming interface (API) in AutoCAD Release 2.1, in the mid-1980s. LISP was chosen as the initial AutoCAD API because it was uniquely suited for the unstructured design process of AutoCAD projects, which involved repeatedly trying different solutions to design problems.
Developing AutoLISP programs for AutoCAD is done by writing code in a text editor, then loading the code into AutoCAD and running it. Debugging your program is handled by adding statements to print the contents of variables at strategic points in your program. You must figure out where in your program to do this, and what variables you need to look at. If you discover you do not have enough information to determine the error, you must go back and change
1
the code by adding more debugging points. And finally, when you get the program to work correctly, you need to either comment out or remove the debugging code you added.

About Related AutoLISP Documents

In addition to the AutoLISP Reference, several other AutoCAD publications may be required by users building applications with AutoLISP:
■ AutoCADCustomization Guide contains basic information on creating
customized AutoCAD applications. For example, it includes information on creating customized user interface elements, linetypes, and hatch patterns. The Customization Guide is available through the AutoCAD and Help menu on the Mac OS menu bar.
■ The DXF Reference describes drawing interchange format (DXF
DXF group codes that identify attributes of AutoCAD objects.
The DXF Reference is not included when you install AutoCAD. To obtain the manual, download the DXF Reference from www.autodesk.com.
■ The ObjectARX Reference contains information on using ObjectARX
develop customized AutoCAD applications. AutoCAD reactor functionality is implemented through ObjectARX. If you develop AutoLISP applications that implement reactor functions, you may want to refer to this manual.
The ObjectARX Reference is not included when you install AutoCAD. To obtain the manual, download the ObjectARX SDK (Software Development Kit) from www.autodesk.com.
TM
) and the
®
to
2 | Chapter 1 Introduction
Using the AutoLISP Lan­guage

AutoLISP Basics

You can use number, string, and list-handling functions to customize AutoCAD.
This chapter introduces the basic concepts of the AutoLISP® programming language. It describes the core components and data types used in AutoLISP, and presents examples of simple number-, string-, output-, and list-handling functions.
AutoLISP code does not need to be compiled, so you can enter the code at a Command line and immediately see the results.
2

AutoLISP Expressions

An AutoLISP program consists of a series of expressions. AutoLISP expressions have the following form:
(function
arguments
)
Each expression begins with an open (left) parenthesis and consists of a function name and optional arguments to that function. Each argument can also be an expression. The expression ends with a right parenthesis. Every expression returns a value that can be used by a surrounding expression. The value of the last interpreted expression is returned to the calling expression.
For example, the following code example involves three functions:
3
(fun1 (fun2
arguments)(fun3 arguments)
)
If you enter this code at the AutoCAD Command prompt, the AutoCAD AutoLISP interpreter processes the code. The first function, fun1, has two arguments, and the other functions, fun2 and fun3, each have one argument. The functions fun2 and fun3 are surrounded by function fun1, so their return values are passed to fun1 as arguments. Function fun1 evaluates the two arguments and returns the value to the window from which you entered the code.
The following example shows the use of the * (multiplication) function, which accepts one or more numbers as arguments:
(* 2 27)
54
Because this code example has no surrounding expression, AutoLISP returns the result to the window from which you entered the code.
Expressions nested within other expressions return their result to the surrounding expression. The following example uses the result from the + (addition) function as one of the arguments for the * (multiplication) function.
(* 2 (+ 5 10))
30
If you enter the incorrect number of close (right) parentheses, AutoLISP displays the following prompt:
(_>
The number of open parentheses in this prompt indicates how many levels of open parentheses remain unclosed. If this prompt appears, you must enter the required number of close parentheses for the expression to be evaluated.
(* 2 (+ 5 10
((_>
) )
30
4 | Chapter 2 Using the AutoLISP Language
A common mistake is to omit the closing quotation mark (") in a text string, in which case the close parentheses are interpreted as part of the string and have no effect in resolving the open parentheses. To correct this condition, press Shift+Esc to cancel the function, then re-enter it correctly.
AutoLISP Function Syntax
In this guide, the following conventions describe the syntax for AutoLISP functions:
In this example, the foo function has one required argument, string, and one optional argument, number. Additional number arguments can be provided. Frequently, the name of the argument indicates the expected data type. The examples in the following table show both valid and invalid calls to the foo function.
Valid and invalid function call examples
Invalid callsValid calls
(foo 44 13)(foo "catch")
(foo "fi" "foe" 44 13)(foo "catch" 22)
(foo)(foo "catch" 22 31)
AutoLISP Basics | 5

AutoLISP Data Types

AutoLISP expressions are processed according to the order and data type of the code within the parentheses. Before you can fully utilize AutoLISP, you must understand the differences among the data types and how to use them.
Integers
Integers are whole numbers that do not contain a decimal point. AutoLISP integers are 32-bit signed numbers with values ranging from +2,147,483,647 to -2,147,483,648. (Note, however, that the getint function only accepts 16-bit numbers ranging from +32767 to -32678.) When you explicitly use an integer in an AutoLISP expression, that value is known as a constant. Numbers such as 2, -56, and 1,200,196 are valid AutoLISP integers.
If you enter a number that is greater than the maximum integer allowed (resulting in integer overflow), AutoLISP converts the integer to a real number. However, if you perform an arithmetic operation on two valid integers, and the result is greater than the maximum allowable integer, the resulting number will be invalid. The following examples illustrate how AutoLISP handles integer overflow.
The largest positive integer value retains its specified value:
2147483647
2147483647
If you enter an integer that is greater than the largest allowable value, AutoLISP returns the value as a real:
2147483648
2.14748e+009
An arithmetic operation involving two valid integers, but resulting in integer overflow, produces an invalid result:
(+ 2147483646 3)
-2147483647
6 | Chapter 2 Using the AutoLISP Language
In this example the result is clearly invalid, as the addition of two positive numbers results in a negative number. But note how the following operation produces a valid result:
(+ 2147483648 2)
2.14748e+009
In this instance, AutoLISP converts 2147483648 to a valid real before adding 2 to the number. The result is a valid real.
The largest negative integer value retains its specified value:
-2147483647
-2147483647
If you enter a negative integer larger than the greatest allowable negative value, AutoLISP returns the value as a real:
-2147483648
-2.14748e+009
The following operation concludes successfully, because AutoLISP first converts the overflow negative integer to a valid real:
(- -2147483648 1)
-2.14748e+009
Reals
A real is a number containing a decimal point. Numbers between -1 and 1 must contain a leading zero. Real numbers are stored in double-precision floating-point format, providing at least 14 significant digits of precision.
Reals can be expressed in scientific notation, which has an optional e or E followed by the exponent of the number (for example, 0.0000041 is the same as 4.1e-6). Numbers such as 3.1, 0.23, -56.123, and 21,000,000.0 are valid AutoLISP reals.
AutoLISP Basics | 7
Strings
A string is a group of characters surrounded by quotation marks. Within quoted strings the backslash (\) character allows control characters (or escape codes) to be included. When you explicitly use a quoted string in an AutoLISP expression, that value is known as a literal string or a string constant.
Examples of valid strings are “string 1” and “\nEnter first point:”.
Lists
An AutoLISP list is a group of related values separated by spaces and enclosed in parentheses. Lists provide an efficient method of storing numerous related values. AutoCAD expresses 3D points as a list of three real numbers.
Examples of lists are (1.0 1.0 0.0), (“this” “that” “the other”), and (1 “ONE”).
Selection Sets
Selection sets are groups of one or more objects (entities). You can interactively add objects to, or remove objects from, selection sets with AutoLISP routines.
The following example uses the ssget function to return a selection set containing all the objects in a drawing.
(ssget "X")
<Selection set: 1>
Entity Names
An entity name is a numeric label assigned to objects in a drawing. It is actually a pointer into a file maintained by AutoCAD, and can be used to find the object's database record and its vectors (if they are displayed). This label can be referenced by AutoLISP functions to allow selection of objects for processing in various ways. Internally, AutoCAD refers to objects as entities.
The following example uses the entlast function to get the name of the last object entered into the drawing.
8 | Chapter 2 Using the AutoLISP Language
(entlast)
<Entity name: 27f0540>
Entity names assigned to objects in a drawing are only in effect during the current editing session. The next time you open the drawing, AutoCAD assigns new entity names to the objects. You can use an object's handle to refer to it from one editing session to another; see Entity Handles and Their Uses (page
87) for information on using handles.
File Descriptors
A file descriptor is a pointer to a file opened by the AutoLISP open function. The open function returns this pointer as an alphanumeric label. You supply the file descriptor as an argument to other AutoLISP functions that read or
write to the file.
The following example opens the myinfo.dat file for reading. The open function returns the file descriptor:
(setq file1 (open "/myinfo.dat" "r") )
#<file "/myinfo.dat">
In this example, the file descriptor is stored in the file1variable.
Files remain open until you explicitly close them in your AutoLISP program. The close function closes a file. The following code closes the file whose file descriptor is stored in the file1 variable:
(close file1)
nil
AutoLISP Basics | 9
Symbols and Variables
AutoLISP uses symbols to refer to data. Symbol names are not case sensitive and may consist of any sequence of alphanumeric and notation characters, except the following:
Characters restricted from symbol names
(
)
.
'
"
;
(Open Parenthesis)
(Close Parenthesis)
(Period)
(Apostrophe)
(Quote Symbol)
(Semicolon)
A symbol name cannot consist only of numeric characters.
Technically, AutoLISP applications consist of either symbols or constant values, such as strings, reals, and integers. For the sake of clarity, this guide uses the term symbol to refer to a symbol name that stores static data, such as built-in and user-defined functions. The term variable is used to refer to a symbol name that stores program data. The following example uses the setq function to assign the string value "this is a string" to the str1 variable:
(setq str1 "this is a string")
"this is a string"
Help yourself and others who need to read your code. Choose meaningful names for your program symbols and variables.
10 | Chapter 2 Using the AutoLISP Language

AutoLISP Program Files

Although you can enter AutoLISP code at the AutoCAD Command prompt, testing and debugging a series of instructions are considerably easier when you save AutoLISP code in a file rather than re-entering it each time you make a refinement. AutoLISP source code is usually stored in ASCII text files with an .lsp extension. However, you can load AutoLISP code from any ASCII text file.
Formatting AutoLISP Code
The extensive use of parentheses in AutoLISP code can make it difficult to read. The traditional technique for combatting this confusion is indentation. The more deeply nested a line of code is, the farther to the right you position the line.
Spaces in AutoLISP Code
In AutoLISP, multiple spaces between variable names, constants, and function names are equivalent to a single space. The end of a line is also treated as a single space.
The following two expressions produce the same result:
(setq test1 123 test2 456) (setq
test1 123 test2 456
)
Comments in AutoLISP Program Files
It is good practice to include comments in AutoLISP program files. Comments are useful to both the programmer and future users who may need to revise a program to suit their needs. Use comments to do the following:
■ Give a title, authorship, and creation date
■ Provide instructions on using a routine
■ Make explanatory notes throughout the body of a routine
AutoLISP Basics | 11
■ Make notes to yourself during debugging
Comments begin with one or more semicolons (;) and continue through the end of the line.
; This entire line is a comment (setq area (* pi r r)) ; Compute area of circle
Any text within ;| ... |; is ignored. Therefore, comments can be included within a line of code or extend for multiple lines. This type of comment is known as an in-line comment.
(setq tmode ;|some note here|; (getvar "tilemode"))
The following example shows a comment that continues for multiple lines:
(setvar "orthomode" 1) ;|comment starts here and continues to this line, but ends way down here|; (princ "\nORTHOMODE set On.")
It is recommended that you use comments liberally when writing AutoLISP programs.

AutoLISP Variables

An AutoLISP variable assumes the data type of the value assigned to it. Until they are assigned new values, variables retain their original values. You use the AutoLISP setq function to assign values to variables.
(setq
variable_name1 value1 [variable_name2 value2 ...]
)
The setq function assigns the specified value to the variable name given. It returns the value as its function result.
(setq val 3 abc 3.875)
3.875
(setq layr "EXTERIOR-WALLS")
"EXTERIOR-WALLS"
12 | Chapter 2 Using the AutoLISP Language
Displaying the Value of a Variable
To display the value of a variable from the AutoCAD Command prompt, you must precede the variable name with an exclamation point (!). For example:
!abc
3.875
Nil Variables
An AutoLISP variable that has not been assigned a value is said to be nil. This is different from blank, which is considered a character string, and different from 0, which is a number. So, in addition to checking a variable for its current value, you can test to determine if the variable has been assigned a value.
Each variable consumes a small amount of memory, so it is good programming practice to reuse variable names or set variables to nil when their values are no longer needed. Setting a variable to nil releases the memory used to store that variable's value. If you no longer need the val variable, you can release its value from memory with the following expression:
(setq val nil)
nil
Another efficient programming practice is to use local variables whenever possible. See Local Variables in Functions (page 34) on this topic.
Predefined Variables
The following predefined variables are commonly used in AutoLISP applications:
PAUSE Defined as a string consisting of a double backslash (\\) character. This
variable is used with the command function to pause for user input.
PI Defined as the constant p (pi). It evaluates to approximately 3.14159.
T Defined as the constant T. This is used as a non-nil value.
AutoLISP Basics | 13
NOTE You can change the value of these variables with the setq function. However,
other applications might rely on their values being consistent; therefore, it is recommended that you do not modify these variables.

Number Handling

AutoLISP provides functions for working with integers and real numbers. In addition to performing complex mathematical computations in applications, you can use the number-handling functions to help you in your daily use of AutoCAD. If you are drawing a steel connection detail that uses a 2.5" bolt that is 0.5" in diameter, how many threads are there if the bolt has 13 threads per inch?
(* 2.5 13)
32.5
The arithmetic functions that have a number argument (as opposed to num or
angle, for example) return different values if you provide integers or reals as
arguments. If all arguments are integers, the value returned is an integer. However, if one or all the arguments are reals, the value returned is a real. To ensure your application passes real values, be certain at least one argument is a real.
(/ 12 5)
2
(/ 12.0 5)
2.4
A complete list of number-handling functions is in AutoLISP Function Synopsis, (page 119) under the heading Arithmetic Functions. (page 122) These functions are described in the AutoLISP Reference.

String Handling

AutoLISP provides functions for working with string values. For example, the
strcase function returns the conversion of all alphabetic characters in a string
to uppercase or lowercase. It accepts two arguments: a string and an optional
14 | Chapter 2 Using the AutoLISP Language
argument that specifies the case in which the characters are returned. If the optional second argument is omitted, it evaluates to nil and strcase returns the characters converted to uppercase.
(strcase "This is a TEST.")
"THIS IS A TEST."
If you provide a second argument of T, the characters are returned as lowercase. AutoLISP provides the predefined variable T to use in similar situations where a non-nil value is used as a type of true/false toggle.
(strcase "This is a TEST." T)
"this is a test."
The strcat function combines multiple strings into a single string value. This is useful for placing a variable string within a constant string. The following code sets a variable to a string value and then uses strcat to insert that string into the middle of another string.
(setq str "BIG") (setq bigstr (strcat "This is a " str " test."))
"This is a BIG test."
If the variable bigstr is set to the preceding string value, you can use the
strlen function to find out the number of characters (including spaces) in that
string.
(strlen bigstr)
19
The substr function returns a substring of a string. It has two required arguments and one optional argument. The first required argument is the string. The second argument is a positive integer that specifies the first character of the string you want to include in the substring. If the third argument is provided, it specifies the number of characters to include in the substring. If the third argument is not provided, substr returns all characters including and following the specified start character.
As an example, you can use the substr function to strip off the three-letter extension from a file name (note that you can actually use the vl-filename-base function to do this). First, set a variable to a file name.
AutoLISP Basics | 15
(setq filnam "bigfile.txt")
"bigfile.txt"
You need to get a string that contains all characters except the last four (the period and the three-letter extension). Use strlen to get the length of the string and subtract 4 from that value. Then use substr to specify the first character of the substring and its length.
(setq newlen (- (strlen filnam) 4))
7
(substr filnam 1 newlen)
"bigfile"
If your application has no need for the value of newlen, you can combine these two lines of code into one.
(substr filnam 1 (- (strlen filnam) 4))
"bigfile"
Additional string-handling functions are listed in AutoLISP Function Synopsis, (page 119) under the heading String-Handling Functions. (page 131) These functions are described in the AutoLISP Reference.
AutoLISP also provides a number of functions that convert string values into numeric values and numeric values into string values. These functions are discussed in Conversions (page 61).

Basic Output Functions

AutoLISP includes functions for controlling the AutoCAD display, including both text and graphics windows. The major text display functions are:
■ prin1
■ princ
■ print
■ prompt
16 | Chapter 2 Using the AutoLISP Language
These functions are discussed in the following sections. The remaining display functions are covered in Using AutoLISP to Communicate with AutoCAD (page 42), beginning with the Display Control (page 47) topic.
Displaying Messages
The princ, prin1, and print functions all display an expression (not necessarily a string) in the AutoCAD Command window. Optionally, these functions can send output to a file. The differences are as follows:
■ princ displays strings without the enclosing quotation marks.
■ prin1 displays strings enclosed in quotation marks.
■ print displays strings enclosed in quotation marks but places a blank line
before the expression and a space afterward.
The following examples demonstrate the differences between the four basic output functions and how they handle the same string of text. See Control
Characters in Strings (page 18) for an explanation of the control characters
used in the example.
(setq str "The \"allowable\" tolerance is \261 \274\"") (prompt str)
printsThe "allowable" tolerance is 1/4"and returns nil
(princ str) printsThe "allowable" tolerance is 1/4"and returns "The \"allowable\" tolerance is 1/4\""
(prin1 str) prints"The \"allowable\" tolerance is 1/4""and returns "The \"allowable\" tolerance is 1/4\""
(print str)
prints<blank line>"The \"allowable\" tolerance is 1/4""<space>and returns "The \"allowable\" tolerance is
1/4\""
Note that the write-char and write-line functions can also display output to a Command window. Refer to the AutoLISP Reference for information on these functions.
AutoLISP Basics | 17
Exiting Quietly
If you invoke the princ function without passing an expression to it, it displays nothing and has no value to return. So if you write an AutoLISP expression that ends with a call to princ without any arguments, the ending nil is suppressed (because it has nothing to return). This practice is called exiting quietly.
Control Characters in Strings
Within quoted strings, the backslash (\) character allows control characters (or escape codes) to be included. The following table shows the currently recognized control characters:
AutoLISP control characters
DescriptionCode
\ character\\
" character\"
Escape character\e
Newline character\n
Return character\r
Tab character\t
\nnn
The prompt and princ functions expand the control characters in a string and display the expanded string in the AutoCAD Command window.
If you need to use the backslash character (\) or quotation mark (") within a quoted string, it must be preceded by the backslash character (\). For example, if you enter
Character whose octal code is nnn
18 | Chapter 2 Using the AutoLISP Language
(princ "The \"filename\" is: /ACAD/TEST.TXT.")
the following text is displayed in the AutoCAD Command window:
The "filename" is: /ACAD/TEST.TXT
You will also see this output in the VLISP Console window, along with the return value from the princ function (which is your original input, with the unexpanded control characters).
To force a line break at a specific location in a string, use the newline character (\n).
(prompt "An example of the \nnewline character. ")
An example of the newline character.
You can also use the terpri function to cause a line break.
The return character (\r) returns to the beginning of the current line. This is useful for displaying incremental information (for example, a counter showing the number of objects processed during a loop).
The Tab character (\t) can be used in strings to indent or to provide alignment with other tabbed text strings. In this example, note the use of the princ function to suppress the ending nil.
(prompt "\nName\tOffice\n- - - - -\t- - - - -
(_>
\nSue\t101\nJoe\t102\nSam\t103\n") (princ)
OfficeName
- - - - -- - - - -
101Sue
102Joe
103Sam
AutoLISP Basics | 19
Wild-Card Matching
The wcmatch function enables applications to compare a string to a wild-card pattern. You can use this facility when you build a selection set (in conjunction with ssget) and when you retrieve extended entity data by application name (in conjunction with entget).
The wcmatch function compares a single string to a pattern. The function returns T if the string matches the pattern, and nil if it does not. The wild-card patterns are similar to the regular expressions used by many system and application programs. In the pattern, alphabetic characters and numerals are treated literally; brackets can be used to specify optional characters or a range of letters or digits; a question mark (?) matches a single character; an asterisk (*) matches a sequence of characters; and, certain other special characters have special meanings within the pattern. When you use the * character at the beginning and end of the search pattern, you can locate the desired portion anywhere in the string.
In the following examples, a string variable called matchme has been declared and initialized:
(setq matchme "this is a string - test1 test2 the end")
"this is a string - test1 test2 the end"
The following code checks whether or not matchme begins with the four characters "this":
(wcmatch matchme "this*")
T
The following code illustrates the use of brackets in the pattern. In this case,
wcmatch returns T if matchme contains "test4", "test5", "test6" (4-6), or "test9" (note the use of the * character):
(wcmatch matchme "*test[4-69]*")
nil
In this case, wcmatch returns nil because matchme does not contain any of the strings indicated by the pattern.
However,
20 | Chapter 2 Using the AutoLISP Language
(wcmatch matchme "*test[4-61]*")
T
returns true because the string contains "test1".
The pattern string can specify multiple patterns, separated by commas. The following code returns T if matchme equals "ABC", or if it begins with "XYZ", or if it ends with "end".
(wcmatch matchme "ABC,XYZ*,*end")
T

Equality and Conditional

AutoLISP includes functions that provide equality verification as well as conditional branching and looping. The equality and conditional functions are listed in AutoLISP Function Synopsis, (page 119) under the heading Equality
and Conditional Functions. (page 125) These functions are described in the
AutoLISP Reference.
When writing code that checks string and symbol table names, keep in mind that AutoLISP automatically converts symbol table names to upper case in some instances. When testing symbol names for equality, you need to make the comparison insensitive to the case of the names. Use the strcase function to convert strings to the same case before testing them for equality.

List Handling

AutoLISP provides functions for working with lists. This section provides examples of the append, assoc, car, cons, list, nth, and subst functions. A summary of all list-handling functions is in AutoLISP Function Synopsis, (page
119) under the heading List Manipulation Functions. (page 128) Each list-handling function is described in the AutoLISP Reference.
Lists provide an efficient and powerful method of storing numerous related values. After all, LISP is so-named because it is the LISt Processing language. Once you understand the power of lists, you'll find that you can create more powerful and flexible applications.
AutoLISP Basics | 21
Several AutoLISP functions provide a basis for programming two-dimensional and three-dimensional graphics applications. These functions return point values in the form of a list.
The list function provides a simple method of grouping related items. These items do not need to be of similar data types. The following code groups three related items as a list:
(setq lst1 (list 1.0 "One" 1))
(1.0 "One" 1)
You can retrieve a specific item from the list in the lst1 variable with the nth function. This function accepts two arguments. The first argument is an integer that specifies which item to return. A 0 specifies the first item in a list, 1 specifies the second item, and so on. The second argument is the list itself. The following code returns the second item in lst1.
(nth 1 lst1)
"One"
The cdr function returns all elements, except the first, from a list. For example:
(cdr lst1)
("One" 1)
The car function provides another way to extract items from a list. For more examples using car and cdr, and combinations of the two, see Point Lists (page 23).
Three functions let you modify an existing list. The append function returns a list with new items added to the end of it, and the cons function returns a list with new items added to the beginning of the list. The subst function returns a list with a new item substituted for every occurrence of an old item.
These functions do not modify the original list; they return a modified list. To modify the original list, you must explicitly replace the old list with the new list.
The append function takes any number of lists and runs them together as one list. Therefore, all arguments to this function must be lists. The following code adds another "One" to the list lst1. Note the use of the quote (or ') function as an easy way to make the string "One" into a list.
22 | Chapter 2 Using the AutoLISP Language
(setq lst2 (append lst1 '("One")))
(1.0 "One" 1 "One")
The cons function combines a single element with a list. You can add another string "One" to the beginning of this new list, lst2, with the cons function.
(setq lst3 (cons "One" lst2 ))
("One" 1.0 "One" 1 "One")
You can substitute all occurrences of an item in a list with a new item with the subst function. The following code replaces all strings "One" with the string "one".
(setq lst4 (subst "one" "One" lst3))
("one" 1.0 "one" 1 "one")
Point Lists
AutoLISP observes the following conventions for handling graphics coordinates. Points are expressed as lists of two or three numbers surrounded by parentheses.
2D points Expressed as lists of two real numbers (X and Y, respectively), as in
(3.4 7.52)
3D points Expressed as lists of three real numbers (X, Y, and Z, respectively), as in
(3.4 7.52 1.0)
You can use the list function to form point lists, as shown in the following examples:
(list 3.875 1.23)
(3.875 1.23)
(list 88.0 14.77 3.14)
(88.0 14.77 3.14)
AutoLISP Basics | 23
To assign particular coordinates to a point variable, you can use one of the following expressions:
(setq pt1 (list 3.875 1.23))
(3.875 1.23)
(setq pt2 (list 88.0 14.77 3.14))
(88.0 14.77 3.14)
(setq abc 3.45)
3.45
(setq pt3 (list abc 1.23))
(3.45 1.23)
The latter uses the value of variable abc as the X component of the point.
If all members of a list are constant values, you can use the quote function to explicitly define the list, rather than the list function. The quote function returns an expression without evaluation, as follows:
(setq pt1 (quote (4.5 7.5)))
(4.5 7.5)
The single quotation mark (') can be used as shorthand for the quote function. The following code produces the same result as the preceding code.
(setq pt1 '(4.5 7.5))
(4.5 7.5)
You can refer to X, Y, and Z components of a point individually, using three additional built-in functions called car, cadr, and caddr. The following examples show how to extract the X, Y, and Z coordinates from a 3D point list. The pt variable is set to the point (1.5 3.2 2.0):
(setq pt '(1.5 3.2 2.0))
(1.5 3.2 2.0)
24 | Chapter 2 Using the AutoLISP Language
Loading...
+ 148 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use