Next: , Previous: , Up: Core API Reference   [Contents][Index]


2.3 Core attribute functions

To use the functions described in this section, you will need to load the (lepton attrib) module.

Attributes are text objects with a particular format of string. They can be floating, or they can be attached to another object.

Function: attribute? object

Returns true if and only if object is an attribute (i.e. a text object and in attribute format).

2.3.1 Attribute names and values

Function: parse-attrib text

Splits the string from text (a text object) into name and value, if it is in attribute format. If it is not in attribute format, raises an ‘attribute-format’ error. The return value is in the form ‘(name . value)’.

Function: attrib-name attrib

Returns the name part of attrib, as a string.

Function: attrib-value attrib

Returns the value part of attrib, as a string.

Function: set-attrib-value! attrib value

Sets the value part of attrib to value.

2.3.2 Attribute attachment

Function: attrib-attachment attrib

If attrib is attached to another object, returns that object. Otherwise, returns ‘#f’.

Function: object-attribs object

Returns a list of all attributes attached to object.

Function: attach-attribs! object [attribs...]

Attach attribs to object. All the attribs must be text objects. The following conditions must be satisfied, or an ‘object-state’ error will be raised:

  • Neither object nor any of the attribs may be already attached as an attribute;
  • Both object and all attribs must be part of the same page and/or component object;

Any attribs that are already attached to object are ignored. Returns object.

Note: For historical reasons, attach-attribs! does not require that all attribs satisfy attribute?. Nevertheless, avoid attaching non-attribute text objects as attributes.

Function: detach-attribs! object [attribs...]

Detach attribs from object. Any attribs that are not attached as attributes are ignored. If any attribs are attached to objects other than object, an ‘object-state’ error is raised.

2.3.3 Inherited and promoted attributes

Inherited attributes are unattached attributes inside a component object.

Function: inherited-attribs object

Returns the inherited attributes of object, if object is a component. If object is not a component, returns the empty list.

Function: attrib-inherited? attrib

Returns ‘#t’ if attrib is an inherited attribute.

promotable attributes are inherited attributes that are both visible and have names that are in the list of promotable attributes set with the always-promote-attributes rc file parameter.

Function: promotable-attribs component

Returns a list of promotable attributes of component.

Function: promote-attribs! component

Promote all promotable attributes from component into the page that contains component. If component is not in a page, an ‘object-state’ error is raised.

All promotable attributes are copied, and made invisible. The copies are added to the page, and attached as attributes of component.

The promoted attributes are returned. If component is not in fact a component object, does nothing and returns the empty list.


Next: Core source library functions, Previous: Core object functions, Up: Core API Reference   [Contents][Index]