/* -*- 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 diISchemaGraphNode;
interface diIStringGraphAutomaton;
interface diIStringGraphNode;

/**
 * This interface represents an automaton that is responsible to run through a graph
 * and manage all events that occurs during this run.
 * it containts two stacks to save/restore some data during the validation
 * - one for various datas
 * - one for errors
 */
[scriptable, uuid(677898ec-a284-434c-b942-985ed2082b8c)]
interface diISchemaGraphAutomaton : 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;
    const unsigned short MODE_CONTEXT               = 0x10;
    const unsigned short MODE_CONTEXT_RESTORE       = 0x30;


    const unsigned short SEQUENTIAL_MODE = 1;
    const unsigned short INTERLEAVE_MODE = 3;


    /**
     * containts all errors generated during the run through the graph
     * @see diISchemaGraphError
     */
    attribute nsIMutableArray errors;
    
    /**
     * containts all old canceled errors generated during the run through the graph
     * internal use
     * @see diISchemaGraphError
     */
    readonly attribute nsIMutableArray errorsHistory;

    /**
     * it is the current attribute that is currently tested
     */
    attribute nsIDOMAttr currentAttribute;

    /**
     * says if all attributes are matched
     */
    readonly attribute boolean allAttributesMatched;

    /**
     *
     */
    attribute boolean recursive;
    
    /**
     *
     */
    attribute boolean prepareForEditing;

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

    /**
     * the current DOM Element that it is currently inspected
     */
    readonly attribute nsIDOMNode currentChildDomNode;

    /**
     * the DOM element which its children will be match against the graph
     */
    readonly attribute nsIDOMNode domElement;

    /**
     * the value of the current text node analysed
     */
    attribute DOMString currentTextNodeValue;

    /**
     *
     */
    attribute unsigned short matchMode;

    /**
     *
     */
    readonly attribute diIStringGraphAutomaton stringAutomaton;

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

    /**
     * initialize the automaton
     * @param aDomElement    the dom element from which we will verify its children (will become the parentDomElement)
     */
    void init( in nsIDOMNode aDomElement);

   /**
    * initialize the automaton with a "virtual" child node or fragment
    * @param aDomElement    the dom element from which the automaton will verify the content 
    * @param aChild/aFragment  the child to replace/remove or which will become the previous or next child after/before the virtual one
    * @param aVirtualChild/aVirtualFragment  the "virtual" child/Fragment that the automaton must insert in the child list
    * @param aInitType a flag that says what the automaton should do with the given node (see INIT_* constant)
    */
    const  short INIT_INSERT_BEFORE = 1;
    const  short INIT_INSERT_AFTER  = 2;
    const  short INIT_REMOVE        = 3;
    const  short INIT_REPLACE       = 4;

    /**
     * Initialize the automaton on an element and insert before/insert after/replace/remove a node child by the given one
     */
    void initWithVirtualChild( in nsIDOMNode aDomElement, in nsIDOMNode aChild, in nsIDOMNode aVirtualChild, in short aInitType);

    /**
     * Initialize the automaton on an element and insert before/insert after/replace/remove a fragment ( children of the given node) by a new node
     */
    void initWithVirtualChildFragment( in nsIDOMNode aDomElement, in nsIDOMNode aFragment, in nsIDOMNode aVirtualChild,   in short aInitType);
    /**
     * Initialize the automaton on an element and insert before/insert after/replace/remove a node by a fragment ( children of the given node)
     */
    void initWithVirtualFragmentChild( in nsIDOMNode aDomElement, in nsIDOMNode aChild, in nsIDOMNode aVirtualFragment,in short aInitType);
    /**
     * Initialize the automaton on an element and insert before/insert after/replace/remove a fragment by a another fragment 
     */
    void initWithVirtualFragment( in nsIDOMNode aDomElement, in nsIDOMNode aFragment, in nsIDOMNode aVirtualFragment, in short aInitType);
    
    
    /**
     * Initialize the automaton on an element, split one of its children, and insert a given node at the split
     */
    void initWithVirtualChildInsertion( in nsIDOMNode aDomElement, in nsIDOMNode aChildToSplit, in long aOffset, in nsIDOMNode aVirtualChild);
    /**
     * Initialize the automaton on an element, split one of its children, and insert children of the given node at the split
     */
    void initWithVirtualFragmentInsertion( in nsIDOMNode aDomElement, in nsIDOMNode aChildToSplit, in long aOffset, in nsIDOMNode aVirtualFragment);
    

   /**
    * initialize the automaton on the given element and set an attribute
    * @param aDomElement    the dom element from which we will verify its children
    * @param aVirtualAttr  the "virtual" attribute that the automaton must insert in the attribute list
    */
    void initWithVirtualAttribute( in nsIDOMNode aDomElement,  in nsIDOMAttr aVirtualAttr, in boolean aValidateValue);

   /**
    * initialize the automaton on the given element and remove an attribute
    * @param aDomElement    the dom element from which we will verify its children
    * @param aVirtualAttr  the attribute that the automaton must remove from the attribute list
    */
    void initWithRemovedAttribute(in nsIDOMNode aDomElement,  in nsIDOMAttr aAttribute);

   /**
    * launch the validation
    * @param aFirstNode
    * @param aNoChildListEndTest
    */
   boolean run (in diISchemaGraphNode aFirstNode, in boolean aNoChildListEndTest);


   boolean isVirtualElementMatched();
   /**
    *
    */
   void matchCurrentChildDomNode();

   /**
    *
    */
   void matchAllTextNode();
   void matchEmpty();
   void matchVirtualTextNode();
   void matchAnyName();
   void matchWhitespaceTextNode();
   /**
    *
    */
   boolean toNextChildDomNode();


   boolean ValidateAttributeWithGraph( in diISchemaGraphNode aGraphForName, in diIStringGraphNode aValueGraph);
   boolean ValidateAttribute(in AString aLocalName, in AString aNamespaceURI, in diIStringGraphNode aValueGraph);
   boolean ValidateFirstAttribute(in diIStringGraphNode aValueGraph);

   /**
    *
    */
   void saveCurrentChildDomNodePosition();

   void returnToLastSavedChildDomNodePosition();

   void undoLastSavedChildDomNodePosition();


   /**
    * For oneOrMore or zeroOrMore pattern, to avoid entering in an infinited loop with text pattern etc..
    * (see oneOrMore & zeroOrMore pattern)
    * call it in the first node of the graph that made a loop
    */
    void beginLoop();

   /**
    * For oneOrMore or zeroOrMore pattern, to avoid entering in an infinited loop
    * (see oneOrMore & zeroOrMore pattern)
    * call it at the end of a round.
    * @return boolean says if something have been matched (text node, attribute, element node...)
    */
    boolean roundLoop();

   /**
    * For oneOrMore or zeroOrMore pattern, to avoid entering in an infinited loop
    * (see oneOrMore & zeroOrMore pattern)
    * call it at the end of the graph.
    */
    void endLoop();


    void ChoiceBegin();
    boolean ChoicePosCheckPoint();
    void ChoiceNegCheckPoint();
    void ChoicePosEnd();
    boolean ChoiceNegEnd();


   /**
    * 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 relating to  the DOM node declared in domElement property
    * @param    aCode   the code error
    */
   void addError(in short aCode);

   /**
    * add an error relating to a specific DOM node
    * @param    aCode   the code error
    * @param    aDomNode    the dom node
    */
   void addErrorOnDomNode(in short aCode, in nsIDOMNode aDomNode);

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

};


/**
 * diISchemaGraphError represents a container for a validation error
 */
[scriptable, uuid(8f9de014-60ba-42a8-aa42-4d3e3faaa7be)]

interface diISchemaGraphError : nsISupports
{
   attribute short errorCode;
   attribute nsIDOMNode node;
   attribute AString miscInfo1;
   attribute AString miscInfo2;

};