quickmathjs

Quick MathJS Web Calculator (https://www.quickmathjs.com/)

QuickMathJS is an intuitive web-based plaintext calculator powered by math.js. Designed to deliver inline results, it supports free-form calculations without the fuss of special syntax. Much like how markdown mirrors the natural writing style of emails, QuickMathJS emulates the informal way people jot down mathematical expressions in everyday communications. It's math, made as simple as typing out your thoughts.

• This has also been adapted for VSCode and Codium in an extention called QuickCalc

Quick Links:

• https://www.quickmathjs.com/ Try Online Interface
• Download for Offline Use

Motivation

Inspired by SpeQ Mathematics, this project aims to offer an experience where all calculations feel like working within a simple text file. Two key goals drive this project:

• Copy-Paste Integrity: Users should be able to copy and paste calculations seamlessly.
• Offline Usability: The calculator should work without an internet connection, echoing the simplicity of a local app.

Features

• Inline results: Displays results immediately after the expression.
• Variable assignments: Use variables in your calculations.
• Auto-calculation: Evaluates when you press Enter.
• Error handling: Shows inline error messages.
• CLI version available.
• Created with the combined efforts of ChatGPT and humans.

Getting Started

Web Version

1. Try it Online: Click here
2. Offline Version: Download the latest release, extract, and open index.html.

CLI Version: QuickMathJS CLI

Note: The CLI tool is a command-line interface to use QuickMathJS. However, if you're interested in integrating the calculation functionalities into your own Node.js applications, you can use quickmathjs as an npm module. See the section below on "Using as a Node.js Module" for more details.

The CLI offers the same heuristic-based evaluation as the web interface, allowing you to naturally type in mathematical expressions without the need for special syntax. It is perfect for users who prefer working within terminal environments or need to batch-process multiple files.

To use the CLI, first install it via npm:

npm install -g quickmathjs

For more details and documentation, check it out on npm.

After installation, you can immediately use QuickMathJS from the terminal:

npx quickmath path/to/your/file.txt

This will evaluate the entire file and write the results of each calculation back into the file.

Using --sections Feature

If you have files where only specific sections are meant for calculations, you can use the --sections flag. This flag will evaluate only the portions surrounded by the ```calc delimiters:

npx quickmath --sections path/to/your/file.md

For instance, in a document like:

# Kibble Calc
This calcs how much kibble we need to buy

```calc
CatCount = 4
KibblePerCat = 4
TotalKibble = CatCount * KibblePerCat
            = ?
```

The rest of the document can contain text, and only the section within the ```calc delimiters will be evaluated.

Launching Web Interface with --web Feature

If you prefer to use the web interface but have installed QuickMathJS via npm, you can launch the web calculator interface locally:

npx quickmath --web

This will open your default web browser with the QuickMathJS web interface ready to use. Any file specified will be preloaded into the web interface.

npx quickmath --web path/to/your/file.txt

Note: Ensure the --web flag is placed before specifying the file path.

How It Works

For detailed examples, check the full guide here.

Type your expressions. Use = to display results.

For Example:

# Basic Expressions with Direct Calculation
1 + 1 = ?
  = ?

# Variable Assignment with Explicit Value Retrieval
a = 3
a: ?

# Simultaneous Assignment And Results
c = a + 3 = ?

# 2> spaces as alt method for Explicit Value Retrieval
  c = ?

Output:

# Basic Expressions with Direct Calculation
1 + 1 = 2
  = 2

# Variable Assignment with Explicit Value Retrieval
a = 3
a: 3

# Simultaneous Assignment And Results
c = a + 3 = 6

# 2> spaces as alt method for Explicit Value Retrieval
  c = 6

Note 2 spaces and = to indicate we want output result.

Detailed Examples

1. Currency Conversions : QuickMathJS allows for intuitive currency conversions using custom pair ratios. This can also be extended to other types of custom ratios.
2. Unit Conversion and Mathematical Expressions : Leverage the power of Math.js to convert between units seamlessly and evaluate complex expressions.
3. Custom Functions : Users can define custom functions and evaluate them with specific arguments. This allows for a reusable approach to complex calculations.
4. Phrases as Variables : Beyond traditional variable names, QuickMathJS supports using sentences as variable names. Just ensure they don't conflict with reserved keywords in Math.js.
5. Custom Units and Compound Calculations : Define your own custom units and perform arithmetic operations with them, even allowing for compound calculations.

# Custom Pair Ratios (e.g. Currency Conversion and Arithmetic with Defined Exchange Rate)
EUR/USD = 1.2
a = 2 USD
b = 2.4 EUR
c = a + 2 * b = 6 USD
a + b in EUR : 4.8 EUR
total = a + c
total in EUR: 9.6 EUR

# Unit Conversion with Math.js
length = 5.08 cm + 2 inch = 10.16 cm
length in cm to inch = 4 inch

# Evaluating Mathematical Expressions
1.2 / (3.3 + 1.7) = 0.24
sin(90 deg) = 1

# Defining and Evaluating Custom Functions
f(x, y) = x ^ y
f(2, 3) = 8

# Phrase As Variable
Per Person Delivery = 11
People Count = 23
Delivery = 12
Total Food Price = Per Person Delivery * People Count = 253
Total Price = Total Food Price + Delivery = 265
Total Price: 265

# Custom Units
pitbull dogs = 234 fancy animals
flowery cats = 423 fancy animals
animal count = pitbull dogs + flowery cats
animal count: 657 fancy animals
animal count = pitbull dogs * flowery cats
animal count: 98982 fancyanimals^2

Currency Notation Support

This is a list of all the 3 letters ISO 4217 currency unit name that is supported because of it's usage as a national currency representation:

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYN, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SSP, SRD, STD, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPF, YER, ZAR, ZMK, ZMW, ZWL, EUR

Also for each currency an additional secondary representation is provided for the taxed/untaxed notation. So for USD there will also be USD inc tax, USD exc tax, USD inc gst, USD exc gst avaliable for your convenience.

# 10% gst flat tax ratio 
EUR / EUR inc GST = 1/1.1
10.0 EUR in EUR inc GST = 11 EUR inc GST

# Adjust notation to include inc/exc tax notation
(10.0 + 1) EUR to EUR exc tax : 11 EUR exc tax
(10.0 + 2) EUR to EUR inc tax : 12 EUR inc tax
(10.0 + 2) EUR to EUR exc gst : 12 EUR exc gst
(10.0 + 2) EUR to EUR inc gst : 12 EUR inc gst

# Can also convert between extended notation
(10.0 + 2) EUR exc tax to EUR inc tax : 12 EUR inc tax

Using as a Node.js Module

QuickMathJS can also be used as an npm module in your own projects. Here's how:

Installation

npm install quickmathjs

Usage

const mathjs = require('mathjs');
const webcalc = require('./calculator.js')(mathjs);
mathContent = `
a = 5
b = 7
c = a + b = ?
  = ?
1 + 1
    = ?
    c = ?
`
mathContent = webcalc.calculate(mathContent);
console.log(mathContent);

Functions

webcalc.calculate(mathContent: string): string

Calculates mathematical content within a given text and returns the result.

• mathContent (string): The text containing mathematical content.

Returns a string with the mathematical content replaced by their calculated results.

webcalc.calculateWithMathSections(documentContent: string): string

Calculates mathematical content within sections in a given text and replaces them with their calculated results.

• documentContent (string): The text containing a commonmark/markdown content with math marked blockquote sections.

Returns a string with the mathematical content replaced by their calculated results.

Dev Note:

• Why is the backend CI/CD Node.js based and not deno based?

  • I've tried Deno, but it uses 'export' keyword which messes with browser syntax parsing (if module is not enabled). I could try enabling modules, but my aim is for the code to be useable without CORS being triggered... so you could use it offline without having to start a local server for it.

• For developers working on quickmathjs, there is a built-in testing feature that can be triggered using the --test flag. This is primarily for development and CI/CD purposes.

Tips for Developers:

• While developing or making changes, use the npx quickmathjs --test flag to run the predefined test cases and ensure the core functionalities remain intact. This helps in catching any regression bugs early on.

Contributing

Feedback, suggestions, and contributions are always appreciated. Kindly open an issue or submit a pull request.

License

This project is under the GNU General Public License v3.0.