Mini-Language

Fityk comes with own domain-specific language (DSL), which is humbly called mini-language. All operations are driven by commands of the mini-language.

Do not worry

you do not need to learn the syntax of the mini-language. It is possible to use menus and dialogs in the GUI and avoid typing commands.

When you use the GUI and perform an action using the menu, you can see the corresponding command in the output window. It is one of less than 30 fityk commands. The commands have relatively simple syntax and perform single actions, such as loading data from file, adding function, assigning variable, fitting, or writing some values to a file.

It is possible to write a script (macro) as a sequence of such commands. This can automate common tasks, although some complex tasks still need to be programmed in a general-purpose language. That is why Fityk comes with embedded Lua (lightweight programming language) and also with bindings to Python and several other languages.

Now a quick glimpse at the syntax. Here, the =-> prompt marks an input:

=-> print pi
3.14159
=-> # this is a comment -- from `#' to the end of line
=-> p '2+3=', 2+3 # p stands for print
2+3 = 5
=-> set numeric_format='%.9f' # show 9 digits after dot
=-> pr pi, pi^2, pi^3 # pr, pri and prin also stand for print
3.141592654 9.869604401 31.006276680

Usually, one line is one command, but if it is really needed, two or more commands can be put in one line like this:

=-> $a = 3; $b = 5 # two commands separated with `;'

If the user works simultaneously with multiple datasets, she can refer to a dataset using its number: the first dataset is @0, the second – @1, etc:

=-> fit # perform fitting of the default dataset (the first one)
=-> @2: fit # fit the third dataset (@2)
=-> @*: fit # fit all datasets, one by one

All settings in the program are changed using the command set:

set key = value

For example:

=-> set logfile = 'C:\log.fit' # log all commands to this file
=-> set verbosity = 1 # make output from the program more verbose
=-> set epsilon = 1e-14

The last example changes the ε value, which is used to test floating-point numbers a and b for equality (it is well known that due to rounding errors the equality test for two numbers should have some tolerance, and the tolerance should be tailored to the application): |a−b| < ε.

To change a setting only for one command, add with key=value before the command:

=-> with epsilon = 0.1 print pi == 3.14 # abusing epsilon
1
=-> print pi == 3.14 # default epsilon = 10^-12
0

Writing informally, each line has a syntax:

[[@...:] [with ...] command [";" command]...] [#comment]

In scripts and in the CLI backslash () at the end of the line means that the next line is continuation.

All the commands are described in the next chapters.

Important

The rest of this section can be useful as reference, but it is recommended to skip it when reading the manual for the first time.

To keep the description above concise, some details were skipped.

The datasets listed before the colon (:) make a foreach loop:

=-> $a=0
=-> @0 @0 @0: $a={$a+1}; print $a
1
2
3

@* stands for all datasets, from @0 to the last one.

There is a small difference between two commands in two lines and two commands separated by ;. The whole line is parsed before the execution begins and some checks for the second command are performed before the first command is run:

=-> $a=4; print $a # print gives unexpected error
Error: undefined variable: $a

=-> $b=2
=-> $b=4; print $b # $b is already defined at the check time
4

Grammar

The grammar is expressed in EBNF-like notation:

  • (*this is a comment*)
  • A* means 0 or more occurrences of A.
  • A+ means 1 or more occurrences of A.
  • A % B means A (B A)* and the % operator has the highest precedence. For example: term % "+" comment is the same as term ("+" term)* comment.
  • The colon : in quoted string means that the string can be shortened, e.g. "del:ete" means that any of del, dele, delet and delete can be used.

The functions that can be used in p_expr and v_expr are available here and here, respectively. v_expr contains only a subset of functions from p_expr (partly, because we need to calculate symbolical derivatives of v_expr)

Line structure

line      ::=  [statement] [comment]
statement ::=  [Dataset+ ":"] [with_opts] command % ";"
with_opts ::=  "w:ith" (Lname "=" value) % ","
comment   ::=  "#" AllChars*

Commands

The kCmd* names in the comments correspond to constants in the code.

command ::=  (
             "deb:ug" RestOfLine              | (*kCmdDebug*)
             "def:ine" define                 | (*kCmdDefine*)
             "del:ete" delete                 | (*kCmdDelete*)
             "del:ete" delete_points          | (*kCmdDeleteP*)
             "e:xecute" exec                  | (*kCmdExec*)
             "f:it" fit                       | (*kCmdFit*)
             "g:uess" guess                   | (*kCmdGuess*)
             "i:nfo" info_arg % "," [redir]   | (*kCmdInfo*)
             "l:ua" RestOfLine                | (*kCmdLua*)
             "=" RestOfLine                   | (*kCmdLua*)
             "pl:ot" [range] [range] Dataset* [redir] | (*kCmdPlot*)
             "p:rint" print_args [redir]      | (*kCmdPrint*)
             "quit"                           | (*kCmdQuit*)
             "reset"                          | (*kCmdReset*)
             "s:et" (Lname "=" value) % ","   | (*kCmdSet*)
             "sleep" expr                     | (*kCmdSleep*)
             "title" "=" filename             | (*kCmdTitle*)
             "undef:ine" Uname % ","          | (*kCmdUndef*)
             "use" Dataset                    | (*kCmdUse*)
             "!" RestOfLine                   | (*kCmdShell*)
             Dataset "<" load_arg             | (*kCmdLoad*)
             Dataset "=" dataset_expr         | (*kCmdDatasetTr*)
             Funcname "=" func_rhs            | (*kCmdNameFunc*)
             param_lhs "=" v_expr             | (*kCmdAssignParam*)
             Varname "=" v_expr               | (*kCmdNameVar*)
             Varname "=" "copy" "(" var_id ")" | (*kCmdNameVar*)
             model_id ("="|"+=") model_rhs    | (*kCmdChangeModel*)
             (p_attr "[" expr "]" "=" p_expr) % "," | (*kCmdPointTr*)
             (p_attr "=" p_expr) % ","        | (*kCmdAllPointsTr*)
             "M" "=" expr                     ) (*kCmdResizeP*)

Other rules

define         ::=  Uname "(" (Lname [ "=" v_expr]) % "," ")" "="
                       ( v_expr |
                         component_func % "+" |
                         "x" "<" v_expr "?" component_func ":" component_func
                       )
component_func ::=  Uname "(" v_expr % "," ")"
delete         ::=  (Varname | func_id | Dataset | "file" filename) % ","
delete_points  ::=  "(" p_expr ")"
exec           ::=  filename |
                    "!" RestOfLine |
                    "=" RestOfLine
fit            ::=  [Number] [Dataset*] |
                    "undo" |
                    "redo" |
                    "history" Number |
                    "clear_history"
guess          ::=  [Funcname "="] Uname ["(" (Lname "=" v_expr) % "," ")"] [range]
info_arg       ::=  ...TODO
print_args     ::=  [("all" | ("if" p_expr ":")]
                    (p_expr | QuotedString | "title" | "filename") % ","
redir          ::=  (">"|">>") filename
value          ::=  (Lname | QuotedString | expr) (*value type depends on the option*)
model_rhs      ::=  "0" |
                    func_id |
                    func_rhs |
                    model_id |
                    "copy" "(" model_id ")"
func_rhs       ::=  Uname "(" ([Lname "="] v_expr) % "," ")" |
                    "copy" "(" func_id ")"
load_arg       ::=  filename Lname* |
                    "."
p_attr         ::=  ("X" | "Y" | "S" | "A")
model_id       ::=  [Dataset "."] ("F"|"Z")
func_id        ::=  Funcname |
                    model_id "[" Number "]"
param_lhs      ::=  Funcname "." Lname |
                    model_id "[" (Number | "*") "]" "." Lname
var_id         ::=  Varname |
                    func_id "." Lname
range          ::=  "[" [expr] ":" [expr] "]"
filename       ::=  QuotedString | NonblankString

Mathematical expressions

expr        ::=  expr_or ? expr_or : expr_or
expr_or     ::=  expr_and % "or"
expr_and    ::=  expr_not % "and"
expr_not    ::=  "not" expr_not | comparison
comparison  ::=  arith % ("<"|">"|"=="|">="|"<="|"!=")
arith       ::=  term % ("+"|"-")
term        ::=  factor % ("*"|"/")
factor      ::=  ('+'|'-') factor | power
power       ::=  atom ['**' factor]
atom        ::=  Number | "true" | "false" | "pi" |
                 math_func | braced_expr | ?others?
math_func   ::=  "sqrt" "(" expr ")" |
                 "gamma" "(" expr ")" |
                  ...
braced_expr ::=  "{" [Dataset+ ":"] p_expr "}"

The atom rule also accepts some fityk expressions, such as $variable, %function.parameter, %function(expr), etc.

p_expr and v_expr are similar to expr, but they use additional variables in the atom rule.

p_expr recognizes n, M, x, y, s, a, X, Y, S and A. All of them but n and M can be indexed (e.g. x[4]). Example: (x+x[n-1])/2.

v_expr uses all unknown names (Lname) as variables (example: a+b*x^2). Only a subset of functions (math_func) from expr is supported. The tilde (~) can be used to create simple-variables (~5), optionally with a domain in square brackets (~5[1:6]).

Since v_expr is used to define variables and user-defined functions, the program calculates symbolically derivatives of v_expr. That is why not all the function from expr are supported (they may be added in the future).

dataset_expr supports very limited set of operators and a few functions that take Dataset token as argument (example: @0 - shirley_bg(@0)).

Lexer

Below, some of the tokens produced by the fityk lexer are defined.

The lexer is context-dependend: NonblankString and RestOfLine are produced only when they are expected in the grammar.

Uname is used only for function types (Gaussian) and pseudo-parameters (%f.Area).

Dataset        ::=  "@"(Digit+|"+"|"*")
Varname        ::=  "$" Lname
Funcname       ::=  "%" Lname
QuotedString   ::=  "'" (AllChars - "'")* "'"
Lname          ::=  (LowerCase | "_") (LowerCase | Digit | "_")*
Uname          ::=  UpperCase AlphaNum+
Number         ::=  ?number read by strtod()?
NonblankString ::=  (AllChars - (WhiteSpace | ";" | "#" ))*
RestOfLine     ::=  AllChars*