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

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = standard graph module guide - chapter 1                            = -->
<!-- ====================================================================== -->
<!-- = 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) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter module="gfx" number="1">
  <title>Standard graph services</title>
  
  <p>
  This chapter covers the graph facilities available in the
  <em>standard graph</em> module. The basic operations are related to
  edge, vertices and graph manipulations.
  </p>

  <p>
  All <afnix/> standard graph objects are located in the
  <code>afnix-gfx</code> module. This module must be loaded prior
  any operation. Multiple calls to the module initialization routine
  are harmless. The interpreter method <code>module</code> loads a
  specific module by name. When the module has been loaded, the
  object are available in the <code>afnix:gfx</code> nameset.
  </p>
  
  <example>
  interp:library "afnix-gfx"
  </example>

  <!-- graph concepts -->
  <section>
    <title>Graph concepts</title>

    <p>
    The <code>afnix-gfx</code> provides the support for manipulating
    graphs. Formally a graph is a collection of edges and vertices. In
    a normal graph, an edge connects two vertices. On the other hand,
    a vertex can have several edges. When an edge connects several
    vertices, it is called an hyperedge and the resulting structure is
    called an hypergraph.
    </p>

    <!-- edge class -->
    <subsect>
      <title>Edge class</title>

      <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. When the edge cardinality
      is one, the edge is called a self-loop. This mean that the edge
      connects the vertex to itself. This last point is merely a
      definition but present the advantage of defining an hyperedge as
      a set of vertices.
      </p>
    </subsect>

    <!-- vertex class -->
    <subsect>
      <title>Vertex class </title>

      <p>
      The <code>Vertex</code> is the other class used for the
      graph construction. and operates with the <code>edge</code>
      class. A vertex is used to reference edges. the number of edges
      referenced by a vertex is called the degree of that vertex.
      </p>
    </subsect>

    <!-- graph class -->
    <subsect>
      <title>Graph</title>

      <p>
      The <code>Graph</code> class is class that represent either a
      graph or a hypergraph. By definition, a graph is collection of
      edges and vertices. There are numerous property attached to
      graph. Formally, a graph consists of a set of edges, a set of
      vertices and the associated endpoints. However, the implementation
      is designed in a way so that each edge and vertex carry its
      associated objects. This method ensures that the graph is fully
      defined by only its two sets.
      </p>
    </subsect>
  </section>

  <!-- graph construction -->
  <section>
    <title>Graph construction</title>

    <p>
    The graph construction is quite simple and proceed by adding edges
    and vertices. The base system does not enforce rules on the graph
    structure. it is possible to add con connected vertices as well as
    unreferenced edges.
    </p>

    <!-- edge construction -->
    <subsect>
      <title>Edge construction</title>

      <p>
      An edge is constructed by simply invoking the default
      constructor. Optionally, a client object can be attached to the
      edge.
      </p>

      <example>
      # create a default edge
      const edge (afnix:gfx:Edge)
      
      # create an edge with a client object
      const hello (afnix:gfx:Edge "hello")
      </example>

      <p>
      The <code>edge-p</code> predicate can be used to check for the
      object type. When an edge is created with client object, the
      <code>get-client</code> method can be used to access that object.
      </p>
    </subsect>

    <!-- vertex construction -->
    <subsect>
      <title>Vertex construction</title>

      <p>
      A vertex is constructed  a way similar to the <code>Edge></code>
      object. The vertex is constructed by simply invoking the default
      constructor. Optionally, a client object can be attached to the
      edge.
      </p>

      <example>
      # create a default vertex
      const vrtx (afnix:gfx:Vertex)
      
      # create an vertex with a client object
      const world (afnix:gfx:Vertex "world")
      </example>

      <p>
      The <code>vertex-p</code> predicate can be used to check for the
      object type. When a vertex is created with a client object, the
      <code>get-client</code> method can be used to access that object.
      </p>
    </subsect>

    <!-- graph construction -->
    <subsect>
      <title>Graph construction</title>

      <p>
      A graph is constructed by simply adding edges and vertices to
      it. The <code>graph-p</code> predicate can be use to assert the
      graph type. the graph class also supports the concept of client
      object which can be attached at construction or with the
      <code>set-client</code> method.
      </p>

      <example>
      const graph (afnix:gfx:Graph)
      </example>
      
      <p>
      The <code>add</code> method can be used to add edges or vertices
      to the graph. The important point is that during the
      construction process, the graph structure is updated with the
      proper number of edge and vertices.
      </p>

      <example>
      # create a graph
      const  g    (afnix:gfx:Graph)
      assert true (afnix:gfx:graph-p g)

      # create an edge and add vertices
      const edge (afnix:gfx:Edge)
      edge:add   (afnix:gfx:Vertex "hello") 
      edge:add   (afnix:gfx:Vertex "world")
      assert 2   (edge:degree)

      # add the edge to the graph and check
      g:add edge
      assert 1 (g:number-of-edges)
      assert 2 (g:number-of-vertices)

      # check for nodes and edges
      assert true (afnix:gfx:edge-p   (g:get-edge   0))
      assert true (afnix:gfx:vertex-p (g:get-vertex 0))
      assert true (afnix:gfx:vertex-p (g:get-vertex 1))
      </example>
    </subsect>
  </section>
</chapter>
