A simple calculator application which works similar to taking notes on a sheet of paper. This is a mirror of the GitLab repository.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.settings
examples
libs
screenshots
src/org/bonsaimind/jmathpaper
test/org/bonsaimind/jmathpaper/core
.classpath
.gitignore
.project
CHANGES
CONTRIBUTE
CREDITS
LICENSE
MANIFEST.MF
README
build.xml
code-formatter.xml
jMathPaper.launch

README

jMathPaper
==========

A simple and easy to use calculation application, which works similar to taking
notes on a sheet of paper.

![A screenshot of the main view.](./screenshots/01-main-view.png)


License
-------

jMathPaper is licensed under LGPLv3.


Dependencies
------------

Please see the attached license files for details.

 * [EvalEx](https://github.com/uklimaschewski/EvalEx/), BSD-like
 * [jline3](https://github.com/jline/jline3), BSD-like
 * [Lanterna](https://github.com/mabe02/lanterna), LGPLv3
 * [picocli](https://github.com/remkop/picocli), Apache 2.0
 * [SWT](https://www.eclipse.org/swt/), Eclipse Public License 1.0


Usage
-----

### Basics

When you start jMathPaper you are greeted with a (currently empty) list of
previous expressions and the input box to enter a new one. You can enter any
expression you want to evaluate. Additionally, there is a larger input are to
the right which allows you to take notes.

You can save and load papers from the menu, they are stored in a very simple
cleartext format, so it is easy to create and edit them without jMathPaper.
Examples can be found in the examples directory.

Let us start with something simple and enter a few simple expressions:

    ID                               Expression Result
    --------------------------------------------------
    #1                                       1+1 =   2
    #2                                       5*5 =  25
    #3                                    239-38 = 201

One of the big features of jMathPaper is that you can easily reference
a previous result by using its ID, like this:

    #1                                       1+1 =   2
    #2                                       5*5 =  25
    #3                                    239-38 = 201
    #4                                     #2*25 = 625

We can also define variables which we can reference:

    #1                                       1+1 =   2
    #2                                       5*5 =  25
    #3                                    239-38 = 201
    #4                                     #2*25 = 625
    length                             length=10 =  10
    width                                width=5 =   5
    area                       area=length*width =  50

Now if we made a mistake, for example the width really is 7, we can simply press
up and down to scroll through the history and execute the corrected expression
again. The previously executed expressions do not change, so we need to evaluate
them again:

    #1                                       1+1 =   2
    #2                                       5*5 =  25
    #3                                    239-38 = 201
    #4                                     #2*25 = 625
    length                             length=10 =  10
    width                                width=5 =   5
    area                       area=length*width =  50
    width                                width=7 =   7
    area                       area=length*width =  70

We can also use mathematical functions, like `sin`:

    #1                                   sin(70) = 0.9396926

See the documentation of [EvalEx](https://github.com/uklimaschewski/EvalEx/blob/master/README.md)
to see what functions are supported.

### Variables

jMathPaper allows to store results in variables by prefixing the expression with
the name of the variable and an equals sign:

    width                                width=5 =   5

The variable names must begin with either a lower- or uppercase letter or
an underscore, and can contain any letter, underscores or numbers. 

### Functions

Functions can also be defined on the fly:

    add                      add(x, y, z)=x+y+z = true
    #1                             add(1, 2, 3) =    6
    value                             value()=5 =    6
    add              add(x, y, z)=x+y+z+value() = true
    #2                             add(1, 2, 3) =   11

### Different base

We can also enter numbers in hex, octal or binary:

    hex                                 hex=0xff = 255
    octal                             octal=0o77 =  63
    binary                           binary=0b11 =   3

### Comments

If there is need to comment lines or parts of equations C style comments can be
used:

    #10       // We can also comment whole lines. =   0
    #11           1+1 // Or lines with equations. =   2
    #12    1 + /* Or inlined commenting. */ 1 + 1 =   3

### Booleans

Support for booleans is built right in, internally true and false are treated
as zero and one.

    comparison                   comparison= 1==1 = true
    boolean      boolean= (true || false) && true = true

The following operations are supported:

    Operation    Description                          Aliases
    --------------------------------------------------------------------
    ==           equals                               equal, equals
    !=           not equals                           notequal, notequals
    >            greater                              greater
    >=           greater equals                       greaterequal,
                                                      greaterequals
    <            less                                 less
    <=           less equals                          lessequal, lessequals
    &&           and                                  and
    ||           or                                   or

These aliases should be treated as reserved words, but are only replace when
surrounded by spaces, example:

    aliases                  aliases= true and false = false
    aliases                   aliases= true or false =  true

### Unit conversions

There is support for converting units, out-of-the-box the most basic units being
possible to be converted. The conversion works by specifying a value and
the units to convert from and to. The following ways to write the conversion is
acceptable.

    #1                            3feet to meter = 0.9144
    #2                            3feet in meter = 0.9144
    #3                               3feet meter = 0.9144

Units can either be specified by name or by alias (for example `meter` and `m`).
Additionally, they can also be specified in plural (`meters`).

By default, SI and IEC prefixes are supported.

    #1                              3km to meter = 3000
    #2                             20yards to km = 0.018288
    #3                          2decimeter to in = 7.874015...

Not just plain values but whole expressions are supported.

    a                                          a = 5
    b                                          b = 10
    c                  c=a*sqrt(b) meter to inch = 622.4956...

#### Custom units files

Additional units can be specified in a file and passed to jMathPaper with the
`--units=UNITSFILE` parameter or in the user configuration file located in
the jMathPaper configuration directory (most likely
`~/.local/share/jmathpaper/`).

A well-formed units file has one unit per line, looking like this:

    <unitname> <exponent> [<alias,alias,alias,...>]

Or with values:

    foot 1 feet,ft
    meter 1 m

The name is required and considered case-insensitive.

The exponent is required and can be any positive value.

The aliases are an optional, comma separated list which are considered
case-sensitive.

Comments can be specified with a leading `#` character.

#### Custom prefixes files

Additional prefixes can be specified in a file and passd to jMathPaper with the
`--prefixes=PREFIXESFILE` parameter or in the user configuration file located in
the jMathPaper configuration directory (most likely
`~/.local/share/jmathpaper/`).

A well-formed prefixes file has one prefix per line, looking like this:

    <prefixname> <prefix> <base> <exponent>

Or with values:

    kilo k 10 3
    centi c 10 -2

The name is required and considered case-insensitive.

The prefix is required and considered case-sensitive.

The base and exponent are both required and form the factor for this prefix.

Comments can be specified with a leading `#` character.

#### Custom conversions files

Additional conversions can be specified in a file and passed to jMathPaper with
the `--conversions=CONVERSIONSFILE` parameter or in the user configuration file
located in the jMathPaper configuration directory (most likely
`~/.local/share/jmathpaper/`).

A well-formed conversions file has one conversion per line, looking like this:

    <targetunit> <value><sourceunit>

Or with values:

    foot 30cm
    byte 8bit
    torr 101325/760Pa
    some (x + 6)other
    other (x - 6)some

The target unit is the unit to which is converted.

The value can either be a fixed factor (read: a decimal number), a mathematical
expression which evaluates to a fixed factor or a mathematical expression in
parentheses, with `x` denoting the source value. If a mathematical expression
which does not evaluate to a fixed factor is specified, the reverse conversion
must also be added.

Comments can be specified with a leading `#` character.

### Different UIs

jMathPaper supports three main modes of operations:

 1. CLI, only processing arguments given.
 2. TUI, a simple text interface.
 3. SWT, a GUI based on SWT.
 4. Service, a UI to use jMathPaper as a service.

By default with no arguments given the SWT UI is started, if an expression is
given the CLI UI will be used instead.

One can also force one UI to use by specifying `-t` as argument and one of
the following values:

 * `cli`
 * `tui`
 * `swt`
 * `service`

### Commands

There are also commands which can be used to control the application, they can
be entered instead of expressions:

    Command     Description                            Aliases
    --------------------------------------------------------------------
    add         Adds an unit, prefix or conversion on   add
                the fly to the current paper. The added
                item will not be saved in any way and
                will only be usable in the current
                paper.
                The first parameter must either be
                "unit", "prefix" or "conversion"
                followed by a valid definition.
    
    alias       Adds an alias on the fly to the current alias
                paper, the added alias will not be
                saved. A valid alias string is expected
                as parameter.
    
    clean       Cleans the current paper, removing      clean, clear
                all expressions from it.
    
    close       Closes the current paper.               close, :bdelete,
                                                        :bd
    
    copy        Copies the current paper to             copy, cp, y
                the clipboard.
    new         Creates a new paper.                    new, :new
    
    next        Switches to the next paper in           next, right,
                the list, if there is any.              :bnext, :bn
    
    open        Opens a paper from the given path.      open, :e
                The path to open the files is expected
                as parameter to this command. If
                multiple parameters are provided, all
                are opened.
    
    option      Set the given option with the given     option, opt, set,
                value. See the Options section for      setoption, setopt,
                further information.                    :so, :setopt
    
    previous    Switches to the previous paper in       previous, left,
                the list, if there is any.              :bprevious, :bp
    
    quit        Quits the application.                  quit, exit, :q,
                                                        :q!
    
    reload      Reloads the current paper, effectively  reload, reset
                undoing all changes.
    
    save        Saves the current paper, the location   save, store, :w
                can be given as parameter. If multiple
                parameters are provided, it is saved to
                all provided locations.
    
    save/quit   Saves the current paper and quits,      :x
                the location can be given as parameter.
                If multiple parameters are provided, it
                is saved to all provided locations.

Parameters are to be provided space separated and can be quoted, some examples:

    open /home/user/dir/somefile.jmathpaper
    open "./relative path with spaces/file.jmathpaper"
    open ./relative\ path\ with\ spaces/file.jmathpaper
    open a.jmathpaper b.jmathpaper c.jmathpaper

### Options

There are various options available to change how jMathPaper behaves, they can
be set either through the GUI (if available) or with the `option` command.

    option OPTION VALUE

Will set `OPTION` to `VALUE`. The following options are available:

    Option        Description                             Aliases
    -----------------------------------------------------------------------
    numberformat  The format in which the results         numberformat,
                  should be displayed. The following      number-format,
                  symbols are supported:                  format, fmt
                   * 0 - Display either a number or
                         zero.
                   * # - Display either a number or
                         nothing.
                   * . - The decimal separator.
                   * , - The thousands separator.
                   * ? - Display as many decimal places
                         as there are.
                  Here are some examples of valid format
                  strings:
                   * 0.?    - Display the numbers with as
                              many decimal places as needed.
                   * 0.###  - Display the number with
                              three decimal places, if
                              they are not zero.
                   * 0.000  - Display the number with
                              three decimal places.
                   * ,##0.? - Display a thousands separator
                              with as many decimals as
                              needed.
    precision     The precision of the calculations.      precision, prec,
                  The value is expected to be a number,   decimals, dec
                  with 0 meaning "endless". Negatives
                  are not allowed.
    
    rounding      The rounding method that is used.       rounding,
                  Allowed values are:                     rounding-mode
                   * ceiling
                   * down
                   * floor
                   * half-down
                   * half-even
                   * half-up
                   * unnecessary
                   * up

Options only apply to the current paper.

### Chaining

Expressions and commands can be chained by using a semicolon (`;`). So
the following input:

    1+1;2+3;5+5;a=5;a+5

Turns into this:

    #1                                         1+1 =  2
    #2                                         2+3 =  5
    #3                                         5+5 = 10
    a                                          a=5 =  5
    #4                                         a+5 = 10

Of course one can also chain commands and expressions.

### Service

With the Service UI, jMathPaper can be used as a "service" to answer requests.
The Service UI will read expressions from stdin and will output the expression
or result to stdout. This allows to start jMathPaper once and keep it running
while being used from external applications, mitigating the cost of starting of
starting a JVM everytime an expression should be evaluated.

Here is an example script which starts jMathPaper as service:

    #usr/bin/env sh
    
    jmathpaper="jmathpaper.jar"
    input="/tmp/mathpipe-input"
    output="/tmp/mathpipe-output"
    
    mkfifo "$input"
    mkfifo "$output"
    
    tail -f "$input" \
        | java -jar $jmathpaper --ui=service > "$output"
    
    rm "$input"
    rm "$output"

Now a process could write into `/tmp/mathpipe-input` and retrieve the result
from `/tmp/mathpipe-output`.


Technical information
---------------------

jMathPaper is a Java 8 application which uses SWT and EvalEx.

The save format is a simple plain text format, with UTF-8 as encoding and UNIX
line endings. Everything from the start of the file to the first empty line is
treated as expression, everything below the first empty line is treated as note.

### Jars

There are multiple jars available for download:

 * CLI, only containing the command line and service interface.
 * CLI-TUI, only containing the command line and service interface and the
   simple text user interface.
 * Full, the full builds, containing all user interfaces. As SWT uses native
   components, these must be built for every platform.

### Custom UIs

Custom UIs can be implemented by implementing the `Ui` interface and can be
launched afterwards by specifying `--ui=UI` parameter with the full class name.