\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename fraccalc.info
@settitle fraccalc Command Manual
@c %**end of header

@c This file has the new style title page commands.
@c Run 'makeinfo' rather than 'texinfo-format-buffer'.

@smallbook

@c tex
@c \overfullrule=0pt
@c end tex

@titlepage
@title @command{fraccalc}
@subtitle an exact precision calculator language
@subtitle version 1.0

@author Mikhail V. Sinitcin
@page

@paragraphindent 3

This manual documents @command{fraccalc}, an exact precision calculator
language. @command{fraccalc} may be considered as the direct descendant of
B.~Kernighan and R.~Pike @command{hoc}.

This manual is part of GNU @command{fraccalc}.
@sp 4
Copyright (C) 2007 Mikhail V. Sinitcin.

@paragraphindent 3

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@iftex

@paragraphindent 3

Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end iftex

@paragraphindent 3

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

@paragraphindent 3

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.

You may contact the author by:
e-mail: @email{sinitcinmv@@rambler.ru}@*

@end titlepage

@node Top, Introduction, (dir), (dir)

@menu
* Introduction::
* Basic Elements::
* Expressions::
* Statements::
* Functions::
* Space in numbers::
* Errors in execution::
@end menu

@node Introduction, Basic Elements, Top, Top
@chapter Introduction
@menu
* Description::
* Command Line Options::
@end menu

@node Description, Command Line Options, Introduction, Introduction
@section Description

@paragraphindent 3

@command{fraccalc} [-h/--help] [-f/--file] [-l/--lib] [-V/--version]

@sp 2

@paragraphindent 3

@command{fraccalc} is a language that supports proper and improper fractions
with interactive execution of statements.  There are some similarities
in the syntax to the C programming language.
@command{fraccalc} starts by processing code from the standard input.
@command{fraccalc} may also read code from the file on the
command line after @command{-f} or @command{-l} option. The option @command{-l} allows to add commands from standard input. The option @command{-f} causes immediate exit 
after executing last command from file. All code is executed as it is read.

The author would like to thank Vladimir Lidovski for guidance and some
advice.

Email bug reports to @email{sinitcinmv@@rambler.ru}.  Be sure to include
the word "fraccalc" somewhere in the "Subject:" field.

@node Command Line Options, Description, , Introduction
@section Command Line Options

@command{fraccalc} takes the following options from the command line:
@table @code

@item -h, --help
Print the usage and exit.

@item -l, --lib
Obtain commands from file.

@item -f, --file
Obtain commands from file end exit.

@item -V, --version
Print the version number.

@end table


@node Basic Elements, Expressions, Introduction, Top
@chapter Basic Elements
@menu
* Fractions::
* Variables::
* Comments::
@end menu

@node Fractions, , Variables, Basic Elements
@section Fractions

@paragraphindent 3

The basic element in @command{fraccalc} is the fraction.
The fractions may be proper, improper, and decimal.
All numbers are represented internally in the fraction form and all
computations are done with fractions. The integer part of a number must
be separated from fractional part by floating point sign. The numerator and
the denominator are separated by spacing underscore or low line sign.

@node Variables, Fractions, Comments, Basic Elements
@section Variables

@paragraphindent 3

Numbers are stored in variables. Names begin with a letter followed by any
number of letters, digits and underscores.

@node Comments, Variables, , Basic Elements
@section Comments

Comments in @command{fraccalc} start with the characters @code{#} and end with
the end of line marker. The end of line
character is not part of the comment and is processed normally.

@node Expressions, Statements, Basic Elements, Top
@chapter Expressions

@menu
* About Expressions and Special Variables::
* Basic Expressions::
* Relational Expressions::
* Boolean Expressions::
* Precedence::
* Special Expressions::
@end menu

@node About Expressions and Special Variables, Basic Expressions, Expressions, Expressions
@section About Expressions and Special Variables

@paragraphindent 3

The numbers are manipulated by expressions and statements.  Since the 
language was designed to be interactive, statements and expressions are 
executed as soon as possible.  There is no main program.  Instead, code 
is executed as it is encountered.  (Functions, discussed in detail later, 
are defined when encountered.)

A simple expression is just a constant. @command{fraccalc} converts 
constants into fractions. Input numbers may contain the 
characters 0-9, "." and "_".

Full expressions are similar to many other high level languages. Since
there is only one kind of number, there are no rules for mixing types.

@node Basic Expressions, Relational Expressions, About Expressions and Special Variables, Expressions
@section Basic Expressions

@paragraphindent 3

In the following descriptions of legal expressions, "expr" refers to a
complete expression and "@var{var}" refers to a simple variable.
A simple variable is just a 

@var{name}

@table @code
@item - expr
The result is the negation of the expression.

@item ++ @var{var}
The variable is incremented by one and the new value is the result of
the expression.

@item -- @var{var}
The variable
is decremented by one and the new value is the result of the
expression.

@item @var{var} ++
 The result of the expression is the value of
the variable and then the variable is incremented by one.

@item @var{var} --
The result of the expression is the value of the variable and then
the variable is decremented by one.

@item expr + expr
The result of the expression is the sum of the two expressions.

@item expr - expr
The result of the expression is the difference of the two expressions.

@item expr * expr
The result of the expression is the product of the two expressions.

@item expr / expr
The result of the expression is the quotient of the two expressions.

@item expr ^ expr
The result of the expression is the value of the first raised to the
second. The second expression must be an integer. (If the second
expression is not an integer, the expression is truncated to get an integer value.) 
It should be noted that expr^0 will always return the value of 1.

@item ( expr )
This alters the standard precedence to force the evaluation of the
expression.

@item @var{var} = expr
The variable is assigned the value of the expression.
@end table

@node Relational Expressions, Boolean Expressions, Basic Expressions, Expressions
@section Relational Expressions

Relational expressions are a special kind of expression that always
evaluate to 0 or 1, 0 if the relation is false and 1 if the relation is
true.  These may appear in any legal expression. The relational operators 
are

@table @code
@item expr1 < expr2
The result is 1 if expr1 is strictly less than expr2.

@item expr1 <= expr2
The result is 1 if expr1 is less than or equal to expr2.

@item expr1 > expr2
The result is 1 if expr1 is strictly greater than expr2.

@item expr1 >= expr2
The result is 1 if expr1 is greater than or equal to expr2.

@item expr1 == expr2
The result is 1 if expr1 is equal to expr2.

@item expr1 != expr2
The result is 1 if expr1 is not equal to expr2.
@end table

@node Boolean Expressions, Precedence, Relational Expressions, Expressions
@section Boolean Expressions

Boolean operations are also legal. The result of all boolean operations 
are 0 and 1 (for false and true) as in relational expressions.  The 
boolean operators are:

@table @code
@item !expr
The result is 1 if expr is 0.

@item expr && expr
The result is 1 if both expressions are non-zero.

@item expr || expr
The result is 1 if either expression is non-zero.
@end table

@node Precedence, Special Expressions, Boolean Expressions, Expressions
@section Precedence

The expression precedence is as follows: (lowest to highest)

@example
|| operator, left associative
&& operator, left associative
! operator, nonassociative
Assignment operator, right associative 
Relational operators, left associative
+ and - operators, left associative
* and / operators, left associative
^ operator, right associative
unary - operator, nonassociative
++ and -- operators, nonassociative
@end example

So @command{fraccalc} uses the same expression precedence as in C programming language.
Consider the expression:

@example
a = 3 < 5
@end example

This would assign the result of "3 < 5" (the value 1) to the variable "a". 

@node Special Expressions, , Precedence, Expressions
@section Special Expressions

There are a few more special expressions that are provided in
@command{fraccalc}.  These have to do with user-defined functions and standard
functions.  They all appear as
"@var{name}@code{(}@var{parameters}@code{)}".  @xref{Functions}, for
user-defined functions.  The standard functions are:

@table @code
@item integer ( expression )
The value of the integer part of a number.

@item numerator ( expression )
The value of the numerator of a fraction.

@item denominator ( expression )
The value of the denomiminator of a fraction.
@end table

@node Statements, Functions, Expressions, Top
@chapter Statements

@menu
* Pseudo Statements::
@end menu

Statements (as in most algebraic languages) provide the sequencing of
expression evaluation.  In @command{fraccalc} statements are executed "as soon
as possible."  Execution happens when a newline in encountered and there
is one or more complete statements.  Due to this immediate execution,
newlines are very important in @command{fraccalc}. In fact, both a semicolon
and a newline are used as statement separators.  An improperly placed
newline will cause a syntax error.  A statement list is a series of 
statements separated by semicolons and newlines.

@table @var
@item expression
The expression is evaluated and printed to the output.  After the number is
printed, a newline is printed. The expression terminated by semicolon 
is not printed to the output. 

@item @code{if} ( expression ) statement1 [@code{else} statement2]
The if statement evaluates the expression and executes statement1 or
statement2 depending on the value of the expression.  If the expression
is non-zero, statement1 is executed.  If statement2 is present and
the value of the expression is 0, then statement2 is executed.  

@item @code{while} ( expression ) statement
The while statement will execute the statement while the expression
is non-zero.  It evaluates the expression before each execution of
the statement.   Termination of the loop is caused by a zero
expression value or the execution of a @code{break} statement.

@item @code{for} ( [expression1] ; [expression2] ; [expression3] ) statement
The @code{for} statement controls repeated execution of the statement.
@var{Expression1} is evaluated before the loop.  @var{Expression2} is
evaluated before each execution of the statement.  If it is non-zero,
the statement is evaluated.  If it is zero, the loop is terminated.
After each execution of the statement, @var{expression3} is evaluated
before the reevaluation of expression2.  If @var{expression1} or
@var{expression3} are missing, nothing is evaluated at the point they
would be evaluated.  If @var{expression2} is missing, it is the same as
substituting the value 1 for @var{expression2}.  The following is equivalent 
code for the @code{for} statement:

@example
expression1;
while (expression2) @{
   statement;
   expression3;
@}
@end example

@item @code{break}
This statement causes a forced exit of the most recent enclosing @code{while}
statement or @code{for} statement.

@item @code{return} expression 
Return the value of the expression from a function.  (@xref{Functions}.)


@item @code{include} filename 
Obtain commands from file with filename.

@item exit
When the @code{exit} statement is read, the @command{fraccalc} processor
is terminated. 

@end table

@node Pseudo Statements, , Statements, Statements
@section Pseudo Statements

These statements are not statements in the traditional sense.  They are
not executed statements.  Their function is performed at "compile" time.

@table @code
@item proper
Set default proper fraction format for output. This mode is set initially. 

@item improper
Set default improper fraction format for output.

@end table

@node Functions, Statements, Space in numbers, Top
@chapter Functions

Functions provide a method of defining a computation that can be
executed later.  Functions in @command{fraccalc} always compute a value and
return it to the caller.  Function definitions are "dynamic" in the
sense that a function is undefined until a definition is encountered in
the input.  That definition is then used until another definition
function for the same name is encountered.  The new definition then
replaces the older definition.  A function is defined as follows:

@example
@var{name} @code{(} @var{parameters} @code{)} @code{@{} @var{newline}
    @var{statement_list} @code{@}}
@end example

A function call is just an expression of the form
"@code{name} @code{(}@var{parameters}@code{)}".

Parameters are numbers.  In the function definition,
zero or more parameters are defined by listing their names separated by
commas.  Numbers are only call by value parameters. It is possible to miss 
some parameters values at function call --- these missed parameters are 
set to 0. These missed parameters may be used as local variables inside function body only.

The function body is a list of @command{fraccalc} statements.  Again, statements
are separated by semicolons or newlines.  Return statements cause the
termination of a function and the return of a value.  There are two
versions of the return statement.  The first form, "@code{return}", returns
the value 0 to the calling expression.  The second form, 
"@code{return} @var{expression}", computes the value of the expression
and returns that value to the calling expression.  There is an implied
"@code{return} 0" at the end of every function.  This allows a function
to terminate and return 0 without an explicit @code{return} statement.

At the description of function the opening brace be on the same line and 
all other parts must be on following lines.

@example
   d (n) @{ return (2*n); @}
   d (n) @{ 
		return (2*n); 
	@}
@end example

The following is the definition of the recursive factorial function.

@example

fact (x) @{
  if (x <= 1) return 1;
  return f(x-1) * x;
@}

@end example

@node Space in numbers, Functions, Errors in execution, Top
@chapter Space in numbers

Some implementations of @command{bc} allow spaces in numbers.  For example,
"x=1 3" would assign the value 13 to the variable x.  The same statement
would cause a syntax error in this version of @command{fraccalc}.


@node Errors in execution, Space in numbers, , Top
@chapter Errors in execution

If a syntax error in expression is found then the processor 
skips this expression. 

@contents
@bye