/* $Id$ */

/*
 * Copyright (C) 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
 */

#ifndef _MTXSYMBOL_H
#define _MTXSYMBOL_H

#include <string>
#include <vector>

#include "mtx.h"
#include "mtxvalue.h"
#include "mtxlanguage.h"

/**
 * A structure representing a special name.
 * 
 * Special names are e.g. "about" or "exit". They have a special meaning
 * and are associated to a function. They should never be used as variable
 * names or normal function names.
 */
struct mtx_special_name
{
  /**
   * The special name.
   */
  const char *name;

  /**
   * Pointer to a function implementing the action associated to the special
   * name.
   */
  std::string (*function)(const MtxSymbol *);
};

/**
 * A symbol.
 * 
 * Symbols are named or temporary values in the language engine.
 * E.g. in the expression "a + 2", both \a a and \a 2 are symbols.
 */
class MtxSymbol
{
  private:
    /**
     * Name of the symbol. An unnamed symbol is considered temporary.
     */
    std::string name;

    /**
     * The value associated to the symbol.
     */
    MtxValue *value;

    /**
     * If true, the symbol is special. I.e. it is created from a special name.
     * When a special symbol is returned by the engine, the engine user should
     * not display the "name = " string that usually prefixes the string
     * representation of the value, so that the output of the commands
     * associated to special names is unaltered when displayed.
     * 
     * @see setSpecial()
     * @see isSpecial()
     */
    bool special;

    /**
     * Set the special member according to the name of the symbol.
     * 
     * @see special
     * @see isSpecial()
     */
    void setSpecial();

    /**
     * Return the index of the struct special_name entry which name matches
     * the symbol name. The special member must be true, or this method will
     * raise an MtxException exception.
     */
    size_t getSpecial() const;

    /**
     * List of special names and function pointers associated to them.
     */
    static struct mtx_special_name special_names[];

  protected:
    /**
     * Address of the MtxLanguage object used to retreive global symbols.
     * 
     * The copy constructor and operator = must not duplicate the content
     * of this pointer.
     */
    MtxLanguage *language;

  public:
    /**
     * Default constructor.
     * 
     * A symbol created with this constructor is unusable, as it doesn't
     * have any link to an MtxLanguage object. The language object is needed
     * to get and set named symbols from the global variable namespace of the
     * language engine.
     */
    MtxSymbol();

    /**
     * Create a named variable.
     * 
     * The value doesn't always need to be stored in the object itself, as
     * it will be retreived from the MtxLanguage object.
     */
    MtxSymbol(MtxLanguage *language, const std::string &name);

    /**
     * Create a temporary object.
     */
    MtxSymbol(MtxLanguage *language, const MtxValue &value);

    /**
     * Create a named symbol with a value.
     */
    MtxSymbol(MtxLanguage *language, const std::string &name,
              const MtxValue &value);

    MtxSymbol(const MtxSymbol &symbol);
    virtual ~MtxSymbol();

    MtxSymbol & operator=(const MtxSymbol &symbol);

    /**
     * Return a copy of the symbol.
     * 
     * This method is actually where execution takes place.
     * 
     * @param create if the symbol is a nonexistent named variable, create it
     * @param fail_if_special if the symbol is special, raise an exception
     */
    virtual MtxSymbol getSymbol(bool create = false,
                                bool fail_if_special = true) const;

    /**
     * Return the name of the symbol.
     */
    virtual std::string getName() const;

    /**
     * Set the name of the symbol. The symbol becomes a named variable if it
     * was unnamed. It will be registered in the MtxLanguage object when
     * getSymbol() is called.
     */
    void setName(const std::string &name);

    /**
     * Return the address of the underlying value associated to the symbol.
     * 
     * This address can be NULL if no value was associated.
     */
    virtual MtxValue * getValue() const;

    /**
     * Return the string representation of the underlying value.
     */
    virtual std::string toString() const;

    /**
     * This method should never be used on a MtxSymbol object.
     * 
     * @see MtxExpression
     */
    virtual bool isSilent() const;

    /**
     * Return the special member.
     * 
     * @see special
     * @see setSpecial()
     */
    bool isSpecial() const;

    /**
     * Return the address of the associated MtxLanguage object.
     */
    MtxLanguage * getLanguage() const;
};

/*
 * Functions associated to special names.
 */
std::string about(const MtxSymbol *symbol);
std::string list(const MtxSymbol *symbol);
std::string quit(const MtxSymbol *symbol);

#endif /* _MTXSYMBOL_H */