Merge pull request #570 from Lexpedite/predicate_validation

Predicate validation

CHANGELOG.md

@@ -7,6 +7,27 @@ As of v0.2-alpha, this project is attempting to adhere to [Semantic Versioning](
 While alpha, however, any version may include breaking changes that may not be specifically noted as such,
 and breaking changes will not necessarily result in changes to the main version number.
 
+## [v1.6.17-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.6.17-alpha) 2023-07-18
+
+This release adds validation for category names, attribute names, object names, relationship names, and variable names.
+The corresponding blocks will now convert invalid names to valid names where possible, and will reject names that they
+cannot convert.
+
+This version is reverse compatible with .blawx files from previous versions. However, invalid names will be either corrected
+if possible, or if not possible to correct will be replaced with the default value for the relevant field. This may have unexpected
+effects in encodings with invalid field values.
+
+### Changed
+* New Relationship, New Category, New Attribute, New Object, and Variable blocks now validate and correct
+  names as follows:
+  * first letters will be corrected to uppercase for variables and lowercase for all others
+  * spaces at the start and end will be removed
+  * spaces elsewhere will be converted to underscores
+  * names with symbols other than letters, numerals, underscore, and space will be rejected
+  * names that end in an underscore followed by numerals will be rejected
+* Documentation has been updated to reflect the new behaviour.
+
+
 
 ## [v1.6.16-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.6.16-alpha) 2023-06-26
 

blawx/fixtures/docs/blocks/categories/new_attribute.yaml

@@ -22,8 +22,6 @@
       It accepts a category to which the attribute should be applied, specified in a dropdown,
       a name for the attribute specified in a text field, and an attribute type specified in a dropdown.
 
-      To be valid, an attribute name should start with a lowercase letter and not have any spaces.
-
       The datatype can be a scalar data type like "number", or another category.
 
       The block also accepts an order for how the attribute should be displayed in natural language,
@@ -39,6 +37,16 @@
 
       ## Tips
 
+      To be valid, an attribute name must
+
+      * contain only numbers, underscores, and letters
+      * begin with a lowercase letter
+      * not end in an underscore followed by only digits
+
+      The block will automatically remove leading and trailing spaces, convert spaces to underscores,
+      and convert an initial uppercase letter into lowercase. Other invalid values will be rejected, and
+      the value of the field will not be changed.
+
       Note that if you specify a data type as the attribute type your attribute selector blocks
       will only accept the correct type of value, and variables in the value position. If you choose
       a category as the data type, your attribute selector blocks will accept any object, or a variable.

blawx/fixtures/docs/blocks/categories/new_category.yaml

@@ -19,12 +19,21 @@
 
       The new category block is a statement, and can be stacked with other statements.
 
-      The new category block accepts the name of the category. To be valid, the name of the category must begin with a lower-case letter and not
-      include any spaces.
+      The new category block accepts the name of the category.
 
       It also accepts text that should appear before and after the name of the object in explanations.
 
       ## Tips
 
       Names of categories should be unique, but can safely
-      overlap with the names of non-boolean attributes.
+      overlap with the names of non-boolean attributes.
+
+      To be valid, a category name must
+
+      * contain only numbers, underscores, and letters
+      * begin with a lowercase letter
+      * not end in an underscore followed by only digits
+
+      The block will automatically remove leading and trailing spaces, convert spaces to underscores,
+      and convert an initial uppercase letter into lowercase. Other invalid values will be rejected, and
+      the value of the field will not be changed.

blawx/fixtures/docs/blocks/categories/new_relationship.yaml

@@ -32,4 +32,14 @@
 
       ## Tips
 
-      Names of relationships should be unique, but can safely overlap with other relationship that have a different number of objects and values.
+      Names of relationships should be unique, but can safely overlap with other relationship that have a different number of objects and values.
+
+      To be valid, a relationship name must
+
+      * contain only numbers, underscores, and letters
+      * begin with a lowercase letter
+      * not end in an underscore followed by only digits
+
+      The block will automatically remove leading and trailing spaces, convert spaces to underscores,
+      and convert an initial uppercase letter into lowercase. Other invalid values will be rejected, and
+      the value of the field will not be changed.

blawx/fixtures/docs/blocks/objects/new_object.yaml

@@ -28,8 +28,17 @@
 
       The new object block asserts that the named object is in the category.
 
-      The text field must be the name of the object, which must not include spaces
-      and must start with a lower-case letter. Names for objects must also be unique.
+      The text field must be the name of the object. Names for objects must also be unique.
+
+      To be valid, an object name must
+
+      * contain only numbers, underscores, and letters
+      * begin with a lowercase letter
+      * not end in an underscore followed by only digits
+
+      The block will automatically remove leading and trailing spaces, convert spaces to underscores,
+      and convert an initial uppercase letter into lowercase. Other invalid values will be rejected, and
+      the value of the field will not be changed.
 
       The new object block is a statement, and can be stacked with other statements.
 

blawx/fixtures/docs/blocks/variables/variable.yaml

@@ -23,8 +23,17 @@
 
       ## Technical Details
 
-      The variable block requires you to enter a variable name into the text field,
-      which must not include spaces and must start with a capital letter to be valid.
+      The variable block requires you to enter a variable name into the text field.
+
+      To be valid, a variable name must
+
+      * contain only numbers, underscores, and letters
+      * begin with an uppercase letter
+      * not end in an underscore followed by only digits
+
+      The block will automatically remove leading and trailing spaces, convert spaces to underscores,
+      and convert an initial lowercase letter into uppercase. Other invalid values will be rejected, and
+      the value of the field will not be changed.
 
       The variable block can be entered anywhere an object or a value is expected.
 

blawx/fixtures/docs/features/categories.yaml

@@ -28,9 +28,9 @@
 
             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.
+      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
@@ -44,7 +44,7 @@
 
       An attribute or a relationship can hold either a basic data type, or objects in a category.
 
-      The basic data types are numbers, true or false values, dates, times, datetimes, durations, and lists.
+      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
@@ -59,7 +59,7 @@
       ### Creating Categories
       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
+      category declaration block can be found under the "Categories" drawer in the
       Toolbox.
 
       ![Person is Category](/static/blawx/docs/images/person_is_category.png)
@@ -68,13 +68,14 @@
       and in explanations. In this case, the phrase will be "_____ is a person".
 
       Category names should not
-      have spaces in them, and must start with a lowercase letter. Blawx will not stop you from creating
-      a category with a space in its name, but they will not work properly.
+      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
+      block can be found in the "Categories" drawer of the toolbox, and looks like
       this:
 
       ![attribute declaration binary](/static/blawx/docs/images/new_attribute_declaration_binary.png)
@@ -83,13 +84,13 @@
       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
+      example, to say that "a person has an age and a best friend" you might create
        attribute declaration blocks like these:
 
       ![person ontology](/static/blawx/docs/images/person_ontology.png)
 
-      The name of an attribute must start with a lowercase letter, must not have spaces,
-      and must be unique across all categories.
+      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.
 
       ### Attribute Customization
 
@@ -152,26 +153,26 @@
 
       ![bob is person](/static/blawx/docs/images/bob_is_person.png)
 
-      Object names should start with lowercase letters, and should not have spaces in them.
-      Blawx will not stop you from creating
-      an object with a name that has spaces
-      in it, but it won't work properly.
+      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”
+      onto the Workspace, a corresponding Object Block appears in the "Known Objects"
       drawer of the Toolbox.
 
       ![bob known](/static/blawx/docs/images/known_object_bob.png)
 
       The
-      object block for “Bob” can be used anywhere a block is expecting an or accepts
+      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
+      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:
 
@@ -182,21 +183,21 @@
       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:
+      found in the "Objects" drawer of the Toolbox, and which looks like this:
 
       ![object identity](/static/blawx/docs/images/blocks/object_equality.png)
 
       The object identity
-      block takes two object blocks. To say that “Bob” and “Robert” are the same object,
+      block takes two object blocks. To say that "Bob" and "Robert" are the same object,
       you could do this:
 
       ![bob and robert](/static/blawx/docs/images/bob_and_robert_identical.png)
 
       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.
+      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
 
@@ -211,20 +212,21 @@
 
       ### Naming Attributes
 
-      Attribute names must start with a lowercase letter, and must not have spaces in them.
-      They must also be unique across all categories.
-      Blawx will not currently
-      stop you from creating invalid attribute names, but they will cause errors.
+      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”.
+      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
+      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
+      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.
 
@@ -247,7 +249,8 @@
       ## Relationships
 
       You can create a relationship by using the new relationship block. You need to give it a name, which
-      must be lower case and not have spaces. You also need to give it a number of objects or values that will
+      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.
 

blawx/fixtures/docs/features/variables.yaml

@@ -59,7 +59,12 @@
       the name of the variable, but you can use any other name you like.
 
       **Note that
-      variable names should not include spaces, and must start with a capital letter.**
+      variable names should include only letters, numerals, and underscores, must start with a capital letter, and must not end
+      in an underscore followed by numerals.**
+
+      The variable block will automatically remove leading and trailing spaces, convert spaces to underscores,
+      and convert an initial lowercase letter into uppercase. Other invalid variable names will be rejected, and
+      the variable name will not be changed.
 
       ### Variables in Rule Conclusions
 
@@ -147,7 +152,7 @@
       A named variable is the only kind of variable that will cause Blawx to give you the specific
       value in response to a question, outside of the explanation.
 
-      A variable should start with a capital letter, and have no spaces.
+      See above for the rules on what counts as a valid variable name.
 
       ### Unnamed Variables
 

blawx/settings.py

@@ -13,7 +13,7 @@
 from pathlib import Path
 
 # For adding a version identifier
-BLAWX_VERSION = "v1.6.16-alpha"
+BLAWX_VERSION = "v1.6.17-alpha"
 
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.