### 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 `object`s 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 `object`s. 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 `object`s 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.