Block Definitions and Instances

Class and object, semantically

The closest familiar model is that a Block is a declarative semantic Class, and a Block Instance is an Object — a semantic analogy, not a mandate that the compiler must represent them as runtime objects. The compiler may represent both definitions and instances as plain data; the parser nonetheless distinguishes block documents from composition children.

Two contexts, never mixed

A Block definition is a .bml file describing shape and behaviour — its FQN, members, and composition schema — with no runtime and no address of its own.

A Block instance is one concrete occurrence inside composition, identified by bml:id rather than by its type FQN, carrying its own member values.

The most common authoring confusion

value and composition belong only to member declarations on a Block definition; on a Block instance the Property element is already the value and the Aggregation element already holds its children, so wrapping an instance payload in either one is a category error. A member actually named value, such as on PrimitiveEntity, is the one exception — that is ordinary instance syntax, not a definition wrapper.

A definition and one instance of it

Placing a Block's definition beside one instance of it makes the class/object analogy concrete: the definition declares a property, and the instance supplies a value for it.

<!-- Definition: declares the "count" Property and its default value -->
<acme:Basket xmlns="http://blockml.org/bml"
  xmlns:acme="com.acme.example"
  xmlns:core="org.blockml.bml.core"
  xmlns:type="org.blockml.bml.type">

  <baseType>
    core:Block
  </baseType>
  <properties>
    <count type="type:Integer">
      <value>3</value>
    </count>
  </properties>
</acme:Basket>

<!-- Instance: count is set directly as an attribute, never wrapped in <value> -->
<acme:Basket bml:id="firstBasket" count="5" />

The definition's count property declaration exists once, together with its default of 3; the instance's count attribute supplies a concrete value, 5, for that one occurrence — exactly the class-declares, object-holds relationship the analogy describes.

What to carry into the next pages

After this page, readers should be able to tell a Block definition from a Block instance in any piece of BML, and keep definition-only fields like value out of instance payloads.

Continue with inheritance