Scheme Extensions

 

 

Technical Article
Scheme is a public domain programming language, based on the LISP language, that uses an interpreter to run commands. ACIS provides extensions (written in C++) to the native Scheme language that can be used by an application to interact with ACIS through its Scheme Interpreter. The C++ source files for ACIS Scheme extensions are provided with the product. Spatial's Scheme based demonstration application, Scheme ACIS Interface Driver Extension (Scheme AIDE), also uses these Scheme extensions and the Scheme Interpreter.

attrib:add

Action
Adds an attribute to an entity or a list of entities.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
None

Syntax
(attrib:add entity-list name [value])

Arg Types
entity-list entity | (entity ...)
name string
value integer | real | string | position | boolean
Arguments
entity-list specifies an entity or list of entities to which the attributes are attached.
 
name specifies the name of the attribute.
 
The optional value (integer, gvector,real, string, position, or logical) provides additional identification for the attribute.
;attrib:add
; Create a block.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Add the following attributes to the block.
(attrib:add block1 "layer" 1)
;; ()
(attrib:add block1 "color" 3)
;; ()
(attrib:add block1 "type" "block")
;; ()
(attrib:add block1 "part")
;; ()
(attrib:get block1)
;; (("layer" . 1) ("color" . 3) ("type" . "block")
;; ("part"))   

[Top]

attrib:get

Action
Gets the attributes attached to a given entity.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
None

Syntax
(attrib:get entity [name [value]])

Arg Types
entity entity
name string
value integer | real | string | position | boolean

Returns
(attribute ... )
Arguments
entity specifies an input entity to which the attributes are attached. This extension returns a list of attributes. If no options are provided, this returns all attributes attached to the given entity.
 
The optional name returns attributes with a given name, regardless of whether they contain a value. value provides additional identification for the attribute.
If name and value are specified, the extension returns attributes that match both name and value. If there are no attributes attached to the entity, the extension returns an empty list.
;attrib:get
; Create block 1.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Create block 2.
(define block2
    (solid:block (position 20 20 20)
    (position 5 10 15)))
;; block2
; Add an attribute to block 1.
(attrib:add block1 "layer" 1)
;; ()
; Add attributes to block 2.
(attrib:add block2 "color" 3)
;; ()
(attrib:add block2 "type" "block")
;; ()
; Get the attributes for block 1.
(attrib:get block1)
;; (("layer" . 1))
; Get the attributes for block 2.
(attrib:get block2)
;; (("color" . 3) ("type" . "block"))
; Get the color attribute for block 2.
(attrib:get block2 "color")
;; (("color" . 3))

[Top]

attrib:remove

Action
Deletes an attribute from an entity or list of entities.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
None

Syntax
(attrib:remove entity-list [name [value]])

Arg Types
entity-list entity | (entity ...)
name string
value integer | real | string | position | boolean
Arguments
entity-list specifies an entity or list of entities from which attributes are removed.
 
The optional name identifies by the given name the attributes to be removed, regardless of whether they contain a value. value provides additional identification for the attribute.

If name and value are specified, the extension removes attributes that match both name and value. If name or value are not specified, the extension removes all attributes from the entity-list.
;attrib:remove
; Create block 1.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Create block 2.
(define block2
    (solid:block (position 20 20 20)
    (position 5 10 15)))
;; block2
; Create block 3.
(define block3
    (solid:block (position 20 20 20)
    (position 25 30 35)))
;; block3
; Add an attribute to block 1.
(attrib:add block1 "layer" 1)
;; ()
; Add attributes to block 2.
(attrib:add block2 "color" 3)
;; ()
; Add attributes to block 3.
(attrib:add block3 "type" "block")
;; ()
; Save this part with attributes.
(part:save "att.sat")
;; #t
; Get the attributes for block 1.
(attrib:get block1)
;; (("layer" . 1))
; Get the attributes for block 2.
(attrib:get block2)
;; (("color" . 3))
; Get the attributes for block 3.
(attrib:get block3)
;; (("type" . "block"))
; Remove the layer attribute for block 1.
(attrib:remove block1 "layer")
;; ()
; Get the attributes for block 1.
(attrib:get block1)
;; ()
; Remove the color attribute for block 2.
(attrib:remove block2 "color")
;; ()
; Get the attributes for block 2.
(attrib:get block2)
;; ()
; Remove the type attribute for block 3.
(attrib:remove block3 "type")
;; ()
; Get the attributes for block 3.
(attrib:get block3)
;; ()
; Save this part without attributes
(part:save "not_att.sat")
#t

[Top]

attrib:replace

Action
Replaces all attributes on an entity or list of entities of a given name.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
None

Syntax
(attrib:replace entity-list name [value])

Arg Types
entity-list entity | (entity ...)
name string
value integer | real | string | position | boolean
Arguments
entity-list specifies the entities to have attributes replaced.
 
name assigns an attribute name to the entity-list.
 
value provides additional identification for the attribute. This extension creates a new attribute and attaches it to the specified entity or list of entities with the name and value.
;attrib:replace
; Create block 1.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Add an attribute to block 1.
(attrib:add block1 "layer" 1)
;; ()
; Get a list of the entity's attributes.
(attrib:get block1)
;; (("layer" . 1))
; Replace some attributes for the block.
(attrib:replace block1 "chrome" 6)
;; ()
; Get a list of the entity's attributes.
(attrib:get block1)
;; (("layer" . 1) ("chrome" . 6))
(attrib:replace block1 "layer" 6)
;; ()
; Get a list of the entity's attributes.
(attrib:get block1)
;; (("chrome" . 6) ("layer" . 6))
; Add an attribute for the block.
(attrib:add block1 "layer" 3)
;; ()
; Get a list of attributes for the block.
(attrib:get block1)
;; (("chrome" . 6) ("layer" . 6) ("layer" . 3))
; Replace an attribute for the block.
(attrib:replace block1 "layer" 5)
;; ()
; Get the list of attributes for the block.
(attrib:get block1)
;; (("chrome" . 6) ("layer" . 5))   

[Top]

generic:add

Action
Adds a generic attribute to an entity or list of entities.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
api_add_generic_named_attribute

Syntax
(generic:add ent-list attrib-name
    [attrib-value] [attrib-behaviors])

Arg Types
ent-list entity | (entity ...)
attrib-name string
attrib-value [ string | UTF8-filename (whchar) | integer | real | boolean | position | vector | entity ]
attrib-behaviors [ string... ]

Errors
Type checking of input arguments.
Description
This extension creates a generic named attribute on the given input entity(s). The type of generic named attribute created depends upon the type of attrib-value given.
Arguments
ent-list specifies the entities to have attributes added.
attrib-name assigns an attribute name to the ent-list. The following mapping applies:
 
<no value> ATTRIB_GEN_NAME
string ATTRIB_GEN_STRING
UTF-8 filename ATTRIB_GEN_WSTRING
integer ATTRIB_GEN_INTEGER
real ATTRIB_GEN_REAL
boolean ATTRIB_GEN_INTEGER
position ATTRIB_GEN_POSITION
vector ATTRIB_GEN_VECTOR
entity ATTRIB_GEN_ENTITY
attrib-behaviors controls how the generic named attribute is to behave when its owner undergoes a split, transform, merge, or copy operation. You may specify one to four attrib-behaviors from the following strings: 

Choices for split owner:
"SplitLose" Lose the attribute if its owner is split.
"SplitKeep" Do nothing if owner is split (default).
"SplitCopy" Create a new instance of the attribute on the new entity.
"SplitCustom" Call application supplied routine.

Choices for merge owner:
"MergeLose" Lose the attribute if its owner is merged.
"MergeKeepKept" Do nothing if owner is merged (default).
"MergeKeepLost" Transfer attribute from entity being lost to entity being kept.
"MergeKeepOne" Transfer from entity being lost to entity being kept if none on entity being kept.
"MergeKeepAll" Move attribute from entity being lost to entity being kept.
"MergeCustom" Call application supplied routine.

Choices for transform owner:
"TransLose" Lose the attribute if its owner is transformed.
"TransIgnore" Do nothing if its owner is transformed (default).
"TransApply" Apply given transform.
"TransCustom" Call application supplied routine.

Choices for copy owner:
"CopyLose" Lose the attribute if its owner is copied.
"CopyKeep" Do nothing if the owner is copied.
"CopyCopy" Create a new instance of the attribute on the new owner (default).
"CopyCustom" Call application supplied routine.

Note: If you want to create a wide character attribute, you can create a text file with UTF8 characters and specify the name of the file as the attribute string value. If a file with the given name is found, it loads the contents of the file into a wide character string and creates a wide character attribute. (If a file with a given name is not found, a normal string attribute is created with the input string as the value of the attribute.)

;generic:add
; Create a block.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Create a named attribute (no value). Set copy behavior to lose if owner is copied.
(generic:add block1 "layer" "CopyLose")
;; ()
; Create a position named attribute. Apply transforms to position value, copy to
; new owner if split.
(generic:add block1 "layer" (position 1 -2 3) "TransApply" "SplitCopy")
;; ()
; Create a named wide character attribute using a wide character string stored in a file.
  (generic:add block1 "blockdescription" "inputUTF8file.txt")

[Top]

generic:get

Action
Gets the value of a named generic attribute attached to an entity.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
api_find_named_attribute

Syntax
(generic:get ent [attrib-name])

Arg Types
ent entity
attrib-name string

Returns
entity | integer | position | real | string | gvector | unspecified

Errors
Prints out a message if named attrib-name attribute is not found.

Description
If the attribute is found on the given ent entity, it is returned as the type of Scheme object that it is. For example, if the attribute is a real ATTRIB_GEN_REAL, this returns a real number. If it is a vector, it returns a gvector, for example. If the attribute is an ATTRIB_GEN_WSTRING, then the contents of the attribute are saved to a file in UTF-8 text format and a string which specifies the file path is returned.

;generic:get
; Create a block.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Add the following attributes to the block.
(generic:add block1 "layer")
;; ()
(generic:get block1 "layer")
; Found
;; ()
; Add a wide character attribute using a wide character string stored in a file. 
(generic:add block1 "blockdescription" "inputUTF8file.txt")
(generic:get block1 "blockdescription")
; Returns a string "widecharfile101.txt"

[Top]

generic:remove

Action
Removes the name of a generic attribute attached to each entity in the list.

Filename
scm/scmext/ga/attr_scm.cpp

APIs
api_remove_generic_named_attribute

Syntax
(generic:remove ent-list attrib)

Arg Types
ent-list entity | (entity ...)
attrib string

Description
This removes the named attrib attribute from all entities given in the ent-list entity list. 

;generic:remove
; Create a block.
(define block1
    (solid:block (position 0 0 0)
    (position 5 10 15)))
;; block1
; Add the following attributes to the block.
(generic:add block1 "layer")
;; ()
(generic:remove block1 "layer")
;; ()

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.