diff --git a/doc/Makefile.am b/doc/Makefile.am --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -6,6 +6,7 @@ doc/lgf.dox \ doc/license.dox \ doc/mainpage.dox \ + doc/migration.dox \ doc/named-param.dox \ doc/namespaces.dox \ doc/html \ diff --git a/doc/mainpage.dox b/doc/mainpage.dox --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -56,5 +56,5 @@ Modules section. - +If you are a user of the old (0.x) series of LEMON, please check out the \ref migration "Migration Guide" for the backward incompatibilities. */ diff --git a/doc/migration.dox b/doc/migration.dox new file mode 100644 --- /dev/null +++ b/doc/migration.dox @@ -0,0 +1,143 @@ +/* -*- mode: C++; indent-tabs-mode: nil; -*- + * + * This file is a part of LEMON, a generic C++ optimization library. + * + * Copyright (C) 2003-2008 + * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport + * (Egervary Research Group on Combinatorial Optimization, EGRES). + * + * Permission to use, modify and distribute this software is granted + * provided that this copyright notice appears in all copies. For + * precise terms see the accompanying LICENSE file. + * + * This software is provided "AS IS" with no warranty of any kind, + * express or implied, and with no claim as to its suitability for any + * purpose. + * + */ + +namespace lemon { +/*! + +\page migration Migration from the 0.x Series + +This guide gives an in depth description on what has changed compared +to the 0.x release series. + +Many of these changes adjusted automatically by the +script/lemon-0.x-to-1.x.sh tool. Those requiring manual +update are typeset boldface. + +\section migration-graph Graph Related Name Changes + +- \ref concepts::Digraph "Directed graphs" are called \c Digraph and + they have Arcs (instead of Edges), while + \ref concepts::Graph "undirected graphs" are called \c Graph + (instead of \c UGraph) and they have Edges (instead of + UEdges). These changes reflected thoroughly everywhere in + the library. Namely, + - \c Graph -> \c Digraph + - \c %ListGraph -> \c ListDigraph, \c %SmartGraph -> \c SmartDigraph etc. + - \c UGraph -> \c Graph + - \c ListUGraph -> \c ListGraph, \c SmartUGraph -> \c SmartGraph etc. + - \c Edge -> \c Arc, \c UEdge -> \c Edge + - \c EdgeMap -> \c ArcMap, \c UEdgeMap -> \c EdgeMap + - \c EdgeIt -> \c ArcIt, \c UEdgeIt -> \c EdgeIt + - Class names and function names containing the words \c graph, + \c ugraph, \e edge or \e arc should also be updated. +- The two endpoints of an (\e undirected) \c Edge can be obtained by the + u() and v() member function of the graph + (instead of source() and target()). This change + must be done by hand. + \n Of course, you can still use source() and target() + for Arcs (directed edges). + +\warning +The script/lemon-0.x-to-1.x.sh tool replaces all instances of +the words \c graph, \c digraph, \c edge and \c arc, so it replaces them +in strings, comments etc. as well as in all identifiers. + +\section migration-lgf LGF tools + - The \ref lgf-format "LGF file format" has changed, + \@nodeset has changed to \@nodes, + \@edgeset and \@uedgeset to \@arcs or + \@edges, which become completely equivalents. The + \@nodes, \@edges and \@uedges sections are + removed from the format, the content of them should be + the part of \@attributes section. The data fields in + the sections must follow a strict format, they must be either character + sequences without whitespaces or quoted strings. + - The LemonReader and LemonWriter core interfaces + are no longer available. + - The implementation of the general section readers and writers has changed + they are simple functors now. Beside the old + stream based section handling, currently line oriented section + reading and writing are also supported. In the + section readers the lines must be counted manually. The sections + should be read and written with the SectionWriter and SectionReader + classes. + - Instead of the item readers and writers, item converters should be + used. The converters are functors, which map the type to + std::string or std::string to the type. The converters for standard + containers hasn't yet been implemented in the new LEMON. The converters + can return strings in any format, because if it is necessary, the LGF + writer and reader will quote and unquote the given value. + - The DigraphReader and DigraphWriter can used similarly to the + 0.x series, however the read or write prefix of + the member functions are removed. + - The new LEMON supports the function like interface, the \c + digraphReader and \c digraphWriter functions are more convenient than + using the classes directly. + +\section migration-search BFS, DFS and Dijkstra +- Using the function interface of BFS, DFS and %Dijkstra both source and + target nodes can be given as parameters of the run() function + (instead of \c bfs(), \c dfs() or \c dijkstra() itself). +- \ref named-templ-param "Named class template parameters" of \c Bfs, + \c Dfs, \c Dijkstra, \c BfsVisit, \c DfsVisit are renamed to start + with "Set" instead of "Def". Namely, + - \c DefPredMap -> \c SetPredMap + - \c DefDistMap -> \c SetDistMap + - \c DefReachedMap -> \c SetReachedMap + - \c DefProcessedMap -> \c SetProcessedMap + - \c DefHeap -> \c SetHeap + - \c DefStandardHeap -> \c SetStandardHeap + - \c DefOperationTraits -> \c SetOperationTraits + - \c DefProcessedMapToBeDefaultMap -> \c SetStandardProcessedMap + +\section migration-error Exceptions and Debug tools + +The class hierarchy of exceptions has largely been simplified. Now, +only the i/o related tools may throw exceptions. All other exceptions +have been replaced with either the \c LEMON_ASSERT or the \c LEMON_DEBUG +macros. + +On the other hand, the parameter order of constructors of the +exceptions has been changed. See \ref IoError and \ref FormatError for +more details. + +\section migration-other Others +- The contents of graph_utils.h are moved to core.h + and maps.h. core.h is included by all graph types, + therefore it usually do not have to be included directly. +- path_utils.h is merged to \c path.h. +- The semantic of the assignment operations and copy constructors of maps + are still under discussion. So, you must copy them by hand (i.e. copy + each entry one-by-one) +- The parameters of the graph copying tools (i.e. \c GraphCopy, + \c DigraphCopy) have to be given in the from-to order. +- \c copyDigraph() and \c copyGraph() are renamed to \c digraphCopy() + and \c graphCopy(), respectively. +- The interface of \ref DynArcLookUp has changed. It is now the same as + of \ref ArcLookUp and \ref AllArcLookUp +- Some map types should also been renamed. Namely, + - \c IntegerMap -> \c RangeMap + - \c StdMap -> \c SparseMap + - \c FunctorMap -> \c FunctorToMap + - \c MapFunctor -> \c MapToFunctor + - \c ForkWriteMap -> \c ForkMap + - \c StoreBoolMap -> \c LoggerBoolMap +- \c dim2::BoundingBox -> \c dim2::Box + +*/ +} diff --git a/scripts/lemon-0.x-to-1.x.sh b/scripts/lemon-0.x-to-1.x.sh new file mode 100755 --- /dev/null +++ b/scripts/lemon-0.x-to-1.x.sh @@ -0,0 +1,127 @@ +#!/bin/bash + +set -e + +if [ $# -eq 0 -o x$1 = "x-h" -o x$1 = "x-help" -o x$1 = "x--help" ]; then + echo "Usage:" + echo " $0 source-file" + exit +fi + +TMP=`mktemp` + +sed -e "s/undirected graph/_gr_aph_label_/g"\ + -e "s/undirected edge/_ed_ge_label_/g"\ + -e "s/graph_/_gr_aph_label__/g"\ + -e "s/_graph/__gr_aph_label_/g"\ + -e "s/UGraph/_Gr_aph_label_/g"\ + -e "s/uGraph/_gr_aph_label_/g"\ + -e "s/ugraph/_gr_aph_label_/g"\ + -e "s/Graph/_Digr_aph_label_/g"\ + -e "s/graph/_digr_aph_label_/g"\ + -e "s/UEdge/_Ed_ge_label_/g"\ + -e "s/uEdge/_ed_ge_label_/g"\ + -e "s/uedge/_ed_ge_label_/g"\ + -e "s/IncEdgeIt/_In_cEd_geIt_label_/g"\ + -e "s/Edge/_Ar_c_label_/g"\ + -e "s/edge/_ar_c_label_/g"\ + -e "s/ANode/_Re_d_label_/g"\ + -e "s/BNode/_Blu_e_label_/g"\ + -e "s/A-Node/_Re_d_label_/g"\ + -e "s/B-Node/_Blu_e_label_/g"\ + -e "s/anode/_re_d_label_/g"\ + -e "s/bnode/_blu_e_label_/g"\ + -e "s/aNode/_re_d_label_/g"\ + -e "s/bNode/_blu_e_label_/g"\ + -e "s/_Digr_aph_label_/Digraph/g"\ + -e "s/_digr_aph_label_/digraph/g"\ + -e "s/_Gr_aph_label_/Graph/g"\ + -e "s/_gr_aph_label_/graph/g"\ + -e "s/_Ar_c_label_/Arc/g"\ + -e "s/_ar_c_label_/arc/g"\ + -e "s/_Ed_ge_label_/Edge/g"\ + -e "s/_ed_ge_label_/edge/g"\ + -e "s/_In_cEd_geIt_label_/IncEdgeIt/g"\ + -e "s/_Re_d_label_/Red/g"\ + -e "s/_Blu_e_label_/Blue/g"\ + -e "s/_re_d_label_/red/g"\ + -e "s/_blu_e_label_/blue/g"\ + -e "s/\(\W\)DefPredMap\(\W\)/\1SetPredMap\2/g"\ + -e "s/\(\W\)DefPredMap$/\1SetPredMap/g"\ + -e "s/^DefPredMap\(\W\)/SetPredMap\1/g"\ + -e "s/^DefPredMap$/SetPredMap/g"\ + -e "s/\(\W\)DefDistMap\(\W\)/\1SetDistMap\2/g"\ + -e "s/\(\W\)DefDistMap$/\1SetDistMap/g"\ + -e "s/^DefDistMap\(\W\)/SetDistMap\1/g"\ + -e "s/^DefDistMap$/SetDistMap/g"\ + -e "s/\(\W\)DefReachedMap\(\W\)/\1SetReachedMap\2/g"\ + -e "s/\(\W\)DefReachedMap$/\1SetReachedMap/g"\ + -e "s/^DefReachedMap\(\W\)/SetReachedMap\1/g"\ + -e "s/^DefReachedMap$/SetReachedMap/g"\ + -e "s/\(\W\)DefProcessedMap\(\W\)/\1SetProcessedMap\2/g"\ + -e "s/\(\W\)DefProcessedMap$/\1SetProcessedMap/g"\ + -e "s/^DefProcessedMap\(\W\)/SetProcessedMap\1/g"\ + -e "s/^DefProcessedMap$/SetProcessedMap/g"\ + -e "s/\(\W\)DefHeap\(\W\)/\1SetHeap\2/g"\ + -e "s/\(\W\)DefHeap$/\1SetHeap/g"\ + -e "s/^DefHeap\(\W\)/SetHeap\1/g"\ + -e "s/^DefHeap$/SetHeap/g"\ + -e "s/\(\W\)DefStandardHeap\(\W\)/\1SetStandradHeap\2/g"\ + -e "s/\(\W\)DefStandardHeap$/\1SetStandradHeap/g"\ + -e "s/^DefStandardHeap\(\W\)/SetStandradHeap\1/g"\ + -e "s/^DefStandardHeap$/SetStandradHeap/g"\ + -e "s/\(\W\)DefOperationTraits\(\W\)/\1SetOperationTraits\2/g"\ + -e "s/\(\W\)DefOperationTraits$/\1SetOperationTraits/g"\ + -e "s/^DefOperationTraits\(\W\)/SetOperationTraits\1/g"\ + -e "s/^DefOperationTraits$/SetOperationTraits/g"\ + -e "s/\(\W\)DefProcessedMapToBeDefaultMap\(\W\)/\1SetStandardProcessedMap\2/g"\ + -e "s/\(\W\)DefProcessedMapToBeDefaultMap$/\1SetStandardProcessedMap/g"\ + -e "s/^DefProcessedMapToBeDefaultMap\(\W\)/SetStandardProcessedMap\1/g"\ + -e "s/^DefProcessedMapToBeDefaultMap$/SetStandardProcessedMap/g"\ + -e "s/\(\W\)IntegerMap\(\W\)/\1RangeMap\2/g"\ + -e "s/\(\W\)IntegerMap$/\1RangeMap/g"\ + -e "s/^IntegerMap\(\W\)/RangeMap\1/g"\ + -e "s/^IntegerMap$/RangeMap/g"\ + -e "s/\(\W\)integerMap\(\W\)/\1rangeMap\2/g"\ + -e "s/\(\W\)integerMap$/\1rangeMap/g"\ + -e "s/^integerMap\(\W\)/rangeMap\1/g"\ + -e "s/^integerMap$/rangeMap/g"\ + -e "s/\(\W\)copyGraph\(\W\)/\1graphCopy\2/g"\ + -e "s/\(\W\)copyGraph$/\1graphCopy/g"\ + -e "s/^copyGraph\(\W\)/graphCopy\1/g"\ + -e "s/^copyGraph$/graphCopy/g"\ + -e "s/\(\W\)copyDigraph\(\W\)/\1digraphCopy\2/g"\ + -e "s/\(\W\)copyDigraph$/\1digraphCopy/g"\ + -e "s/^copyDigraph\(\W\)/digraphCopy\1/g"\ + -e "s/^copyDigraph$/digraphCopy/g"\ + -e "s/\(\W\)\([sS]\)tdMap\(\W\)/\1\2parseMap\3/g"\ + -e "s/\(\W\)\([sS]\)tdMap$/\1\2parseMap/g"\ + -e "s/^\([sS]\)tdMap\(\W\)/\1parseMap\2/g"\ + -e "s/^\([sS]\)tdMap$/\1parseMap/g"\ + -e "s/\(\W\)\([Ff]\)unctorMap\(\W\)/\1\2unctorToMap\3/g"\ + -e "s/\(\W\)\([Ff]\)unctorMap$/\1\2unctorToMap/g"\ + -e "s/^\([Ff]\)unctorMap\(\W\)/\1unctorToMap\2/g"\ + -e "s/^\([Ff]\)unctorMap$/\1unctorToMap/g"\ + -e "s/\(\W\)\([Mm]\)apFunctor\(\W\)/\1\2apToFunctor\3/g"\ + -e "s/\(\W\)\([Mm]\)apFunctor$/\1\2apToFunctor/g"\ + -e "s/^\([Mm]\)apFunctor\(\W\)/\1apToFunctor\2/g"\ + -e "s/^\([Mm]\)apFunctor$/\1apToFunctor/g"\ + -e "s/\(\W\)\([Ff]\)orkWriteMap\(\W\)/\1\2orkMap\3/g"\ + -e "s/\(\W\)\([Ff]\)orkWriteMap$/\1\2orkMap/g"\ + -e "s/^\([Ff]\)orkWriteMap\(\W\)/\1orkMap\2/g"\ + -e "s/^\([Ff]\)orkWriteMap$/\1orkMap/g"\ + -e "s/\(\W\)StoreBoolMap\(\W\)/\1LoggerBoolMap\2/g"\ + -e "s/\(\W\)StoreBoolMap$/\1LoggerBoolMap/g"\ + -e "s/^StoreBoolMap\(\W\)/LoggerBoolMap\1/g"\ + -e "s/^StoreBoolMap$/LoggerBoolMap/g"\ + -e "s/\(\W\)storeBoolMap\(\W\)/\1loggerBoolMap\2/g"\ + -e "s/\(\W\)storeBoolMap$/\1loggerBoolMap/g"\ + -e "s/^storeBoolMap\(\W\)/loggerBoolMap\1/g"\ + -e "s/^storeBoolMap$/loggerBoolMap/g"\ + -e "s/\(\W\)BoundingBox\(\W\)/\1Box\2/g"\ + -e "s/\(\W\)BoundingBox$/\1Box/g"\ + -e "s/^BoundingBox\(\W\)/Box\1/g"\ + -e "s/^BoundingBox$/Box/g"\ +<$1 > $TMP + +mv $TMP $1 \ No newline at end of file