-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
668 lines (476 loc) · 24 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
jMathPaper
==========
A simple and easy to use calculation application, which works similar to taking
notes on a sheet of paper.
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.