Skip to content

A simple calculator application which works similar to taking notes on a sheet of paper. This is a mirror of the GitLab repository.

License

Notifications You must be signed in to change notification settings

RobertZenz/jMathPaper

Repository files navigation

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.

Single source files might be licensed under a more permissive license, please
see the individual license headers for details

 * com.sibvisions.rad.ui.swing.ext-Package: Apache 2, copied from
   [JVx](https://sourceforge.net/projects/jvx/) (with modifications).


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


Download
--------

There are multiple download options available:

 * Core: Library option, can not be run on its own and only contains the most
   basic classes without any UI implementations.
 * CLI: Only contains the command line and service interface.
 * CLI-TUI: Only contains the command line and service interface and the simple
   text user interface.
 * CLI-TUI2: Only contains the command line and service interface and
   the extended text user interface. This interface has to be considered
   experimental and might not work correctly.
 * GUI: Only contains the GUI interface.
 * Full: The full build, containing all user interfaces including the GUI one.


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 area 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

The special case of `00` will evaluate to the last result.

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 evaluated 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 the list of supported functions.

### 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. 

The following constants are available by default:

    Constant
    --------------------------------------------------------------------
    e
    PI

### Functions

The following functions are available by default:

    Function                   Result
    --------------------------------------------------------------------
    abs(value)                 The absolute value.
    acos(value)                The angle of the cosine (in degrees).
    acosh(value)               The angle of the hyperbolic cosine (in degrees).
    acot(value)                The angle of the cotangents (in degrees).
    asin(value)                The angle of the sine (in degrees).
    asinh(value)               The angle of the hyperbolic sine (in degrees).
    atan(value)                The angle of the tangents (in degrees).
    atanh(value)               The angle of the hyperbolic tangents (in degrees).
    ceiling(value)             Rounded up to the nearest integer.
    cos(value)                 The cosine.
    cosh(value)                The hyperbolic cosine.
    cot(value)                 The cotangents.
    coth(value)                The hyperbolic cotangents.
    csc(value)                 The cosecant (in degrees).
    csch(value)                The hyperbolic cosecant (in degrees).
    deg(value)                 Degrees from radians.
    fact(value)                The factorial value of an integer.
    floor(value)               Rounded down to the nearest integer.
    if(condition, true, false) Tests the conditions and returns the appropriate
                               value.
    log(value)                 The logarithm (base e).
    log10(value)               The logarithm (base10).
    max(values, ...)           The highest value from all.
    min(value, ...)            The lowest value from all.
    not(value)                 Negates the value.
    rad(value)                 Radians from degrees.
    random()                   A random number between 0 and 1.
    round(value, precision)    The rounded value.
    sec(value)                 The secant.
    sech(value)                The hyperbolic secant.
    sin(value)                 The sine.
    sinh(value)                The hyperbolic sine.
    sqrt(value)                The square root.
    tan(value)                 The tangents.
    tanh(value)                The hyperbolic tangents.

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 replaced 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 as meter = 0.9144
    #4                               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 = 5
    b                                       b=10 = 10
    c                  c=a*sqrt(b) meter to inch = 622.4956...

Also combined units are being supported.

    #1                           5km/h to in/sec = 54.6806...
    #2               12 l/sec/m^2 in l/hour/sqin = 27.8709...


There is also an automatic conversion from a unit with a prefix to a unit
without one, if no target unit is specified.

    #1                                       1km = 1000
    #2                                     1km/h = 1000

#### 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 passed 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. GUI, a graphical interface based on Swing.
 4. Service, a UI to use jMathPaper as a service.

By default with no arguments given the GUI 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`
 * `gui`
 * `service`

#### CLI

The CLI accepts a number of UI parameters, they can be provided with
the `--uiparam=NAME:VALUE` parameter.

    Parameter           Description
    --------------------------------------------------------------------
    isNoNewline         Do not output a newline after printing
                        the result.
    
    isPrintResultOnly   Print only the result, not the whole expression.

#### Service

The Service accepts a number of UI parameters, they can be provided with
the `--uiparam=NAME:VALUE` parameter.

    Parameter           Description
    --------------------------------------------------------------------
    isNoNewline         Do not output a newline after printing
                        the result.
    
    isPrintResultOnly   Print only the result, not the whole expression.

#### TUI

The TUI does not support any parameters.

#### TUI2

The TUI2 does not support any parameters.

#### GUI

The Swing UI accepts a number of UI parameters, they can be provided with
the `--uiparam=NAME:VALUE` parameter.

    Parameter           Description
    --------------------------------------------------------------------
    laf                 The fully qualified classname of Look And Feel
                        to use for the UI.
    
    alternateRowColor   The color to use for alternate rows in
                        the table, expected is a hex-string.

### 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 by default. Accepts
                a type and a range.
    
    new         Creates a new paper.                    new, :new
    
    next        Switches to the next paper in           next, right,
                the list, if there is any.              :bnext, :bn
    
    note        Allows to edit the current note.        note
                Accepts the operation and parameters.
    
    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

#### copy

The copy command accepts additional parameters, namely a part and a range. If
no parameters are provided the whole paper will be copied, if parameters are
provided only the set parts of the given lines will be copied.

    copy [part] [range]

The types available are:

    Part        Description                              Aliases
    -----------------------------------------------------------------------
    expression  The expression of the selected lines.    expression, exp
    
    id          The ID of the selected lines.            id
    
    line        The whole lines.                         line
    
    paper       The whole paper.                         paper
    
    result      The result of the selected lines.        result, res

The range can either be nothing (for all), a single ID or index (starting at 1),
a comma separated list of ID's or indexes or a range specified with two dots.

    copy abc
    copy 4
    copy expression #3,abc,#7
    copy result 3..abc

#### note

The note command allows you to manipulate the notes. It accepts additional
parameters, namely the action and the associated parameters.

    note action [index] line

The actions are:

    Action      Description                              Aliases
    -----------------------------------------------------------------------
    add         Adds the given value as separate line    add, append
                to the notes.
    
    clear       Clears the whole note.                   clear, clr, cls,
                                                         reset
    
    delete      Deletes the line with the given 1-based  delete, del,
                index.                                   remove, rem
    
    insert      Inserts the line at the given 1-based    insert, ins
                index.

Some examples.

    note add New line.
    note insert 1 Inserted before the first line.
    note delete 3
    note clear

### 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 every time 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`.


Configuration
-------------

jMathPaper creates a configuration directory in which it places all the user
editable configuration files. The location of the configuration directory is
determined as follows:

 1. The directory specified with the `-c`/`--config-dir` argument.
 2. The directory specified in the `$XGD_DATA_HOME` variable with
    the sub-directory `jmathpaper`.
 3. The user-home directory with the sub-directories `.local/share/jmathpaper`.
 4. The current directory with the sub-directory `jmathpaper`.


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

jMathPaper is a Java 8 application which uses Swing 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.

### 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.
Note that there is the `AbstractPapersUi` which does already implement a great
deal of the functionality required.

About

A simple calculator application which works similar to taking notes on a sheet of paper. This is a mirror of the GitLab repository.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages