/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ETNA Relax NG validator.
 *
 * The Initial Developer of the Original Code is The Connexions Project.
 *
 * Portions created by the Initial Developer are Copyright (C) 2004-2006
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Laurent Jouanneau <laurent.jouanneau@disruptive-innovations.com>, Original author
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
#include "domstubs.idl"
#include "nsIMutableArray.idl"
#include "diIValidationSchema.idl"

interface diIStringGraphNode;


/**
 * This interface represents an automaton for string analysis
 */
[scriptable, uuid(9b0fba94-203f-4f6b-9a6c-7e937d3cddec)]
interface diIStringGraphAutomaton : nsISupports
{
    const unsigned short GENERAL_CONTEXT            = 0x01;
    const unsigned short GENERAL_CONTEXT_RESTORE    = 0x03;
    const unsigned short ERROR_CONTEXT              = 0x04;
    const unsigned short ERROR_CONTEXT_RESTORE      = 0x0C;

    /**
     * containts all errors generated during the run through the graph
     * @see diISchemaGraphError
     */
    attribute nsIMutableArray errors;

    /**
     * this is the schema containing one of the graph that the automaton need to walk through
     */
    attribute diIValidationSchema schema;

    /**
     * the sub string that is currently inspected
     */
    readonly attribute DOMString currentSubString;

    /**
    * initialize the automaton
    * @param aString    the string to validate
    */
    void init( in DOMString aString, in boolean aCutIntoSequence);

    /**
    * launch the validation
    * @param aFirstNode
    * @param aNoTestEndChildList
    */
    boolean run (in diIStringGraphNode aFirstNode, in  boolean aNoEndVerification);

    /**
     *
     */
    void matchCurrentSubString();
    
    
    void matchWholeString();
    
    boolean matchEmptyString();
    boolean hasMoreSubString();

    /**
     * push a data into the top of the data stack
     * @param
     */
    void pushData (in nsISupports aData);

    /**
     * push an integer into the top of the data stack
     * @param aData the data to store
     */
    void pushIntData (in long aData);

    /**
     * remove a data from the top of the data stack
     * @return the removed data
     */
    nsISupports popData();

    /**
     * get a data from the top of the data stack without removing it
     * @return the data
     */
    nsISupports peekData();

    /**
     * remove an integer data from the top of the data stack
     * (of course, we have to know that the data on the top is an integer)
     * @return the removed data
     */
    long popIntData();

    /**
     * get an integer from the top of the data stack without removing it
     * (of course, we have to know that the data on the top is an integer)
     * @return the data
     */
    long peekIntData();


   /**
    * Sometimes, during the validation, we have to save some properties of the automaton,
    * (a context)  to validate an element and then retrieve (or not) the old context
    */
   void saveContext(in unsigned short aWhat);

   /**
    * cancel the saving of the context
    * @param aRestoreContext    if true, the old context is restored. if false, the current context don't change
    */
   void undoSaveContext (in unsigned short aWhat);

   /**
    * add an error
    * @param    aCode   the code error
    */
   void addError(in short aCode);

   /**
    * add many errors
    * @param aErrors    an array of the errors
    * @see diISchemaGraphError
    */
   void addErrors(in nsIMutableArray aErrors);

};