path: root/mtx.h

/* $Id$ */

/*
 * Copyright (C) 2005-2006 Richard Braun
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

/**
 * \mainpage mtx 0.1
 *
 * \section intro_sec Introduction
 *
 * Mtx is a small interpreter for a subset of the MATLAB/GNU Octave language
 * specialized for matrix calculus. It can be compiled to use 64 bits words
 * (which improves performance on 64 bits processors), and is able to handle
 * arbitrary length values for every symbol.
 *
 * \section usage_sec Usage
 *
 * There are two ways to use mtx :
 *  - the command line interface (mtx_cli)
 *  - the graphical user interface (mtx_gui)
 * 
 * Both interfaces provide exactly the same engine, so there will be no
 * other difference than the interface itself. Start mtx by typing
 * either ./mtx_cli or ./mtx_gui.
 * 
 * Once your interface is ready, you can enter expressions. The simplest
 * form of expression is the value (either a variable or an immediate value).
 * For example :
 * <pre>
 * mtx_cli> 5
 * ans = 5
 * mtx_cli> ans
 * ans = 5
 * </pre>
 * 
 * An immediate value is considered to be an integer or, if a dot
 * (".") is found, a rational :
 * <pre>
 * mtx_cli> 123
 * ans = 123
 * mtx_cli> 1.23
 * ans = 123/100
 * </pre>
 * 
 * As you can see, <i>ans</i> is an automatic variable which is set when
 * the result of an expression is unnamed.
 * 
 * Assignment is done with the <code>=</code> operator :
 * <pre>
 * mtx_cli> a=123
 * a = 123
 * </pre>
 * 
 * When assigning a value, the left value must be an <i>lvalue</i>, which means
 * it must be a named variable, or refer to it. For example,
 * <code>(a = 1) = 2</code> sets a to 2, because the expression
 * (a = 1) returns a.
 * 
 * \subsection usage_operator Operators
 * 
 * Here is the list of supported operators :
 *  - = : assign the value of the right expression to the lvalue of the left
 *        expression
 *  - +=, -=, *=, /= : execute the operator on the left and right expressions,
 *                     and assign the result to the lvalue of the left
 *                     expression
 *  - + - : (unary operators) return the value of the expression (+) or its
 *          opposite (-).
 *  - + - * / : (binary operators) execute the operator on the right and
 *              left expressions and return the result as a temporary
 *              (unnamed) variable.
 *  - () : force execution of the inner expression before evaluating
 *         the global expression
 *  - f() : use function f
 *  - [] : create a matrix
 *  - , ; : separate expressions (when not used as a separator of function
 *          arguments or matrix elements - ; makes the expressions silent)
 * 
 * \subsection usage_matrices Matrices
 * 
 * A matrix is created using the [] operator. The ; character separates lines
 * whereas the , character separates columns. For example :
 * <pre>
 * mtx_cli> matrix = [1,2,3;4,5,6;7,8,9]
 * matrix = 
 * 
 *    1  2  3
 *    4  5  6
 *    7  8  9
 * 
 * </pre>
 * 
 * \subsection usage_functions Functions
 * 
 * A small set of builtin functions can be used on matrices. These are :
 * 
 * det : compute the determinant of a matrix
 * <pre>
 * mtx_cli> det([1,2;3,4])
 * ans = -2
 * </pre>
 * 
 * inverse : compute the inverse of a matrix
 * <pre>
 * mtx_cli> inverse([1,2;3,4])
 * ans = 
 * 
 *     -2     1
 *    3/2  -1/2
 * 
 * </pre>
 * 
 * transpose : compute the transpose of a matrix
 * <pre>
 * mtx_cli> transpose([1,2;3,4])
 * ans = 
 * 
 *    1  3
 *    2  4
 * 
 * </pre>
 * 
 * augment : compute the augmented matrix of two matrices
 * <pre>
 * mtx_cli> matrix1=[1,2;3,4];matrix2=[5,6;7,8];
 * mtx_cli> augment(matrix1, matrix2)
 * ans = 
 * 
 *    1  2  5  6
 *    3  4  7  8
 * 
 * </pre>
 * 
 * lu : compute the LU decomposition of a matrix
 * <pre>
 * mtx_cli> lu([1,2;3,4], l, u)
 * ans = 1
 * mtx_cli> l,u
 * l = 
 * 
 *    1  0
 *    3  1
 * 
 * u = 
 * 
 *    1   2
 *    0  -2
 * 
 * </pre>
 * 
 * \subsection usage_inputfile Input file
 * 
 * When using the CLI interface, you can use a file which contains expressions
 * on each line :
 * <pre>
 * $ ./mtx_cli test.mtx 
 * mtx 0.1
 * Copyright (C) 2005-2006 Richard Braun.
 * This is free software. You may redistribute copies of it under the terms of
 * the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
 * There is NO WARRANTY, to the extent permitted by law.
 * 
 * mtx_cli> matrix1=[1,2;3,4];matrix2=[5,6;7,8];
 * mtx_cli> augment(matrix1, matrix2)
 * ans = 
 * 
 *    1  2  5  6
 *    3  4  7  8
 * 
 * $
 * </pre>
 * 
 * Have fun using mtx.
 */

/**
 * \file mtx.h
 * \brief Global header.
 * 
 * This header includes API definitions and is used to solve inclusion loops.
 */

#ifndef _MTX_H
#define _MTX_H

#include <stdint.h>

/**
 * \def MTX_VERSION
 * \brief Software version.
 */
#define MTX_VERSION "0.1"

/**
 * \def MTX_NOTICE
 * \brief Software notice.
 */
#define MTX_NOTICE "mtx " MTX_VERSION "\n" \
  "Copyright (C) 2005-2006 Richard Braun.\n" \
  "This is free software. You may redistribute copies of it under the terms of\n" \
  "the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.\n" \
  "There is NO WARRANTY, to the extent permitted by law.\n"

/**
 * \def MTX_DEFAULT_PRECISION
 * \brief Default precision.
 * 
 * Used for decimal floating point representation.
 */
#define MTX_DEFAULT_PRECISION 8

/**
 * \def MTX_MAX_BASE
 * \brief Maximum usable base for conversions.
 */
#define MTX_MAX_BASE 16

/**
 * \def MTX_DEFAULT_BASE
 * \brief Default base.
 */
#define MTX_DEFAULT_BASE 10

/**
 * \def MTX_INT_BITS
 * \brief Number of bits in mtx_int_t words.
 * 
 * If USE_64BITS_WORDS is defined, mtx_int_t words will be 64 bits large,
 * otherwise they'll be 32 bits large.
 */

/**
 * \def MTX_INT_HALF
 * \brief Half of 2^MTX_INT_BITS.
 * 
 * This macro is used to get the most significant bit of mtx_int_t words.
 */

/**
 * \typedef uint64_t mtx_int_t
 * \brief Type definition for words used in MtxInteger.
 */

#ifdef USE_64BITS_WORDS
#define MTX_INT_BITS 64
#define MTX_INT_HALF 0x8000000000000000ull
typedef uint64_t mtx_int_t;
#else
#define MTX_INT_BITS 32
#define MTX_INT_HALF 0x80000000ul
typedef uint32_t mtx_int_t;
#endif /* USE_64BITS_WORDS */

#include <string>
#include <vector>

/*
 * Declare types which cause inclusion loops here.
 */

/**
 * \typedef std::vector<std::string> mtx_expression_t
 * \brief Vector of strings used to store lexical elements.
 */
typedef std::vector<std::string> mtx_expression_t;
class MtxMatrix;
class MtxSymbol;
class MtxLanguage;
class MtxWindow;
class MtxEntry;

#endif /* _MTX_H */