<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<!--
// // See license.txt for license information. // // tool.xml // // 12-Aug-2003 phamilton Created //
-->

<object xmlns:xi="http://www.w3.org/2001/XInclude" xmlns="urn:xmlliterate.schema" name="@tool">
    <description>Abstract class representing a tool. A tool is a piece of software without any special UI requirements other than a console for outputting status information, and an output stream. Typically tools mimic shell scripts like in a unix environment, or "console" programs.</description>
    <classname>tool</classname>
    <namespace>ph:tools</namespace>
    <templates>
        <xi:include href="../../xml/typename/xmlobj/xmlobj_contextptrtype.xml"/>
        <xi:include href="../../xml/typename/stringmapptrtype.xml"/>
        <xi:include href="../../xml/typename/chararrayptrtype.xml"/>
    </templates>
    <typeimpls>
        <xi:include href="../../xml/typeimpl/xmlobj/cpp/xmlobj_contextptrtype.xml"/>
        <xi:include href="../../xml/typeimpl/cpp/stringmapptrtype.xml"/>
        <xi:include href="../../xml/typeimpl/cpp/chararrayptrtype.xml"/>
    </typeimpls>
    <members>
        <templatevectortype name="templates">
            <description>Template objects used to create others.</description>
        </templatevectortype>
    </members>
    <methods>
        <method name="process">
            <inheritance>abstract</inheritance>
            <access>public</access>
            <description>Do whatever the tool does. All tools override this method and then provide an implementation to do whatever they need to do. Typically they will process information and then output something to an output buffer.</description>
            <returns>
                <booltype>
                    <description>Returns true if the function is successful.</description>
                </booltype>
            </returns>
            <arguments>
                <streamptrtype name="console">
                    <description>A place to put errors or status information which is not meant to be part of the output.</description>
                </streamptrtype>
                <streamptrtype name="output">
                    <description>The output stream for this tool.</description>
                </streamptrtype>
            </arguments>
        </method>
        <method name="handle_args">
            <access>public</access>
            <scope>global</scope>
            <description>Handle the arguments list from the command line. The arguments are in the form of "name=value" pairs which are used to replace values inside the "tool" object declarations for each run.</description>
            <returns>
                <booltype>
                    <description>Returns true if the function is successful.</description>
                </booltype>
            </returns>
            <arguments>
                <inttype name="argc">
                    <description>The argument count.</description>
                </inttype>
                <chararrayptrtype name="argv">
                    <description>The argument vector.</description>
                </chararrayptrtype>
                <stringmapptrtype name="params">
                    <description>The parameters.</description>
                </stringmapptrtype>
            </arguments>
            <implementations>
                <xi:include href="cpp/handle_args.xml"/>
            </implementations>
        </method>
        <method name="tool_main">
            <access>public</access>
            <scope>global</scope>
            <description>Process an actual main() with arguments.</description>
            <returns>
                <inttype>
                    <description>Returns the error level for the OS.</description>
                </inttype>
            </returns>
            <arguments>
                <xmlobj_contextptrtype name="context">
                    <description>A context to pass through to the tool.</description>
                </xmlobj_contextptrtype>
                <stringtype name="filename">
                    <description>The filename to run. This is an XML script containing creation arguments for the tool file.</description>
                </stringtype>
            </arguments>
            <implementations>
                <xi:include href="cpp/tool_main.xml"/>
            </implementations>
        </method>
    </methods>
</object>