doc/getting_started.dox
changeset 2282 9d7b12f83daa
child 2288 ef8af928c54e
equal deleted inserted replaced
-1:000000000000 0:cee925a4f5fc
       
     1 /**
       
     2 \page getting_started Getting Started
       
     3 
       
     4 At the beginning we hardly suggest that you open your favorite text editor
       
     5 and enter the code simultaneously as you read it. Compiling the demos is also
       
     6 a good exercise.
       
     7 
       
     8 As the first example we show you a lemon style "Hello World" program. Now we
       
     9 explain almost every line, but later we will skip the basics and focus on new
       
    10 things.
       
    11 
       
    12 \section hello_world Hello World in LEMON
       
    13 
       
    14 In this little program we give you a taste of the LEMON programming.
       
    15 
       
    16 Let's see the code fragment to fragment!
       
    17 
       
    18 \dontinclude hello_world.cc
       
    19 \skip include
       
    20 \until iostream
       
    21 
       
    22 We want to use a \c lemon::ListGraph so the include goes like this:
       
    23 \skip include
       
    24 \until list_graph
       
    25 
       
    26 The next few lines are not necessary but useful shortcuts, if you don't
       
    27 want to type \c lemon::ListGraph::Node every time.
       
    28 \skip using
       
    29 \until Edge
       
    30 
       
    31 For this demo we need to declare a ListGraph and a special NodeMap to store the
       
    32 characters associated to the graph's nodes.
       
    33 \skip main
       
    34 \until char_map
       
    35 
       
    36 Adding nodes to the graph is very easy.
       
    37 \skip new_node
       
    38 \until addNode
       
    39 
       
    40 When a new node or edge to the graph the assigned maps are automatically resized.
       
    41 So graphs can be build dynamically. The usage of a map is very natural.
       
    42 \skip char_map
       
    43 \until char_map
       
    44 
       
    45 Notice that no reference or additional assignment needed to work with nodes.
       
    46 They won't become illegal or won't lead to throwing any exceptions.
       
    47 You can declare and handle node like every other basic type such as \c int.
       
    48 \skip Store
       
    49 \until char_map
       
    50 
       
    51 As one expects adding an Edge is similar. You need to define the \b source node
       
    52 and the \b destination node. The nodes must belong to the graph of course. The
       
    53 Edge has the direction from the source to the destination. In some case you don't
       
    54 want the edges to be directed - then you use an undirected graph. For example
       
    55 lemon::ListUGraph.
       
    56 \skip addEdge
       
    57 \until addEdge
       
    58 
       
    59 In the next few lines we add some more nodes and edges and to the graph we need.
       
    60 Those lines are not very interesting so we skip them, but you find the whole
       
    61 working program in file hello_lemon.cc in the demo section.
       
    62 
       
    63 The next statement must be familiar. But what is that INVALID in the \c while
       
    64 test statement? In LEMON we usually use the INVALID to check if an object
       
    65 contains valid information.
       
    66 \skip current_node
       
    67 \until {
       
    68 
       
    69 We take the current node and write out the character assigned to it. Is's easy
       
    70 with the \c char_map.
       
    71 \skip std
       
    72 \until std
       
    73 
       
    74 And here comes the trick. OutEdgeIt iterates on outgoing edges of a given node.
       
    75 We pass the current node as argument to it, so the \c edge iterator will stand
       
    76 on the first outgoing edge of the current node, or will be INVALID if the node
       
    77 has no outgoing edges.
       
    78 \skip edge
       
    79 \until edge
       
    80 
       
    81 The graph we built before is linear, so we know that it ends, when no more outgoing
       
    82 edges found. Otherwise the current node must be the node the edge points to.
       
    83 Basic information about an edge can be requested from the graph.
       
    84 \skip if
       
    85 \until }
       
    86 
       
    87 Finish the code, just to be precise.
       
    88 \skip return
       
    89 \until }
       
    90 
       
    91 
       
    92 \section compile_hw Compiling Hello World
       
    93 To compile this program all you have to do is type in
       
    94 \code g++ -ohw hello_world.cc \endcode
       
    95 and press \c Enter! This is the case if you installed LEMON on your system.
       
    96 (For more information see the LEMON installation instructions.)
       
    97 
       
    98 This is because LEMON is template library and most of it's code has to be available
       
    99 as source code during compilation.
       
   100  
       
   101 Most programs using LEMON will compile as easy as this one unless you want to
       
   102 use some performance measuring tools LEMON can provide. Then you need to link
       
   103 an additional library against your program.
       
   104 */