Merge pull request #442 from Lexpedite/new_booleans

New booleans

CHANGELOG.md

@@ -7,23 +7,107 @@ 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.3.41-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.41-alpha) 2022-02-27
+## [v1.4.0-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.4.0-alpha) 2023-02-28
+
+**This release is NOT backward compatible.**
+
+This release makes a number of interface changes, and 
+significantly changes the way that Blawx deals with true / false values. Instead of
+being treated as a statement about an object and a value (true, or false),
+they are treated as a statement about an object alone. This has considerable
+implications for the block language, and as a result, `.blawx` files exported prior to v1.4.0-alpha
+will not work from v1.4.0-alpha forward.
+
+True / False attributes are created using the new attribute declaration block. Specifying that a true or false attribute
+has the value of "false" is done by using the "known false" block, and the new style of true / false
+attribute selector block, in a fact or conclusion. Stating that it has the value "true" is done by 
+merely using the new attribute selector block.
+
+This change makes the block language considerably smaller, as it replaces 4 blocks, and removes another 
+14.
+
+Significant changes have also been made to the fact interface in scenario editor, allowing for a
+number of important new features. Whereas previously, it was possible to specify known positive facts,
+and uncertainty about objects or attributes of objects, it is now possible to specify known true,
+known false, and uncertain facts, and it is possible to do that with both specific and general
+parameters.
+
+The interface has been simplified to a list of facts in natural language that can be deleted if they
+were provided by the user, and a single button that allows the user to make new statements.
+
+### Upgrade Process
+
+The process for upgrading Blawx code to this version is as follows:
+* Phase 1: Replace declarations in all sections and tests
+  * replace all category declarations with a new category declaration with the same name and NLG (typically, "object is a X")
+  * replace all attribute declarations with a new attribute declaration with the same name and NLG
+* Phase 2: Replace Usage in all sections and tests
+  * replace all boolean attribute selectors with the new style of boolean attribute selector
+  * replace all object category blocks with the new style of object category block.
+  * replace new object declarations for categories where you changed the NLG
+  * replace attribute selectors for non-boolean attributes where you changed the NLG
+  * replace category equivalence blocks with rules that use the new object category blocks in both the conditions and conclusion
+* Phase 3: Delete Orphaned Blocks
+  * find and delete orphaned true and false value blocks (explained below)
+
+Doing declarations across all code sections and tests first avoids the need to come back to any section of code more than twice.
+
+Because of changes in the type checking in attribute blocks, old-style boolean attribute blocks will reject
+the "True" or "False" value blocks, and orphan (disconnect) them. When that happens, they may not be visible in the workspace until the code has
+been saved and reloaded from save twice. All code being migrated should be opened at least
+twice, and any floating "True" or "False" blocks appearing in the top left of the workspace the second time it is opened should be deleted.
+
+There are circumstances in which adding more than one of the new style of attribute declaration block might cause
+that block not to update properly when the attribute type is set to "true / false". If this happens, add all the required attribute declarations,
+save and re-open the workspace, and the attribute declarations will then format themselves properly. This problem only occurs when migrating.
+
+**NB**: It will not be possible to migrate from pre-v1.4 code to post-v1.4 code indefinitely. At some point, old block types will be removed from the language, making upgrades more difficult or impossible. If you have code that you want to keep using, upgrade it now, or you may have to rewrite it from scratch in a future version.
+
+### Added
+* The Wills Act Tutorial example page in the documentation now links to a YouTube video demonstrating
+  the use of Blawx, and it is linked from the front page.
+
+### Changed
+* Toolboxes are reorganized
+* New Category Declaration Block
+* New Attribute Declaration Block
+* New Object Category Block
+* Examples re-implemented using new block language
+* Removed an incomplete example
+* Reformulated Beard Tax Act example
+* Improved Facts Interface in Scenario Editor
+* New Payload and Response Format for Interview endpoint
+* Revised uncertainty semantics for interview endpoint
+* Updated (some) documentation (and marked the rest as out-of-date)
+
+### Fixed
+* Explanations in the test editor were being truncated
+
+### Removed
+* Data Type Blocks
+* True and False Value Blocks
+* Category and Attribute Display Blocks
+* Category Attribute Block
+* Known Category Blocks
+* Category Equivalency Block
+
+## [v1.3.41-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.41-alpha) 2023-02-27
 
 Refactors code into a single Django app.
 
-## [v1.3.40-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.40-alpha) 2022-02-16
+## [v1.3.40-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.40-alpha) 2023-02-16
 
 Sets allowed hosts to all for testing and development purposes.
 
-## [v1.3.39-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.39-alpha) 2022-02-16
+## [v1.3.39-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.39-alpha) 2023-02-16
 
 This release adds a simple version API endpoint that can be used to check versions and as a heartbeat to test whether
 your blawx server started properly.
 
 ### Adds
 * the `/version` endpoint will now return the version of the Blawx server as a JSON object `{'version': '1.3.39-alpha'}`
 
-## [v1.3.38-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.38-alpha) 2022-02-06
+## [v1.3.38-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.38-alpha) 2023-02-06
 
 This update improves the display of answers in the scenario editor, and makes it easier for developers to
 see how the Scenario Editor uses the Blawx reasoner API.
@@ -44,7 +128,7 @@ see how the Scenario Editor uses the Blawx reasoner API.
 ### Fixes
 * Pre-defined numerical values in code or tests would crash /onto endpoint.
 
-## [v1.3.37-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.37-alpha) 2022-01-12
+## [v1.3.37-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.37-alpha) 2023-01-12
 
 This release adds features for lists and aggregation.
 
@@ -56,7 +140,7 @@ This release adds features for lists and aggregation.
 * List Demonstration example project
 * Lists feature page in documentation.
 
-## [v1.3.36-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.36-alpha) 2022-01-09
+## [v1.3.36-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.36-alpha) 2023-01-09
 
 This release allows the owner of a test to save a default set of facts that should be loaded when that test is viewed
 in the scenario editor.
@@ -72,7 +156,7 @@ in the scenario editor.
 ### Changes
 * updates documentation to reflect availability of "save as" in test editor.
 
-## [v1.3.35-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.35-alpha) 2022-01-06
+## [v1.3.35-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.35-alpha) 2023-01-06
 
 This release fixes a problem in the Covid Test example, and adds the Old Age Security Act example.
 
@@ -82,7 +166,7 @@ This release fixes a problem in the Covid Test example, and adds the Old Age Sec
 ### Changes
 * Covid Test example no longer has extraneous blocks, and uses the views feature of the scenario editor.
 
-## [v1.3.34-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.34-alpha) 2022-01-06
+## [v1.3.34-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.34-alpha) 2023-01-06
 
 This update allows you to configure, from a new tab in the scenario editor, the elements that should and should not be
 displayed when using a particular test in the user interface for collecting facts. You can choose to hide
@@ -101,7 +185,7 @@ a test is viewed in that interface.
 * the owner of the test can save the current view
 * the scenario editor automatically uses the view last saved by the test owner.
 
-## [v1.3.33-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.33-alpha) 2022-01-05
+## [v1.3.33-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.3.33-alpha) 2023-01-05
 
 This update adds "time" to Blawx's date and duration capabilities. It includes new data types,
 new data statements, a revised duration datatype, a new example, and extensive documentation.

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

@@ -17,7 +17,7 @@
 
       ## Technical Details
 
-      The attribute selector block's appearance can vary due to the attribute display block.
+      The attribute selector block's appearance is determined by the attribute declaration block.
 
       It always has two internal connectors, one for the object, and one for the value. The object
       connector accepts an object or a variable. The value connector accepts a variable, or a value

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

@@ -5,7 +5,7 @@
     content: |
       # New Attribute Block
 
-      ![New Attribute Block](/static/blawx/docs/images/blocks/new_attribute.png)
+      ![New Attribute Block](/static/blawx/docs/images/blocks/new_attribute_binary.png)
 
       ## Where Is It?
 
@@ -17,16 +17,31 @@
 
       ## Technical Details
 
-      The new attribute block must be placed inside a category attribute block, and applies
-      to the category named in the category attribute block. It requires an attribute name,
-      which must begin with a lowercase letter and not include spaces. It also requires a
-      data type, which must be one of the datatype blocks in the Data Types drawer of the Blawx
-      toolbox, or a category.
+      The new attribute block is a statement block, and can be stacked with other statements.
+
+      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,
+      either with the object appearing first, or the value appearing first.  It also accepts prefix, infix,
+      and postfix text to define how the attribute should be expressed in natural language. This information
+      will be used in the attribute selector block for this attribute, as well as in explanations.
+
+      If you choose "true / false" as the attribute type, the block will no longer collect the order or infix
+      text, as they are not required.
+
+      ![New Attribute Block](/static/blawx/docs/images/blocks/new_attribute_unary.png)
+
 
       ## Tips
 
-      Note that if you specify a data type, and not a category, your attribute selector blocks
-      for that attribute will only accept the right type of value, and variables. If you choose
-      a category as the data type, your attribute selector blocks will accept any object, or variables.
+      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.
 
-      Attribute names should be unique, even as between different categories.
+      Attribute names should be unique, even as between different categories. Boolean attributes must not
+      share names with categories.

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

@@ -19,14 +19,12 @@
 
       The new category block is a statement, and can be stacked with other statements.
 
-      The new category block accepts a single field, which is the name of the category.
-      To be valid, the name of the category must begin with a lower-case letter and not
+      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.
 
-      ## Tips
+      It also accepts text that should appear before and after the name of the object in explanations.
 
-      Multiple new category blocks with the same category
-      name will have no effect.
+      ## Tips
 
       Names of categories should be unique, but can safely
-      overlap with the names of attributes.
+      overlap with the names of non-boolean attributes.

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

@@ -18,14 +18,13 @@
       ## Technical Details
 
       The Objects drawer of the Blawx toolbox will include one new object block
-      for each defined category. By default, the new object block will read 
-      "(input) is a (category name)". However, the appearance of the new object 
-      block can be customized using the category display block. As such, the
+      for each defined category. The appearance of the new object 
+      block by the category declaration block. As such, the
       new object block may not actually include the name of the category to which
       it applies.
 
       For instance, you might have a category "person", which has a new object
-      block that reads "(input) is a human being".
+      block that reads "(object) is a human being".
 
       The new object block asserts that the named object is in the category.
 
@@ -58,6 +57,6 @@
       Note that it is not possible to declare that an object exists without assigning it to
       at least one category. But it is possible to take an object that has been created in one
       category and add it to additional categories later. This can be done by using the
-      new object block from more than one category, but with the same object name. The safer
+      new object block multiple times with different categories, but with the same object name. The safer
       method, however, is to create the object once, and then use the object category block
       to assign additional categories to it.

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

@@ -20,8 +20,8 @@
 
       The object category block is a statement block, and can be stacked with other statements.
 
-      The first internal connector expects an object or a variable. The second internal connector
-      expects a category selector.
+      The first internal connector expects an object or a variable. The second dropdown field
+      allows you to select a category.
 
       In a question or in the conditions of a rule or constraint, the block checks to see whether the object is
       a member of the category. In a conclusion or in a fact, it asserts that the membership is true.

blawx/fixtures/docs/components/interface.yaml

@@ -26,14 +26,13 @@
       * Help - This will open the Blawx Documentation
       * Save - This will save the currently selected section's code to the Blawx server
       * Exit - This will return you to the Rule screen for the current Rule.
-      * Tutorial - This appears only if the current workspace includes tutorial content, and will display
-        the tutorial pane on the right side of the screen.
+      
 
       If you are using the Test Editor, there are three additional buttons:
 
       * Run - Runs the test in the test editor, opens up the output pane and displays the
         results.
-      * Bot - Starts BlawxBot using the current test.
+      * Scenario Editor - Starts Scenario Editor using the current test.
       * Delete - Deletes the current test from the Rule, and returns you to the Rule screen.
 
       In the Test Editor, there is also a "Save As" option that can be accessed by clicking on the drop-down
@@ -155,9 +154,9 @@
 
       ![Inputs](/static/blawx/docs/images/inputs.png)
 
-      Inputs may expect certain kinds of information. For example, the category
-      attribute block has an input that requires a category selector. If you
-      try to use a block that is not a category selector, it will not "fit".
+      Inputs may expect certain kinds of information. For example, the math operation block
+      accepts two number values, or variables. If you
+      try to use an object selector, it will not "fit".
 
       ![Inputs That Don't Fit](/static/blawx/docs/images/doesnt_fit.gif)