AutoLISP 1.02 - Definitions and Getting Started

AutoLISP is a programming language embedded inside AutoCAD.

AutoLISP code does not need to be compiled, so you can enter the code at a Command line and immediately see the results.

 

Definitions 

Function is a pre-defined set of instructions that can perform a specific task in AutoCAD

            Example

                        * = multiple, + = add,

 

Arguments - the values passed to a function for manipulation

            Example

                        (* 2 4) = multiply the arguments 2 and 4 to return the answer 8

                        (* 2 4 6) = multiply the arguments 2, 4 & 6 to return 48

                        (* 2 4 6.0) = multiply the arguments 2, 4 & 6.0 to return 48.0

                        In the first two cases the arguments are integers, therefore the answers are integers

                        In the third case, one of the arguments is a real number, therefore the answer is a real number

 

Expressions - AutoLISP code to be evaluated 

 

Local Variables - Variables that are only valid a specific function and while the function is running

Global Variables - Variables that are available to all functions during a session of AutoCAD

 

AutoLISP Function Syntax

            (MyFunction Argument1 [Argument2 ....])

                        (                       left "open" parentheses

                        MyFunction      name of the function

                        Argument1        required argument

                        [Argument2       optional arguments in brackets

                        ....                    possible additional arguments denoted by ellipsis

                        )                       right "close" parentheses

 

AutoLISP Function Example

            (foreach name list [expr...])

                        The foreach function steps through a list

                                    assigns each element in the list to the variable name

                                    evaluates each expression for every element in the list

                        foreach returns the last expression evaluated in the list,

                                    or if no expression is specified, foreach returns nil.

            Example

                        Command: (foreach NUMBER (list 1 2 3) (princ NUMBER))

                        returns to the command prompt

                        1

                        2

                        33         (note the function prints the 3 and returns 3 to the command prompt when finished)

 

Data types in AutoLISP

            Integer = whole numbers between -2,147,483,648 and 2,147, 483,647

                        Notes -

                                    The getint function only allows whole numbers between -32,767 and 32678

                                    If an integer is entered that is greater than the largest number allowed,

                                                AutoLISP converts the number to a real

                                    If use perform an arithmetic operation on 2 valid integers ,

                                                and the result is greater than the largest integer, AutoLISP returns nil

                        Examples - 0, 1, -1, 12345789

 

            Real = a number containing a decimal point

                        Notes -

                                    Numbers between -1 and 1 must contain a leading zero

                                    Numbers are stored to 14 significant digits of precision

                                                For information about significant digits of  precision see

                                                            http://mathforum.org/library/drmath/view/58335.html

                        Examples - 0.0, -0.01, 1.1234, 123456789.12345, 4.1e-6 (Scientific notation for 0.0000041)

 

            String = a group of characters surrounded by quotation marks

                        Notes -

                                    Strings are typically numbers and letters, but may contain any ASCII character

                        Examples = "This is a String", "1234", "String1234"

 

            Lists = a group of related values separated by spaces and enclosed in parentheses

                        Notes -

                                    Lists are an efficient method of storing multiple related values like point coordinates

                        Examples - (1.0 2.0 0.0), ("String1" "String2" "String4"), (1 "A" "1A")

 

            Selection Sets = a group of one or more objects (entities)

                        Notes -

                                    You can interactively add objects to or remove objects from the selection set

 

            Entity Names = a numeric label assigned to every object (entity) in the drawing

                        Notes -

                                    This is an efficient method of obtaining the information about an object in the drawing

 

            File Descriptors = a pointer to a file opened in AutoLISP by the open function

                        Notes -

                                    File Descriptors are used to read or write to ASCII based files

 

Symbols and Variables

Symbols and Variables are a named symbol that stores program data

            Notes -

                        Symbols are typically static data (example - user defined function, *, T)

                        Variable names are not case-sensitive

                        Variable names can be any combination of alphanumeric and notation characters except -

                                    (           = open parentheses

                                    )           = close parentheses

                                    .           = period

                                    '            = apostrophe

                                    "           = quote mark

                                    ;           = semicolon

                        Variable symbol names cannot   consist of only numeric characters

                        Please use meaningful names for your variable names to make the program easier to read!

 

Predefined Variables

T this variable is the constant TRUE, used as a non-nil value
nil this variable is the constant NIL, used as a non-T value
pi this variable is the constant for the ratio of the circumference to the diameter of a circle
pause this variable is used with the command function to pause for user input

             Note - these variables can be changed by the setq function, but it is highly recommended that you don't!           

 

Comments

; (semicolon) is used to denote comments in a program

            Example -

                        ; this is a commented line, explaining the program

 

Visual LISP color coding

 Blue Built-in functions and protected symbols
 Magenta Strings
Green Integers
Teal Real Numbers
Magenta, on Gray background Comments
Red Parentheses
Black User Variables and Unrecognized items

 

Operators

  Process   Examples
+ add (+ [number number] ...) (+ 1 2) returns 3;  (+ 1 2.0) returns 3.0; (+ 1 2 3 4) returns 10
- subtract (- [number number] ...) (- 2 1) returns 1;  (- 2 1.0) returns 1.0; (- 10 4 2) returns 4; (- 5) returns -5
* multiply (* [number number] ...) (* 1 2) returns 2;  (* 1 2.0) returns 2.0; (* 1 2 3 4) returns 24; (* 3) returns 3
/ divide (/ [number number] ...) (/ 4 2) returns 2;  (/ 4 3) returns 1; (/ 4 3.0) returns 1.33333; (/ 10 2 2.0) returns 2.5; (/ 3) returns 3
= equal to (= number [number] ...) (= 4 4) returns T; (= 4 4.0) returns T; (= 4 4.0 4) returns T; (= 4 4 3) returns nil; (= "me" "me") returns T; (= "me" "Me") returns nil; (= 1 "1") returns nil
/= not equal to (/= number [number] ...) (/= 1 2) returns T; (/= 1 1) returns nil; (/= 1 1 1.0) returns nil; (/= "me" "Me") returns T
< less than (< number [number] ...) (< 1 2) returns T; (< 1 2 3) returns T; (< 2.0 3) returns T; (< "a" "b") returns T; (< "a" "B") returns nil
<= less than or equal to (<= number [number] ...) (<= 1 2) returns T; (<= 1 2 3) returns T; (<= 2.0 3) returns T; (<= "a" "a") returns T; (< "a" "A") returns nil
> greater than (> number [number] ...) (> 1 2) returns nil; (> 1 2 3) returns nil; (> 2.0 3) returns nil; (> "a" "b") returns nil; (> "a" "B") returns T
>= greater than or equal to (>= number [number] ...) (>= 1 2) returns nil; (>= 1 2 3) returns nil; (>= 2.0 3) returns nil; (>= "a" "a") returns T
1+ increment by 1 (1+ number) (1+ 1) returns 2; (1+ 1.0) returns 2.0; (1+ -1) returns 0
1- decrement by 1 (1- number) (1- 2) returns 1; (1- 2.0) returns 1.0; (1- -2) returns -3

             Notes -

                        A Variable can be supplied instead of a [number]

                        Only numeric number values are valid with +,-,*,/

                        If only 1 number is supplied to comparison, the result is always T

                        When comparing String values, the strings are compared character by character

                        /= compares successive arguments only, not the complete list of numbers

                       

Getting Started

setq function to store a value to a variable

            (setq VariableName Expression [VariableName Expression] ...)

            Notes -

                        setq can assign multiple Variables in one call to the function (setq Var1 1.0 Var2 2.0)

                        setq returns the last evaluated expression (previous example returns 2.0)

            Examples - (setq Var1 1.0), (setq Var1 "Text"), (setq Var1 (list 1 2 3)), (setq Var1 T)

 

defun function defines a user function

            (defun SymbolName ([Arguments ] [/ LocalVariables ...] ) Expressions ...)

            Notes -

                        If you do not supply any Arguments or Local Variables

                                    you must supply an empty set of parentheses after the SymbolName

                        Warning! Never use the SymbolName of a built-in function or symbol

                                    This will overwrite the original definition and make the built-in function inaccessible

            Examples  -

(defun MyFunc () ...) Function without Arguments and Local Variables
(defun MyFunc (Arg1 Arg2) ...) Function with 2 Arguments
(defun MyFunc (/ LVar1 LVar2) ...) Function with 2 Local Variables
(defun MyFunc (Arg1 Arg2 / Var1 LVar2) ...) Function with 2 Arguments and 2 Local Variables
(defun C:MyFunc () ...) Function that can be called like any AutoCAD command
(defun C:MyFunc (/ LVar1 LVar2) ...) Function that can be called like any AutoCAD command with 2 Local Variables

   

First programs

; TEST1 program, sets 2 variables, then adds the 2 variables and saves to the 3rd variable; program returns the 3rd variable (4.0)

(defun C:TEST1 ()

    (setq Var1 1.0)

    (setq Var2 3.0)

    (setq Var3 (+ Var1 Var2))

)

 

; TEST2 program, sets 2 variables, then adds the 2 variables, saves the sum to the 3rd variable; multiples the 2 variables, saves the sum to the 4th variable, program returns whether the 3rd and 4th variables are the same (nil)

(defun C:TEST2 ()

    (setq Var1 1.0)

    (setq Var2 3.0)

    (setq Var3 (+ Var1 Var2))

    (setq Var4 (* Var1 Var2))

    (= Var3 Var4)

)