(objects were added in v1.1)
Some commands return values called objects. An object is a special kind of value that groups together other values that are logically related. These related values are called properties. Each property has both a name and value.
As a real world example consider a “person” object which represents an individual human being. This person object could have a height property (whose value is a number) and a name property (a string). Every single person has these properties, but each person can have a different value for each property, eg: some persons are taller than others.
When describing an object in the abstract sense the title case name of the object type will be used, eg: a Person object. Consider the following documentation for a fictional command:
Make Taller personObject, addHeight
Increases the height of the Person object by the amount given.
The first argument the command expects is a Person object- specifically the person to make taller. The command doesn’t care what Person object it is given, just that it is given a particular Person. Assuming a Person object value is held in the variable $person, the command would be used like:
Make Taller $person, 1.2 # let's grow our person
To inspect properties of an object you use a special dot notation that delimits the name of the property you want to read:
$before = $person.height
Make Taller $person, 1.2
$after = $person.height
Using the same dot notation, object property values may be changed directly through assignment:
$person.name = "Xerxes"
In addition to the basic types like numbers, a property value may be another object. A Person object could have a birthday property that is a Date object:
$date = $person.birthday
$year = $date.year
Objects may also provide commands that change the object’s properties or perform some related function. These commands are executed using the same dot notation, eg:
$person.eatFood('blackberries')
$person.eatFood 'jelly bellies'
$name = $person.fullName # first and last name
Note: surrounding the argument(s) given to the command with parentheses is optional.
So far it has been assumed that the $person variable contained a particular Person object. As stated earlier, any command could return an object value. However, objects are more often obtained using type commands.
Type commands function just as normal commands do, but are grouped together by the name of the object type. These commands do not operate on any particular Person object, but rather are commands related to Person objects. As an example, the Person object may have some type commands that return famous persons:
$person = Person.sherlockHolmes
Or perhaps the Person object provides commands that allow you to create your own persons:
$person = Person.new("Bob")
It should be noted that the Person object type does not exist in the macro language, it was merely an example. To read about an actual object it might be best to start with the Document object, which provides access to many other macro objects.
Note: object property and command names are case sensitive. Also, not all property values can be changed. If a property value cannot be modified it will be marked in this documentation as read-only. If you attempt to change a read-only property, or try to inspect a property a particular object does not possess, an error will be displayed.
| Previous Chapter Indexing |
<< index >> |
Next Chapter Object Equality |