-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
14 additions
and
148 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,167 +1,33 @@ | ||
| # Boolean Expression Parser <!-- omit in toc --> | ||
|
|
||
| A simple boolean expression parser written in C#. It parses boolean expressions and prints out a truth table for each expression. | ||
| A library and accompanying CLI and WebUI for parsing, evaluating and generating truth tables for boolean logic expressions. | ||
|
|
||
|
|
||
| ## Contents <!-- omit in toc --> | ||
|
|
||
| - [Running](#running) | ||
| - [Building](#building) | ||
| - [Display](#display) | ||
| - [Base Command](#base-command) | ||
| - [Truth table generation](#truth-table-generation) | ||
| - [Notation conversion](#notation-conversion) | ||
| - [Expressions](#expressions) | ||
| - [Variables](#variables) | ||
| - [How it works](#how-it-works) | ||
| - [1. Tokenisation](#1-tokenisation) | ||
| - [2. Parsing](#2-parsing) | ||
| - [3. AST](#3-ast) | ||
| - [4. Evaluation](#4-evaluation) | ||
| - [Example expressions](#example-expressions) | ||
| - [Roadmap](#roadmap) | ||
| - [Make up of the project](#make-up-of-the-project) | ||
| - [Wiki](#wiki) | ||
| - [Found an issue?](#found-an-issue) | ||
|
|
||
|
|
||
| ## Running | ||
|
|
||
| After downloading a release from the Releases section to the right, you can run the program on either Windows or Linux by running `BooleanExpressionParser.exe` or `BooleanExpressionParser` in the terminal respectively. Note, you'll need .NET 7 installed on your machine to run the program. | ||
| ## Make up of the project | ||
|
|
||
| There are three main parts to the project: | ||
|
|
||
| ## Building | ||
| - The library, which is the core of the project. It contains the logic for parsing, evaluating and generating truth tables for boolean expressions. | ||
| - This is the C# project named `BooleanExpressionParser`. | ||
| - The CLI, which provides a easy-to-use command line interface for the library. | ||
| - This is the C# project named `BooleanExpressionParser.CLI`. | ||
| - The WebUI, which is a Blazor WebAssembly appplication built ontop of an ASP.NET server. It provides a web interface for the library. | ||
| - This is the C# project named `BooleanExpressionParser.Web`. | ||
|
|
||
| To build the project, you'll need .NET 7 installed. You can then build the project with `dotnet build` or run it with `dotnet run`. Alternatively, you can open the project in Visual Studio or Visual Studio Code, the latter of which has config in the repo. | ||
|
|
||
| ## Wiki | ||
|
|
||
| ## Display | ||
|
|
||
| The application displays an intuitive, coloured truth table output for each boolean expression: | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## Base Command | ||
| `./BooleanExpressionParser [command] [options]` | ||
|
|
||
| ### Options: <!-- omit in toc --> | ||
| - `-o`, `--output`, `--output-type` `<Basic|Display>` The output type to use. | ||
|
|
||
|
|
||
| ## Truth table generation | ||
| Prints the truth table of a boolean expression(s). If none are provided, the user will be prompted to enter them. | ||
|
|
||
| ### Usage: <!-- omit in toc --> | ||
| `./BooleanExpressionParser table [<expression(s)>...] [options]` | ||
| ### Arguments: <!-- omit in toc --> | ||
| - `<expression(s)>` The boolean expression(s) to evaluate. | ||
| ### Options: <!-- omit in toc --> | ||
| - `-t`, `--true` `<true>` Character to use for true values in the truth table. [default: 1] | ||
| - `-f`, `--false` `<false>` Character to use for false values in the truth table. [default: 0] | ||
| - `-c`, `--colour-mode`, `--color-mode` `<Background|Foreground|None>` Colour mode to use for the truth table. [default: Foreground] (possible values: [Ff]oreground, [Bb]ackground, [Nn]one) | ||
| - `--true-colour`, `--true-color` `<true-colour>` Colour to use for true values in the truth table. [default: green] (possible values: 16 ANSI colours, hex string, rgb string) | ||
| - `--false-colour`, `--false-color` `<false-colour>` Colour to use for false values in the truth table. [default: red] (possible values: 16 ANSI colours, hex string, rgb string) | ||
|
|
||
|
|
||
| ## Notation conversion | ||
| Converts a boolean expression(s) to postfix notation. If none are provided, the user will be prompted to enter them. | ||
|
|
||
| ### Usage: <!-- omit in toc --> | ||
| `./BooleanExpressionParser convert [<expression(s)>...] [options]` | ||
| ### Arguments: <!-- omit in toc --> | ||
| - `<expression(s)>` The boolean expression(s) to convert | ||
|
|
||
|
|
||
| More commands to be implemented in the future. | ||
|
|
||
| For help, run `./BooleanExpressionParser --help`. For help with a specific command, run `./BooleanExpressionParser [command] --help` or `./BooleanExpressionParser --help [command]`. | ||
|
|
||
|
|
||
|
|
||
| ## Expressions | ||
|
|
||
| Shown below is a list of supported operators. Each operator's aliases are listed in brackets. | ||
|
|
||
| - AND (`&`, `.`) | ||
| - OR (`|`, `+`) | ||
| - NOT (`!`, `¬`) | ||
| - XOR | ||
| - NAND | ||
| - NOR | ||
| - XNOR | ||
| - IMPLIES (`=>`) | ||
|
|
||
| Of course, you can also use brackets to group expressions. Every type of bracket can be used, which may help distinguish groupings: `()` `[]` `{}` | ||
|
|
||
|
|
||
| ## Variables | ||
|
|
||
| Any characters in an expression which arent operators or brackets are considered variables. The parser will automatically generate a truth table for each variable. Variables can be several characters long, which allows for numbered variables (`A1`, `A_2`, etc.). | ||
|
|
||
| To provide an order in which the variables should be printed, give a comma separated list of variables after your expression, separating these parts with a semicolon (`;`). If this isn't given, the truth table is generated in the order the variables are found in the expression. | ||
|
|
||
| For example: | ||
| - The expression "D0.!S + D1.S" would generate a truth table ordered D0, D1, S. | ||
| - The expression "D0.!S + D1.S;S,D0,D1" would generate a truth table ordered S, D0, D1. | ||
|
|
||
|
|
||
|
|
||
| ## How it works | ||
|
|
||
| ### 1. Tokenisation | ||
| - Input is split into tokens. These tokens are internal representations of the input. | ||
| - Tokens are either operators, variables, or brackets. | ||
| - For example, the input `A & ! B` would be tokenised into [`A`, `AND`, `NOT`, `B`]. | ||
|
|
||
|
|
||
| ### 2. Parsing | ||
| - Tokens are parsed into postfix or [Reverse Polish notation](https://en.wikipedia.org/wiki/Reverse_Polish_notation), using the (slightly modified) Shunting-yard algorithm. | ||
| - Postfix notation removes the need for brackets, and makes it easier to evaluate the expression. In this notation, the operator is placed before the operands (rather than in between them). | ||
| - Our tokenised list, [`A`, `AND`, `NOT`, `B`] would be parsed into [`A`, `B`, `NOT`, `AND`]. | ||
|
|
||
|
|
||
| ### 3. AST | ||
| - The parsed tokens are then converted into an AST (Abstract Syntax Tree). This is so that the expression can be evaluated and easily traversed. | ||
| - An AST consists of several nodes, each with children nodes (0, 1, or 2 depending on its type). Each node represents an operator or variable. | ||
| - Our parsed list, [`A`, `B`, `NOT`, `AND`], would be converted into the following AST: | ||
| ``` | ||
| AND | ||
| ├── A | ||
| └── NOT | ||
| └── B | ||
| ``` | ||
| ### 4. Evaluation | ||
| - Finally, the AST is evaluated, and a truth table is printed out for the expression. | ||
| - Evaluation simply traverses the AST and evaluates each node recursively, using the values of its children. | ||
| - Each expression is evaluated using every possible set of inputs which is then collated into a truth table. | ||
| ## Example expressions | ||
| - `A & B` | ||
| - A simple AND gate | ||
| - `A OR B` | ||
| - A simple OR gate | ||
| - `!S . D_0 + D_1 . S` | ||
| - A 2-1 multiplexer | ||
| - `(!S0 AND ¬S1 . D0) | (NOT{S0} . S1 . D1) + (S0 . {¬S1 & D2}) OR [S0 . S1 AND D3]` | ||
| - A 4-1 multiplexer, using several aliases for operators and brackets | ||
| ## Roadmap | ||
| - [x] Implement basic expression parsing and evaluation | ||
| - [x] Implement truth table generation and display | ||
| - [x] Improve console output with colours | ||
| - [x] Implement command line arguments | ||
| - [ ] Add raw output options | ||
| - [x] Output postfix notation | ||
| - [ ] Output specific output for given variables | ||
| - [x] Output machine-readable truth table | ||
| - [ ] Create UI for the application, either web-based or desktop-based | ||
| For more information about usage, project structure, and functionality, please see the [wiki](https://github.com/tomc128/boolean-expression-parser/wiki). | ||
|
|
||
|
|
||
| ## Found an issue? | ||
|
|
||
| If you've found an issue, like an expression that casuses a crash or an incorrectly parsed expression, please open an issue on GitHub. Please include the expression that caused the issue, thank you! | ||
| If you've found an issue, like an expression that casuses a crash or an incorrectly parsed expression, please open an issue on GitHub. Please include the expression that caused the issue, thank you! Or, if you're able to, fork the repo and fix it yourself. Pull requests are welcome! |