Settings

Perform the necessary Imports.

In [1]: import sys
   ...: from truealgebra.core.settings import(
   ...:     settings, bp
   ...: )
   ...: from truealgebra.core import setsettings
   ...: from truealgebra.core.constants import (
   ...:     DIGITS, LETTERS, WHITE_SPACE, OPERATORS, META_DELIMITERS
   ...: )
   ...: from truealgebra.core import expressions as expr
   ...: 

From The module truealgebra.core.settings is imported the settings object which is a singleton.

In [2]: type(settings)
Out[2]: truealgebra.core.settings.SettingsSingleton

The data inside seettings provides the envioroment for a truealgebra session. It primarily controls the parsing that creates truealgebra expressions from python strings.

To avoid confuion, for a truealgebra session, there should be only one environment. At the beginning of a truealgebra session the settings should be adjusted as desired at the beginning of the session and kept unchanged throughout the rest of the session.

Constants

The five python constants shown below are used during parsing or when a user manually creates truealgebra expressions. The first three constants are required knowledge for a user writing code to instantiate expressions through application of a rule.

In [3]: print('DIGITS =  ' + str(DIGITS))
   ...: print('LETTERS =  ' + str(LETTERS))
   ...: print('OPERATORS =  ' + str(OPERATORS))
   ...: print('WHITE_SPACE =  ' + str(WHITE_SPACE))
   ...: print('META_DELIMITERS =  ' + str(META_DELIMITERS))
   ...: 
DIGITS =  {'3', '5', '1', '6', '2', '0', '8', '4', '7', '9'}
LETTERS =  {'j', 'D', 'f', 'P', 'v', 'u', 'O', 'z', 'E', 'x', 'U', 'I', 'J', 'n', 'g', 'p', 'w', 'T', 'y', 's', 'Q', 'A', 'H', 'o', 'F', 'b', '_', 'Z', 'l', 'V', 'W', 'L', 'a', 'R', 'B', 'd', 'M', 'c', 'K', 'r', 'C', 'X', 'k', 'e', 'Y', 'G', 'N', 'S', 'i', 'm', 'h', 't', 'q'}
OPERATORS =  {'+', ':', '?', '`', '/', '@', '>', '%', '<', '*', '!', '^', '=', '~', '-', '&', '|', '\\', '"'}
WHITE_SPACE =  {'\t', ' '}
META_DELIMITERS =  {';', '\n'}

These constant are sets and the characters are printed without order. The settings.DIGITS set contains the digits 0 through 9. The settings.LETTERS set contains the lower and upper case alphabet characters as well as the number sign and underscore characters.

Definitions

In order to facilitate the discussion, the following definitions have been made.

Binding Power

A binding power is a python object of type int and equal to or greater than 0. Binding powers are used during parsing.

Every truealgebra expression has two binding powers assigned to lbp (left binding power) and rbp (right binding power) attributes. These attributes can be either class or instance attributes. See lbp and rbp attributes.

Symbol Name

A symbol name is a nonempty python string made up of characters from the constants LETTERS and DIGITS. There is no limit on the length of a symbol name. The first character must be one of the characters in the set LETTERS. The remaining characters can only be from the set LETTERS or the set DIGITS.

The name attribute of a Symbol instance must be a symbol name. A symbol name is also the first naming convention for name attributes of Container instances.

Operator Name

An operator name is a nonempty python string made up of characters from the set settings.OPERATORS. Operator names are the second naming convention for name attributes of Container instances.

Settings are python objects that should be modified as needed by users.

bp

bp is a namedtuble, used to create immutable objects that holds left and right binding powers.

An instance of the bp named tuple class below, holds two binding powers. The object my_bp_tuple is a bp instance. The 250 parameter becomes the lbp attribute of the instance and the 600 parameter becomes the rbp attribute. The lbp stands for left binding power and rbp stands for right binding power.

In [4]: my_bp_tuple = bp(250, 600)
   ...: print(my_bp_tuple.lbp)
   ...: print(my_bp_tuple.rbp)
   ...: 
250
600

Settings Attributes

The attributes of the settings object hold the actual data that is set.

It is strongly recomended that users do not modify the attributes directly. To prevent hidden errors that are difficult to debug, use the Set Functions.

default_bp

This setting is used during parsing to provide the default left and right binding powers for Container instances with operator names.

The default_bp settings attribute is a bp class instance containing two positive binding powers. The default value for default_bp is bp(250, 250).

In [5]: print(settings.default_bp)
   ...: settings.default_bp = bp(275, 276)
   ...: print(settings.default_bp)
   ...: 
bp(lbp=250, rbp=250)
bp(lbp=275, rbp=276)

custom_bp

The custom_bp setting is used during parsing to specify custom binding powers for Container instances with operator names to be parsed as operators.

The custom_bp attribute is a dictionary which by default is empty. A dictionary key must be an operator name. A dictionary values must be an instance of bp containing two binding powers. Both binding powers cannot be 0. If the dictionary key is also a key for settings.infixprefix then both binding powers must be positive.

In [6]: print(settings.custom_bp)
   ...: settings.custom_bp['*'] = bp(400, 400)
   ...: settings.custom_bp['!'] = bp(600, 0)
   ...: print(settings.custom_bp)
   ...: 
{'=': bp(lbp=50, rbp=50)}
{'=': bp(lbp=50, rbp=50), '*': bp(lbp=400, rbp=400), '!': bp(lbp=600, rbp=0)}

infixprefix

The infixprefix settings attribute is used during parsing to specify Container instances that can be both infix and prefix operators.

This setting is a dictionary and by default it is empty. A dictionary key must be an operator name. The dictionary value must be a positive binding power. The infix form of the Container instance must have both binding powers positive.

In [7]: print(settings.infixprefix)
   ...: settings.infixprefix['-'] = 800
   ...: print(settings.infixprefix)
   ...: 
{}
{'-': 800}

symbol_operators

This setting is used during parsing to specify Container instances with symbol names that will be parsed as operators.

The symbol_operator setting is a dictionary which by default is empty. The dictionary key must be a symbol name. The dictionary value must be a settings.bp instance that contains two binding powers. Both binding powers cannot be 0. A dictionary key cannot also be a key in settings.bodied_functions.

In [8]: print(settings.symbol_operators)
   ...: settings.symbol_operators['and'] = bp(325, 425)
   ...: print(settings.symbol_operators)
   ...: 
{'and': bp(lbp=75, rbp=75)}
{'and': bp(lbp=325, rbp=425)}

bodied_functions

The bodied_functions setting is used during parsing to specify Container instances that will parsed as bodied functions.

The bodied_functions setting is a dictionary which is by default empty. A dictionary key must be an symbol name. A dictionary value must be a positive integer.Both binding powers cannot be 0. A dictionary key cannot also be a key in settings.symbol_operators.

In [9]: print(settings.bodied_functions)
   ...: settings.bodied_functions['D'] = 100
   ...: print(settings.bodied_functions)
   ...: 
{}
{'D': 100}

container_subclass

The container_subclass setting links name attributes with Container subclasses. This setting is used during parsing when Container instances are instantiated.

This setting is a dictionary that is by default empty. The dictionary key must be symbol or operator name. The dictionary value must be a Container subclass.

In [10]: print(settings.container_subclass)
   ....: settings.container_subclass['*'] = expr.CommAssoc
   ....: print(settings.container_subclass)
   ....: 
{'*': <class 'truealgebra.core.expressions.CommAssoc'>}
{'*': <class 'truealgebra.core.expressions.CommAssoc'>}

complement

The complement setting is used to specify an attribute name of a Container instance that complements an attribute name of a CommAssoc instance. During parsing, A Container instance will be converted to a CommAssoc instance that it complements.

The complement setting is a dictionary that is by default empty. A dictionary key must be either a symbol name or operator name. The dictionary value must be a settings.commassoc_tuple named tuple instance.

The name attribute of the named tuple must also be the name attribute of CommAssoc instances. The identity attribute of the named tuple must be an expression that represents the mathematical identity of the mathematical operation represented by the CommAssoc instances.

The string '*', was assigned above as an attribute name for CommAssoc instances.

In the example below, Container instances with a attribute name of 'star' complement CommAssoc instances with name '*'.

SKIP:

.. ipython::

    In [1]: print(settings.complement)
       ...: settings.complement['star'] = settings.commassoc_tuple(
       ...:     name='*',
       ...:     identity=expr.Number(1),
       ...: )
       ...: print(settings.complement)

container_categories

The container_categories setting can used by rules to identify the name attribute of Container instances that fall in a particular category. Categories are strings and there are no predefined categories. Any string can be used for a category.

Consider the example below where the category is suchthat_names. Any Container instance with a name attribute in the set settings.container_categories['suchthat_names'] is said to be in the suchthat_names category. A rule that has been written for the suchthat_names category would apply to Container instances with a name attribute of ':' or '|'.

The container_types setting is a default dictionary with a default value of an empty set. The truealgebra.core.settings module initializes an empty dictionary. Every dictionary key must be a string. Every dictionary value is a set that can contain only symbol names or operator names.

SKIP:

.. ipython::

    In [1]: print(settings.container_categories)
       ...: settings.container_categories['suchthat_names'].add('|')
       ...: settings.container_categories['suchthat_names'].add(':')
       ...: print(settings.container_categories)

Setting Tools

The setting tools are functions related to the environment settings. Setting tools are found in the module truealgebra.core.setting_tools.

Utility Functions

clear_settings(): Returns all settings to their default value. This function is especially helpful with unit tests.
isbindingpower(num): Returns True if num is a binding power, otherwise returns False.
issymbolname(name): Returns True if name is a symbol name, otherwise returns False.
isoperatorname(name): Returns True if name is an operator name, otherwise returns False.

Set Functions

In the following function definitions, the parameters lbp and rbp stand for left and right binding power. If mistakes are made when using these functions, error messages will be printed and no cahnges to the settings will be made,

set_default_bp(lbp, rbp): Assigns new named tuple settings.bp instance for setting settings.default. The parameters lbp and rbp must be positive binding powers.
set_custom_bp(name, lbp, rbp): Add or reassign key to settings.custom_bp dictionary. The key is the parameter name which must be an operator name. The parameters lbp and rbp must be binding powers. Both lbp and rbp cannot be 0.
set_infixprefix (name, rbp): Add or reassign key to settings.infixprefix dictionary. The key is the parameter name which must be an operator name. The parameter rbp must be a positive binding power. The infix form of the name must have both binding powers positive.
set_symbol_operators (name, lbp, rbp): Add or reassign key to settings.symbol_operators dictionary. The key is the parameter name which must be a symbol name. The parameter name cannot be a key in the setting settings.bodied_functions dictionary. The parameters lbp and rbp must be binding powers. Both lbp and rbp cannot be 0.
set_bodied_functions(name, rbp): Add or reassign key to settings.bodied_function dictionary. The key is the parameter name which must be a symbol name. The parameter name cannot be a key in the setting settings.symbol_operators dictionary. The parameters rbp must be a positive binding power.
set_container_subclass(name, cls): Add or reassign key to settings.container_subclass dictionary. The key is the parameter name which must be a symbol name or an operator name. The parameter cls must be a Container subclass.
set_complement(complement_name, commassoc_name, identity): Add or reassign key to settings.complement dictionary. The key is the parameter complement_name which must be a symbol name or an operator name. The parameter commassoc_name must be a key in settings.container_subclass pointing to CommAssoc. The parameter identity must be a truealgebra expression.
set_container_categories(category, name): Add or reassign key to settings.container_categories dictionary. The key is the parameter catgegory which must be a string. The parameter name which must be symbol name or operator name is the corresponding value

Set Function Error Example

All three parameters of settingst.set_custom_bp have flaws. Error messages are printed and no changes made to the setting settings.custom_bp.

In [11]: print('custom_bp=  ' + str(settings.custom_bp))
   ....: setsettings.set_custom_bp('q@d$', -300, 'four')
   ....: print('custom_bp=  ' + str(settings.custom_bp))
   ....: 
custom_bp=  {'=': bp(lbp=50, rbp=50), '*': bp(lbp=400, rbp=400), '!': bp(lbp=600, rbp=0)}
TRUEALGEBRA ERROR!
set_custom_bp error
    name q@d$ must be an operator name.
    lbp -300 must be a binding power
    rbp four must be a binding power
custom_bp=  {'=': bp(lbp=50, rbp=50), '*': bp(lbp=400, rbp=400), '!': bp(lbp=600, rbp=0)}