CUSTOMIZING

CUSTOMIZING
===========

You can customize EC by adding, deleting, or modifying the various actions
available. To do so, it is useful to know a little about how it is put together.

EC is constructed from the following files:

    calculator.py:
        Foundation of the calculator, contains the class definitions used to
        construct the calculator.
    actions.py:
        Contains the definitions of all actions available, including operators,
        functions, numbers, formats, and commands. It should be possible to
        confine any customization to this file.
    ec.py:
        Provides a command line interface for the calculator.

calculator.py provides a collection of class definitions that are used implement
the various types of available actions. Those classes include:

    Command (matches a key, pops 0, pushes 0)
    Constant (matches a key, pops 0, pushes 1)
    UnaryOp (matches a key, pops 1, pushes 1)
    BinaryOp (matches a key, pops 2, pushes 1)
    BinaryIoOp (matches a key, pops 2, pushes 2)
    Dup (matches a key, peeks 1, pushes 1)
    Number (matches a pattern, pops 0, pushes 1)
    SetFormat (matches a pattern, pops 0, pushes 0)
    Help (matches a pattern, pops 0, pushes 0)
    Store (matches a pattern, peeks 1, pushes 0)
    Recall (matches a pattern, pops 0, pushes 1)
    SetUnits (matches a pattern, pops 1, pushes 1)
    Convert (matches a pattern, pops 1, pushes 1)
    Print (matches a pattern, pops 0, pushes 0)
    Category (not an action, merely a header in the help summary)

To get more information about each of these classes, open a Python shell, import 
calculator, and apply the help function on the class you are interested in. For 
example to get more information on Command:

    $ python
    >>> from calculator import *
    >>> help(Command)


Adding Actions
--------------

An action is created by instantiating one of these classes.  Generally the
function that implements the desired action is passed into the constructor for
one of these classes along with various parameters that describe the action.

These classes take many of the same arguments when they are instantiated.  
Generally they take either *key* or *pattern*. *key* is used when the action 
would be triggered when the user enters a fixed string. Examples include
functions such as *sin*, operators such as *+*, and commands such as *dup*.
*pattern* is used for actions that are triggered by regular expressions, such
numbers and commands that take arguments, such as *sci* and save or recall. When
*pattern* is specified, *name* must be given. It gives a name for those actions
so that the user can ask for help on them. Other arguments are *description*,
*summary*, and *synopsis*. *description* is a half-line description of the
action that should take the form "label: description". The label should either
be *key* or a abstraction of *pattern*. You can use "%(name)s" within the string
to access attributes within the action, and generally parameters to the constructor
are saved as attributes with the same name. So it is common to use something
like "%(key)s: description ..." as a description. *summary* is a longer
description that is presented to the user when they ask for help. It is also
used to describe the action in the man page. Finally, *synopsis* is a brief
description of the effect on the stack of the action.

In each of these strings (*description*, *summary*, and *synopsis*), you can use 
simple inline macros to do the following:
    #⟪text⟫: set text in italics
    @⟪text⟫: set text in bold
    \verb⟪
        text
    ⟫: set text alone on a line or lines while maintaining line breaks
So, "#⟪x⟫ + #⟪y⟫" will be rendered as "x + y" with *x* and *y* in italics. The 
beginning and end of a type face specifier (#⟪…⟫ or @⟪…⟫) must fall on the same 
line and the specifiers must not be nested.  For the no fill directive (\verb⟪⟫) 
the beginning and end must be alone on their lines. For example, to illustrate 
the computation of one half, you might use:
\verb⟪
    @⟪0⟫: 1 2/
    @⟪500m⟫:
⟫

Simply instantiating one of these classes does not add this action to the 
calculator. To do that, you place the objects created by instantiating these 
classes into a list called 'actionsToUse'. It is imported by ec.py and used to 
initialize the calculator.  Several list of actions suitable for different 
disciplines are collected into lists that can easily be assigned to 
'actionsToUse'. This provides an easy way change the personality of the 
calculator. The following lists are predefined:
    allActions
    engineeringActions
    physicsActions
    chemistryActions
To change the personality, simply assign the desired list to 'actionsToUse'.


Changing Defaults
-----------------

Besides 'actionsToUse', three other variables are imported by ec.py and used
when initializing the calculator:
    actionsToUse: A list of actions to be made available by the calculator.
    predefinedVariables: A dictionary of variables that should be predefined
        each variable consists of a name (a string) and a value (a tuple
        consisting of a number (the value) and a string (the units)).
    defaultFormat: An object of the SetFormat class that specifies the initial
        format the calculator uses.
    defaultDigits: An integer that specifies how many digits should be initially
        used.
In addition, there are several other variables that affect the creation of the
man page:
    documentIntegers: Set this to true if your list of actions includes the
        ability to enter and display integers of various bases. It adds the
        section on integers to the man page.
    documentVerilogIntegers: Set this to true if your list of actions includes
        the ability to enter and display Verilog integers of various bases. It
        chooses the section on integers to be the one that include documentation
        of Verilog integers to the man page.
    documentComplexNumbers: Set this to true if your list of actions includes
        the ability to create and operate on complex numbers. It adds the
        section on complex numbers to the man page.


Adding Unit Conversions
-----------------------

In actions.py you will find a section of code labeled Unit Conversions.  It 
contains a series of instantiations of the QuantiPhy UnitConversion class 
(https://quantiphy.readthedocs.io/en/stable/api.html#quantiphy.UnitConversion).

You can add your own unit converters simply by adding more instantiations of 
UnitConversion.  It takes three to four argumentsarguments: the list of the 
to-units, the list of the from-units, and the slope and the intercept.  The 
intercept is optional and is used for affine conversion (like temperature 
conversions).