Categories, Attributes, and Relationships
Categories, Attributes, and Relationships are how Blawx organizes what it knows about the world.
A Category is a type of object. For example, "Car."
A Category has Attributes, which are names for things that you can know about things in that Category. Attributes also describe the type of data that can go in that attribute. For example, "a car has a top speed, which is a number."
An Object is a specific thing in the world you want to model. An object can have any number of categories. An Object has the same attributes as all of the categories it belongs to, which hold that information about the object. For example, "my car's make is Ford, and my car's model is Mustang."
The information that you put into an object's attribute has to be of the correct type. You can't put a number if the attribute is supposed to hold a date value, and vice-versa.
An easy way
to think of a Category is as a description of a blank form. The form might have a name, like "Application for a Permit". That is like the Category name. A form will also have fields that can be filled in, like "Applicant's Name". Those are like the category's attributes.
When you create and fill out an actual form of that type, that is like creating an Object. The information that gets put into the blanks on the form are like the values that get put into the attributes of an object. Some fields on the form are for checkmarks, others numbers, and others dates. Those are like the types of the category attributes.
A Relationship is a thing that is true about a combination of 3 or more objects and values. For example, you might want to record information about where cars placed in races, and you could create a relationship between a car (a category), a race (another category), and a number indicating the finishing position.
An attribute or a relationship can hold either a basic data type, or objects in a category.
The basic data types are numbers, values, dates, times, datetimes, durations, and lists. An attribute can also be true or false.
Not only can you use your Categories as a type, but you can use your category as the type of an attribute inside itself!
For example, you can say that a Person has a friend, which is a Person.
You create a category by putting a category declaration block in a fact block. A category declaration block can be found under the "Categories" drawer in the Toolbox.
You also describe how the category should be displayed to user in new object blocks and in explanations. In this case, the phrase will be "_____ is a person".
Category names should not have spaces in them, must start with a lowercase letter, must contain only letters, numerals, and underscores, and must not end in an underscore followed by numerals. Blawx will automatically correct some problems like these for you, but other invalid category names will be rejected.
Adding Attributes to a Category
Once you have declared a Category, you can use an attribute declaration block to give it an attribute. The attribute declaration block can be found in the "Categories" drawer of the toolbox, and looks like this:
To complete an attribute declaration, you say what category it applies to, give it a name, give it a data type, and then describe how it should be phrased in attribute selector blocks and explanations.
For example, to say that "a person has an age and a best friend" you might create attribute declaration blocks like these:
The name of an attribute must follow the same rules as the name of a category. It also needs to be unique across all categories.
The attribute declaration block allows you to customize how the attribute is described in the attribute selector and explanations. To do that, you first indicate whether the object or the value should appear first in the phrase. Then, you indicate the text that should appear, if any, before, between, and after the object and the value. By default the order is "object, then value". And the words "object" and "value" appear in that order below. If you change the order to "value, then object" in the dropdown, the text on the bottom line of the attribute declaration block will be modified to match. Note how the order has been changed to "value, then object" in the declaration of "best_friend" above.
Once you have selected the order that you want the object and the value to appear, you can specify the text that appears before, between, and after them. For example, imagine that you have a category called "Animal" and an attribute called "legs" that was supposed to hold how many legs the animal has.
Here are three different ways you might want your customized attribute block to appear, and how to achieve that effect using the attribute customization block:
All three of these examples mean the same thing.
If you leave all three fields blank, Blawx will still know what attribute the block is for, but your users will have no clue. Make sure to customize attribute displays in ways that sound natural to your users, but are also very clear about which attribute is being modified.
There is no need for your attribute's name to appear in the text, which can allow you to use more concise attribute names, or attribute names that are easier to keep unique.
Creating an Object
An object is created by using the new object block, which looks like this, and it just takes a name for the object. A different new object block is created for each of the known categories in your code.
Object names need to follow the same rules as category and attribute names, and should be unique. Blawx will correct some errors in object names, such as removing leading and trailing spaces, converting other spaces to underscores, and making the first letter lowercase. Other errors will result in the changed value being rejected.
When you drag an object declaration onto the Workspace, a corresponding Object Block appears in the "Known Objects" drawer of the Toolbox.
The object block for "Bob" can be used anywhere a block is expecting an or accepts an object as a value.
Giving an Object another Category
All objects are created inside a category. But it is possible to assign additional categories to objects that have already been created. You can do this using the object category block, which can be found in the "Objects" drawer of the Toolbox. It expects an object block and a category block. For example, if we wanted to say that in addition to being in the category person, "bob" is in the category "mammal", we could create a statement like this:
Making Two Objects the Same Object
Sometimes your Blawx code will get data from more than one source, and each source may create its own versions of the same objects. In those cases, it can be useful to state that two objects are the same object. You can do that using the object equivalence block, which is found in the "Objects" drawer of the Toolbox, and which looks like this:
The object identity block takes two object blocks. To say that "Bob" and "Robert" are the same object, you could do this:
Note that object equivalence goes in both directions. If Bob is the same object as Robert, Robert is the same object as Bob. So if you set out Bob's age, and then say that Bob and Robert are the same object, asking for Bob's age and asking for Robert's age will both work.
Adding Attributes to an Object
Once there is an object in the database, you can use the attribute selector blocks to assign values to that attribute for that object.
For example, we have said that "bob" is a person. Now we can say that bob is 35 years of age, by taking the attribute selector for "age", and giving it the object selector for bob and the number 35 as inputs, like this:
Attribute names must contain only letters, numerals, and underscores, must start with a lowercase letter, and must not end with an underscore followed by numerals. Blawx will remove leading and trailing spaces, convert internal spaces to underscores, and make the first letter of your attribute name lowercase for you. Names that are invalid in other ways will be rejected.
When working with attributes you will want to be careful with how you name them. Blawx will not stop you from applying an attribute defined for "cars" to an object in the category "bicycle". If you need to know how many seats both categories have, but you want to avoid the implication that bikes have car seats or vice-versa, you may want to name the attributes "bike_seats" and "car_seats" to make it clear what you are referring to.
If you create two attributes both named "seats", they will both appear in the Known Attributes drawer of the toolbox, but Blawx will treat them as two copies of the same attribute.
Object Attributes Hold Multiple Values
Note that in Blawx all Attributes (except true/false attributes) can hold multiple values, but only multiple unique values. If you create an attribute that holds numbers, like "age", it can hold any number of values, but it cannot hold the same value twice, even if you state it twice.
True / False Attributes are Special
Unlike most attribute types, if you choose "True / False" as the attribute type for an attribute, there is only an object, and no value. That is because the way you say something is true in Blawx is by just stating it, and the way that you say it is false is by surrounding it with a "it is false that" negation block.
So when you create a "True / False" attribute, it has only an "object" field, and you only need to customize the text that appears before and after the name of the object.
You can create a relationship by using the new relationship block. You need to give it a name, which must follow the same naming conventions for categories, attributes and objects. You also need to give it a number of objects or values that will be related to one another. Note that if what you are looking for is a relationship between 2 objects, you should use an Attribute instead.
Once you have chosen the name and the number of objects or values, you will be able to choose a type for each of the elements, choosing between the available data types and the known categories. You can also provide the text that should appear before, between, and after all of the elements. This text will be used to build the relationship selector block, and will be used in explanations.