package dsl99lux ;

/**
 * NOTE: The match algorithm used by CmdLineParser.apply
 * is an early version of the algorithm reported for
 * extensionParser.apply in the paper. This version matches
 * Java Strings to method parameters rather than abstract
 * extensionObjects, but the match algorithm and the use
 * of Java reflection remains the same.

 * Copyright (c) 1998-1999  Lucent Technologies, Inc.
 *
 * This software is copyrighted by Lucent Technologies Inc.
 * The following terms apply to all files associated with the
 * software unless explicitly disclaimed in individual files.
 * 
 * The authors hereby grant permission to use and copy this
 * software and its documentation for educational, research
 * and reference purposes provided that existing copyright
 * notices are retained in all copies and that this notice is
 * included verbatim in any distributions. No written agreement,
 * license, or royalty fee is required for such authorized uses.
 * Modifications to this software may not be made without permission.
 * 
 * IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
 * PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
 * DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION,
 * OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
 * IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
 * NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,
 * OR MODIFICATIONS.
 * 
 * GOVERNMENT USE:  If you are acquiring this software on behalf of the
 * U.S. Government, the Government shall have only "Restricted Rights"
 * in the software and related documentation as defined in the Federal
 * Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you
 * are acquiring the software on behalf of the Department of Defense,
 * the software shall be classified as "Commercial Computer Software"
 * and the Government shall have only "Restricted Rights" as defined
 * in Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing,
 * the authors grant the U.S. Government and other acting in its behalf
 * permission to use and distribute the software in accordance with the
 * terms specified in this license.

 * TextListParser is an interface whose 
 * method "SplitList" splits a String into an array
 * of Strings, and whose method "MergeList" merges
 * an array of Strings into a lexically nested String.
 * A specific extension language such as Tcl can supply
 * its own class that implements TextListParser, that
 * implements these methods using the lexical conventions
 * of the language.

 @author Dale Parson
 	 Bell Labs Innovations for Lucent Technologies
	 dparson@lucent.com
*/

public interface TextListParser {
    /**
     * isList returns true if its structuredString represents
     * a legitimate list, otherwise returning false.
     *
     * @param structuredString	The String that isList checks.
     *
     * @return	true on a legitimate list-structured string.
    */
    public boolean isList(String structuredString);

    /**
     * length returns the number of list elements in a list-structured
     * String structuredString, returning 0 on an empty list,
     * and -1 on an invalid list String.
     *
     * @param structuredString	The String that length checks.
     *
     * @return	number of elements, may be 0, -1 on an invalid list.
    */
    public int length(String structuredString);


    /**
     * SplitList parses a nested String into an array of its
     * String members.
     *
     * @param structuredString	The String that SplitList
     * splits into a String array, based on its lexical structure.
     * PRECONDITION: structuredString is a legitimate list.
     *
     * @return	The split array of substrings, null on an invalid String.
    */
    public String[] SplitList(String structuredString);

    /**
     * MergeList merges an array of Strings into a single,
     * properly formatted list-structured string. The
     * structure of the string depends on extension language-
     * specific formatting conventions.
     *
     * @param slist	Array of Strings to combine into a
     * list-structured String.
     *
     * @return	The merged, list-structured String.
    */
    public String MergeList(String slist[]);
}