TextFile2Tree

/*
Copyright 2005 by the authors of asapframework

Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

import org.asapframework.util.StringUtilsSplit;
import org.asapframework.util.StringUtilsTrim;
import data.filedatatransform.*;
import data.tree.*;

/**
This simple text parser, inspired by ogdl (see http://ogdl.org), reads in a text file and transforms its content to {@link TreeNode} nodes (or a subclass of TreeNode, depending on the type of the root node), where each word corresponds to a node name (identifier).

The text file uses tab indenting to indicate node depths:
<code>
Home
    GamePass
        Points
        ClaimPrize
            SendToAddress
        PersonalData
    Help
        GamesHelp
Disclaimer
    PrivacyDetails
</code>
Zero tabs indicate a node depth of 1 (depth 0 is reserved for the root node - the root node is not written in the text file).

Node properties can be passed as a comma-separated list, with the syntax {@code key=value}. In the following example file text, each line starts with the node name, followed by an arbitrary text called {@code text}, and a statistics id.
<code>
Home, text=Homepage, id=FYOS_0100_flash_home
    GamePass, text=Game Pass, stats_id=FYOS_0200_game_pass
</code>
Node properties are stored in the {@link TreeNode#properties} member as Value Object, and can be accessed with {@link TreeNode#getValueForKey}. See also {@link TreeEnumerator} for an example to access TreeNodes.

Two characters are reserved for parsing: the comma ({@code ,}) and the equals sign ({@code =}). If you want to use these characters inside a property text, surround the text by quotes. For instance: <code>GamePass, text="Game Pass, Personal Items", stats_id=QWERTY_0010</code>. The text will be returned as {@code Game Pass, Personal Items}, without quotes and with the comma preserved.

Another way is to set a different delimiter or key/value delimiter in the constructor.
@use
<code>
var transformer:TextFile2Tree = new TextFile2Tree(DATA_URL, this);
transformer.load();
</code>
In same class implement the 'finished' event method:
<code>
private function onTextFile2TreeFinished (inEvent:TextFile2TreeEvent) : Void
{
    mTree = inEvent.tree;
    mTree.printNodes();
}
</code>
@author Arthur Clemens
@version 20 July 2005
*/

class data.filedatatransform.TextFile2Tree extends TextFile2Collection {    
    
    private var ITEM_DELIMITER:String = ","; /**< Property delimiter. */
    private var KEY_VALUE_DELIMITER:String = "="; /**< Key-value pair delimiter. */
    
    /**
    Creates a new TextFile2Tree instance.
    @param inFileUrl: url of the text file with data to parse
    @param inListener: (optional) object that receives a {@link TextFile2TreeEvent#FINISHED} after parsing
    @param inCollection: (optional) existing Tree object to store the data in; if not provided, a new Tree will be created
    @param inItemDelimiter: (optional) character to split each line in separate property components; default a comma (",")
    @param inKeyValueDelimiter: (optional) character to split each key/value pair in components; default an equals sign  ("=")
    @example
    <code>
    mTree = new Tree("Site tree");
    var siteDataUrl:String = "../../www/data/sitedata.txt";
    new TextFile2Tree(dataUrl, this, mTree).load(); // sets 'this' as listener
    </code>
    Implement listener method:
    <code>
    private function onTextFile2TreeFinished (inEvent:TextFile2TreeEvent) : Void
    {
        var filledTree:Tree = inEvent.tree;
        filledTree.printNodes();
    }
    </code>
    */
    public function TextFile2Tree (inFileUrl:String,
                                   inListener:Object,
                                   inTree:Tree,
                                   inItemDelimiter:String,
                                   inKeyValueDelimiter:String) 
    {
        super(inFileUrl, inListener, inTree);
        if (inItemDelimiter) {
            ITEM_DELIMITER = inItemDelimiter;
        }
        if (inKeyValueDelimiter) {
            KEY_VALUE_DELIMITER = inKeyValueDelimiter;
        }
    }
    
    /**
    Creates TreeNode objects (or subclass thereof) and adds them to the Tree passed in {@link #TextFile2Tree}; if no Tree was passed to the constructor, a new Tree object is created.
    @param inSource: the file data
    @implementationNote After parsing, {@link #notifyFinished} is called.
    */
    private function parse (inSource:String) : Void
    {
        if (mCollection == undefined) {
            mCollection = new Tree("TextFile2Tree tree");
            Tree(mCollection).createRootNode();
        }
        addEventListener(TextFile2TreeEvent.FINISHED, mListener);


        var lines:Array = inSource.split("\n");
        var i:Number, ilen:Number = lines.length;
        var node_id_nodeDepth:Object = new Object();
        for (i=0; i<ilen; ++i) {
            var line:String = lines[i];
            var id:String;
            var lastTabPos:Number = line.lastIndexOf("\t");
            var contentPos:Number = lastTabPos + 1;
            if (lastTabPos == -1) {
                // no tabs, use position 0
                contentPos = 0;
            }

            var components:Array = StringUtilsSplit.splitSpecial(line, ITEM_DELIMITER);    
            id = String(components.shift()); // first element is the id
            if (id.substr(0,1) == "#") {
                // comment
                continue;
            }
            var properties:Object = parseProperties(components);

            var nodeDepth:Number = lastTabPos + 1; // assuming 0 is root
            
            // attach to which node?
            var attachNode:TreeNode = node_id_nodeDepth[nodeDepth-1]; // getting an undefined and passing this to Tree.addChild is solved by Tree
            var newNode:TreeNode = Tree(mCollection).addChild(id, attachNode, properties);
            // store this id at this node depth
            node_id_nodeDepth[nodeDepth] = newNode;
        }
        notifyFinished();
    }
    
    /**
    Method used by {@link #parse}. Transforms an array of {@code key=value} texts to one value object. The  delimiter character is {@link #KEY_VALUE_DELIMITER}.
    */
    private function parseProperties (inArray:Array) : Object
    {
        var o:Object = {};
        var ilen:Number = inArray.length;
        var i:Number = ilen;
        while (i--) {
            var keyValue:Array = StringUtilsSplit.splitSpecial(inArray[i], KEY_VALUE_DELIMITER);
            var key:String = trimQuotes(keyValue[0]);
            var value:String = trimQuotes(keyValue[1]);
            o[key] = value;
        }
        return o;
    }
    
    /**
    Called when parsing is done.
    @sends TextFile2TreeEvent#FINISHED
    */
    private function notifyFinished () : Void
    {
        dispatchEvent(new TextFile2TreeEvent(TextFile2TreeEvent.FINISHED, Tree(mCollection)));
        if (mListener != undefined) {
            removeEventListener(TextFile2TreeEvent.FINISHED, mListener);
        }
    }
    
    /**-----------------------------------------------------------------------------
    Removes quote characters at both ends of a string.
    @param inString : String to convert
    ------------------------------------------------------------------------------*/
    private function trimQuotes (inString:String) : String {
        var text:String = StringUtilsTrim.leftTrimForChars(inString, StringUtilsTrim.QUOTE_CHAR);
        return StringUtilsTrim.rightTrimForChars(text, StringUtilsTrim.QUOTE_CHAR);
    }

}