Skip to content

Commit

Permalink
Fixed formatting in README.
Browse files Browse the repository at this point in the history
  • Loading branch information
joachim-n authored Aug 31, 2020
1 parent eb6bcbd commit b56fda8
Showing 1 changed file with 38 additions and 1 deletion.
39 changes: 38 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,110 +18,139 @@ its definition.

Data objects can be simple, holding just a scalar value:

```
$simple_data->value = 42;
$simple_data->value = 'cake';
$simple_data->value = TRUE;
```

or complex, with child properties which are in turn simple:

```
$complex_data->alpha = 42;
$complex_data->beta = 'cake;
$complex_data->gamma = TRUE;
```

or can be complex themselves:

```
$complex_data->child->grandchild->alpha = 42;
```

Both simple or complex data may be multiple-valued:

```
$multiple_simple_data[] = 'adding new value';
$multiple_simple_data[0] = 'changing existing value';
$multiple_complex_data[]->alpha = 'adding new value';
$multiple_complex_data[0]->beta = 'changing existing value';
```

Complex data can be mutable, which means that its child properties change in
response to a controlling property's value:

```
$animal->type = 'mammal';
$animal->gestation_period = '12 months';
$animal->type = 'reptile';
// The gestation_period property is removed; other properties may now have been
added.
```

## Accessing data

Simple data is always accessed with the 'value' property:

```
$simple_data->value = 'cake';
print $simple_data->value;
```

Complex data is accessed with the child property names, which can be chained
until reaching the simple values at the tips of the structure:

```
$complex_data->alpha->value = 'cake';
print $complex_data->alpha->value;
$complex_data->also_complex->value = 'cake';
print $complex_data->also_complex->alpha->value;
```

As a shorthand, simple child values can be set with just the property name:

```
$complex_data->alpha = 'cake';
```

Multiple data can be used as a numeric array:

```
$multiple_simple_data[0] = 'zero';
$multiple_simple_data[1] = 'one';
$multiple_simple_data[] = 'append';
```

Note that the deltas must remain consistent:

```
$multiple_simple_data[0] = 'zero';
$multiple_simple_data[42] = 'delta too high'; // throws Exception
```

Whether multiple data is simple or complex, accessing the array produces a
data object:

```
print $multiple_simple_data[0]->value;
print $multiple_complex_data[0]->alpha->value;
```

### Iterating

All data objects can be iterated over.

Simple data has no effect:

```
foreach ($simple_data as $item) {
// Nothing.
}
```

Complex data iterates over its child properties:

```
foreach ($complex_data as $name => $item) {
print $item->value;
}
```

Multiple data iterates over the delta items:

```
foreach ($multiple_data as $delta => $item) {
print $item->value;
}
```

Because iterating simple items has no effect, iterating data items like this is
safe to do recursively into the data structure.

Alternatively, the items() method on data objects allows iteration that is
agnostic of cardinality:

```
foreach ($simple_data->items() as $item) {
print $item->value; // Same as $simple_data->value
}
foreach ($multiple_simple_data->items() as $item) {
print $item->value;
}

```
This is useful when working with a property that may be either single or
multiple, as it gives all the values in either case. However, it should not be
used recursively, as iterating on the value in the iteration for a simple item
Expand Down Expand Up @@ -175,12 +204,15 @@ have entered. See Drupal's Module Builder for an example of doing this.

Data is defined with a fluent interface:

```
$definition = \MutableTypedData\Definition\DataDefinition::create('string')
->setLabel('Label')
->setRequired(TRUE);
```

Complex data is defined by nesting properties:

```
$definition = \MutableTypedData\Definition\DataDefinition::create('complex')
->setLabel('Label')
->setProperties([
Expand All @@ -190,12 +222,14 @@ $definition = \MutableTypedData\Definition\DataDefinition::create('complex')
'child_property_beta' => \MutableTypedData\Definition\DataDefinition::create('string')
->setLabel('Beta'),
]);
```

### Options

Options can be defined with an array, or with objects, which allow options to
have descriptions as well as labels:

```
$definition = \MutableTypedData\Definition\DataDefinition::create('string')
->setLabel('Label')
->setOptionsArray([
Expand All @@ -211,12 +245,14 @@ $definition = \MutableTypedData\Definition\DataDefinition::create('string')
\MutableTypedData\Definition\OptionDefinition::create('red', 'Magenta', 'A deep red'),
\MutableTypedData\Definition\OptionDefinition::create('grey', 'Grey', 'Not very colourful')
);
```

### Mutable data

Mutable data needs a single property to control the variants, and then a
definition for each variant:

```
$definition = \MutableTypedData\Definition\DataDefinition::create('mutable')
->setLabel('Label')
->setProperties([
Expand All @@ -241,6 +277,7 @@ $definition = \MutableTypedData\Definition\DataDefinition::create('mutable')
->setLabel('B2'),
]),
]);
```

The variants automatically define the options for the type property.

Expand Down

0 comments on commit b56fda8

Please sign in to comment.