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

<!-- ====================================================================== -->
<!-- = afnix-rm-gfx.xml                                                   = -->
<!-- = standard graph module - reference manual                           = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 1999-2023 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="gfx" number="i">
  <title>Standard Graph Reference</title>

  <!-- =================================================================== -->
  <!-- = state object                                                    = -->
  <!-- =================================================================== -->

  <object nameset="afnix:gfx">
    <name>State</name>

    <p>
      The <code>State</code> class is a class the graph object library. The
      state is used to model vertex and edge and can be used seldom in
      structure like finite automaton.
    </p>

    <!-- predicate -->
    <pred>state-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>State</name>
	<args>none</args>
	<p>
	  The <code>State</code> constructor create an empty state.
	</p>
      </ctor>

      <ctor>
	<name>State</name>
	<args>Object</args>
	<p>
	  The <code>State</code> constructor create a state edge with
	  a client object.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>clear</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>clear</code> method clear the state marker.
	</p>
      </meth>

      <meth>
	<name>get-index</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-idex</code> method returns the state index.
	</p>
      </meth>
      <meth>
	<name>set-idnex</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-index</code> method sets the state index.
	</p>
      </meth>

      <meth>
	<name>get-client</name>
	<retn>Object</retn>
	<args>none</args>
	<p>
	  The <code>get-client</code> method returns the state client
	  object. If the client object is not set, nil is returned.
	</p>
      </meth>

      <meth>
	<name>set-client</name>
	<retn>Object</retn>
	<args>Object</args>
	<p>
	  The <code>set-client</code> method sets the state client object. The
	  object is returned by this method.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = edge object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:gfx">
    <name>Edge</name>

    <p>
      The <code>Edge</code> class is a class used for a graph
      construction in association with the <code>Vertex</code> class. 
      An edge is used to connect vertices. Normally, an edge connects
      two vertices. The number of vertices attached to an edge is
      called the cardinality of that edge. A client object can also be
      attached to the class.
    </p>

    <!-- predicate -->
    <pred>edge-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>State, Collectable</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Edge</name>
	<args>none</args>
	<p>
	  The <code>Edge</code> constructor create an empty edge.
	</p>
      </ctor>

      <ctor>
	<name>Edge</name>
	<args>Object</args>
	<p>
	  The <code>Edge</code> constructor create an edge with a
	  client object. 
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset all vertices attached to the edge.
	</p>
      </meth>

      <meth>
	<name>cardinality</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>cardinality</code> method returns the cardinality of the
	  edge. The cardinality of an edge is the number of attached vertices.
	</p>
      </meth>

      <meth>
	<name>add</name>
	<retn>Vertex</retn>
	<args>Vertex</args>
	<p>
	  The <code>add</code> method attach a vertex to this edge.
	  The method return the argument vertex.
	</p>
      </meth>

      <meth>
	<name>get</name>
	<retn>Vertex</retn>
	<args>Integer</args>
	<p>
	  The <code>get</code> method returns the attached vertex by
	  index. If the index is out-of range, and exception is raised.
	</p>
      </meth>
    </methods>
  </object>
  
  <!-- =================================================================== -->
  <!-- = vertex object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:gfx">
    <name>Vertex</name>

    <p>
      The <code>Vertex</code> class is a class used for a graph
      construction in association with the <code>Edge</code> class. 
      An vertex is an edge node. The number of edges referenced by a
      vertex is called the degree of that vertex. A client object can
      also be attached to the object.
    </p>

    <!-- predicate -->
    <pred>vertex-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>State, Collectable</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Vertex</name>
	<args>none</args>
	<p>
	  The <code>Vertex</code> constructor create an empty vertex.
	</p>
      </ctor>

      <ctor>
	<name>Vertex</name>
	<args>Object</args>
	<p>
	  The <code>Vertex</code> constructor create a vertex with a
	  client object.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset all edges attached to
	  the vertex.
	</p>
      </meth>

      <meth>
	<name>degree</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>degree</code> method returns the degree of the
	  vertex. The degree of a vertex is the number of referenced edges.
	</p>
      </meth>

      <meth>
	<name>add</name>
	<retn>Edge</retn>
	<args>Edge</args>
	<p>
	  The <code>add</code> method references an edge with this vertex.
	  The method return the argument edge.
	</p>
      </meth>

      <meth>
	<name>get</name>
	<retn>Edge</retn>
	<args>Integer</args>
	<p>
	  The <code>get</code> method returns the referenced edge by
	  index. If the index is out-of range, and exception is raised.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = graph object                                                    = -->
  <!-- =================================================================== -->

  <object nameset="afnxi:gfx">
    <name>Graph</name>

    <p>
      The <code>Graph</code> object is a general graph class that
      manages a set of edges and vertices. The graph operates by adding
      edges and vertices to it.
    </p>

    <!-- predicate -->
    <pred>graph-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Graph</name>
	<args>none</args>
	<p>
	  The <code>Graph</code> constructor create an empty graph.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the graph
	</p>
      </meth>
      <meth>
	<name>clear</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>clear</code> method clear the graph
	</p>
      </meth>

      <meth>
	<name>add</name>
	<retn>Object</retn>
	<args>Vertex|Edge</args>
	<p>
	  The <code>add</code> method adds a vertex or an edge to the
	  graph. When adding an edge, the methods check that the source and
	  target vertices are also part of the graph.
	</p>
      </meth>

    </methods>
  </object>
</appendix>
