The Result Buffer Object

acad_cons (Type: ads.ConsType)

The Python representation of an Autolisp cons cell. Actually, this object is closer to strictly representing an ADS resbuf struct than a cons cell, because the type of the car is limited to ints and the type of the cdr is restricted to matching the type suggested by the value of the car. However, acad_cons objects should still get converted to cons cells when being passed to Autolisp.

Unfortunately, there is no easy way to represent an association list as known from Autolisp in Python. While the first guess would be a dictionary, there are some differences that make this a bad choice. An association list can have multiple entries of the same key and sequence matters. A Python dictionary has unique keys, and sequence is arbitrary.

To work around this, the ADS module defines a new object type, that is used to emulate a lisp cons cell. The emulation is not formally correct, since we don't build lists by linking cons cells, but we just have a normal Python list pretend it was an association list, as long as it only contains cons cells. This doesn't really work to exchange general association lists between Autolisp and Python, but is rather designed for building arguments to ADS functions, where the Autolisp counterpart would use an association list.

Constructor

ads.cons(key, value) -> acad_cons

The key argument is a short integer, and the value is a Python object of matching type for the key. At the moment, the following types are legal:

Strings
Integers (including long integers within [LONG_MIN ... LONG_MAX])
Floats
Points (tuples of two or three numbers, ints will be preserved as such on the Python side, but are promoted to double when the cons cell is handed over to Autocad/Intellicad).
Entity names (acad_ename objects)
Selection sets (acad_sset objects)

Please refer to the documentation of the DXF file format for a listing of valid keys and their respecive value types.

Many other functions and methods of the ADS module return association lists containing cons cells.

Methods

acad_cons.key() -> int
acad_cons.car() -> int

Returns the key (car) of the cons cell.

acad_cons.value() -> PyObject
acad_cons.cdr() -> PyObject

Returns the value (cdr) of the cons cell.

acad_cons.items() -> (int, PyObject)

Returns the key (car) and value (cdr) of the cons cell.

acad_cons.setval(value)

Sets the value (cdr) of the cons cell.

Note that the type of the value must match the type associated with the key of the cons cell as defined when creating the object. There is no way to change the key of a cons cell.

The set() method will normally be used when modifying existing entities, similar to the following:

e = ads.entfirst()                 # an acad_ename object
data = e.get()                     # an association list
point = data[8]                    # fetch an element from list
print point.items()                # chance has it we got a point...
(11, (232.445, 834.234, 784.934))
point.setval((100.0, 200.0, 0))    # modify value in place
e.set(data)                        # commit modified entity to drawing database

Functions

assocval(assocl, key [,startpos]) -> value

Search the association list assocl for the first entry with the given key and return it's value, or return None if no such entry is found. The optional integer argument startpos allows to start the search at any position in the list.