# Tt – A Truth Table and Karnaugh Map Command-Line Tool

## Synopsis

tt is a command line tool for truth table and Karnuagh Map generation. It currently features syntax checking of Boolean equations and output of corresponding truth tables.

## Installation

tt has been tested with Python 2.7, 3.3, 3.4, and 3.5. tt is written in pure Python, so it only requires a compatible Python installation to run.

You can get the latest release from PyPI:

`\$ pip install ttable`

Using this method, you can invoke tt with:

`\$ tt`

If you want to get the most up to date stable version, you can get the sources directly with:

`\$ git clone https://github.com/welchbj/tt.git && cd tt && git checkout develop`

If you install tt using the git approach, you will have to invoke it directly with Python. This can be done with:

`\$ python -m tt`

## Command Line Use

All you need to specify to tt is your Boolean equation, which can be optionally surrouded in double quotes. Right now, tt assumes that your output variable will be on the left side of your equals sign and that the equivalent expression will be on the right side of the equals sign.

You can use the `--table` option to output a truth table of your passed equation. Omitting all options except for the required equation will default to truth table generation, too.

A simple example:

`\$ tt --table F = A and B +---+---+---+ | A | B | F | +---+---+---+ | 0 | 0 | 0 | | 0 | 1 | 0 | | 1 | 0 | 0 | | 1 | 1 | 1 | +---+---+---+`

tt can handle more complex variable names, too:

`\$ tt --table out = operand_1 or operand_2 +-----------+-----------+-----+ | operand_1 | operand_2 | out | +-----------+-----------+-----+ |     0     |     0     |  0  | |     0     |     1     |  1  | |     1     |     0     |  1  | |     1     |     1     |  1  | +-----------+-----------+-----+`

tt can handle more complex Boolean operations and syntax, as well:

`\$ tt --table out = (op1 xor (op2 and op3)) nand op4 +-----+-----+-----+-----+-----+ | op1 | op2 | op3 | op4 | out | +-----+-----+-----+-----+-----+ |  0  |  0  |  0  |  0  |  1  | |  0  |  0  |  0  |  1  |  1  | |  0  |  0  |  1  |  0  |  1  | |  0  |  0  |  1  |  1  |  1  | |  0  |  1  |  0  |  0  |  1  | |  0  |  1  |  0  |  1  |  1  | |  0  |  1  |  1  |  0  |  1  | |  0  |  1  |  1  |  1  |  0  | |  1  |  0  |  0  |  0  |  1  | |  1  |  0  |  0  |  1  |  0  | |  1  |  0  |  1  |  0  |  1  | |  1  |  0  |  1  |  1  |  0  | |  1  |  1  |  0  |  0  |  1  | |  1  |  1  |  0  |  1  |  0  | |  1  |  1  |  1  |  0  |  1  | |  1  |  1  |  1  |  1  |  1  | +-----+-----+-----+-----+-----+`

tt doesn’t limit you to plain English operations, either. The equation is surrounded in quotes below to avoid escaping the | and & characters in the terminal:

`\$ tt --table "F = ~(A || B) && C" +---+---+---+---+ | A | B | C | F | +---+---+---+---+ | 0 | 0 | 0 | 0 | | 0 | 0 | 1 | 1 | | 0 | 1 | 0 | 0 | | 0 | 1 | 1 | 0 | | 1 | 0 | 0 | 0 | | 1 | 0 | 1 | 0 | | 1 | 1 | 0 | 0 | | 1 | 1 | 1 | 0 | +---+---+---+---+`

And if you wanted a Karnaugh Map for that equation:

`\$ tt --kmap "F = ~(A || B) && C" A / B C      00      01      11      10   +-------+-------+-------+-------+ 0 | 0     | 1     | 3     | 2     |   |   0   |   1   |   0   |   0   |   |       |       |       |       |   +-------+-------+-------+-------+ 1 | 4     | 5     | 7     | 6     |   |   0   |   0   |   0   |   0   |   |       |       |       |       |   +-------+-------+-------+-------+`

tt provides syntax checking for your equations, too. Below are a few examples.

Too many equals signs:

`\$ tt "out == A or B" ERROR: Unexpected equals sign. ERROR: out == A or B ERROR:      ^`

Unbalanced parentheses:

`\$ tt --table "out = ((A and B) or C))" ERROR: Unbalanced right parenthesis. ERROR: ((A and B) or C)) ERROR:                 ^`

Malformed equation:

`\$ tt out = A or (B and and C) ERROR: Unexpected operation. ERROR: A or (B and and C) ERROR:             ^`

## Development

The tt development pipeline was built with all major OSes in mind, and all command line instructions should be identical no matter what terminal or cmd prompt you’re using. All common development tasks should have a corresponding make target (either in make.bat or the Makefile). If you can’t find a target that you find yourself needing frequently, please feel free to add it! Please note, though, that the two "make" files are meant to be functionally equivalent, so please don’t change one without updating the other.

It is recommended that all development is done in a virtualenv . virtualenvwrapper is super helpful, too.

Please note: All below examples are assumed to be done from within the top-level tt directory; this is where the make files reside.

The dependencies for different setups of tt environments are defined in the tt/reqs directory. For development, you can install the appropriate development packages with:

`\$ make install-reqs`

This file can easily be updated with your current environment’s installed packages with the target:

`\$ make write-reqs`

We ask that you update the production requirements.txt manually, as there should be significantly fewer required packages for the published releases and we want to keep the install as lean as possible.

Running tt’s tests is pretty easy, too. You can run all the Python unittests at once with:

`\$ make test`

Alternatively, you can invoke the Python unittest module directly to run different groups of tests:

`\$ python -m unittest discover -s tt/tests/unit \$ python -m unittest discover -s tt/tests/functional`

For formatting of the code, tt tries to follow PEP8 closely. flake8 is used to ensure that the code complies with this standard. Additionally, Google style docstrings are used. The docstrings in tt are modelled after the nice examples in the napoleon documentation .

tt is designed to be a thoroughly tested application. Its test are divided into two groups:

1. unit – For testing individual methods and pieces of functionality
2. functional – For simulating actual use of the application by capturing what is sent to stdout and stderr

Cross Python version testing is made easy with tox . The configuration of thetox.ini file allows for the proper testing against Python 2.7, 3.3, 3.4, and 3.5 just by invoking the `tox` command in the top-level directory of the project, regardless of your platform. The flexiblity of tox makes tt’s CI on Travis CI and AppVeyor pretty seamless.

The git structure of tt is pretty simple, as tt is a pretty simple application itself. Each release has its own branch. Branch names are in the form v{major.minor}. If a branch passes the builds by Travis CI and AppVeyor, then it is considered stable and should be merged into the develop branch.

Once a release is completed, the develop branch will be merged into the master branch, and the master branch will be tagged with the corresponding version, in the form release-{major}.{minor}. Following these guideleines, any clone from the master or develop branch should yield a functioning version of tt, with master being a fully stable release.

Below indicates what is aimed to be included in the releases leading up to v1.0:

• v0.1

1. Initial release
• v0.2

1. introduce the project’s setup.py file
2. add Windows make file
3. improve requirements management, for both production and development
4. update README, in reStructuredText instead of markdown
5. introduce functional test framework
6. initial publish to PyPI
• v0.3

1. integrate with Travis CI
2. integrate with AppVeyor
3. introduce Karnaugh Map functionality
4. port Windows make file to *nix
• v0.4

1. add indication of optimal groupings on Karnaugh Maps
2. improve verbose output and logging
3. implement minimization of equations, using Quine–McCluskey algorithm
4. add option to order inputs in truth table alphabetically (–alphabetical)
5. introduce functionality to generate logic circuit diagrams from equations
• v0.5

1. if too many options are present, we can look into the idea of using argument sub-groups (already supported by Python’s argparse)
2. add more Boolean operations, such as "if and only if" (<->) and "implies" (->)
3. product-of-sum (–pos) and sum-of-product (–sop) form generation for Boolean equations