001/* Copyright (C) 2013 TU Dortmund
002 * This file is part of AutomataLib, http://www.automatalib.net/.
003 * 
004 * AutomataLib is free software; you can redistribute it and/or
005 * modify it under the terms of the GNU Lesser General Public
006 * License version 3.0 as published by the Free Software Foundation.
007 * 
008 * AutomataLib is distributed in the hope that it will be useful,
009 * but WITHOUT ANY WARRANTY; without even the implied warranty of
010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
011 * Lesser General Public License for more details.
012 * 
013 * You should have received a copy of the GNU Lesser General Public
014 * License along with AutomataLib; if not, see
015 * http://www.gnu.de/documents/lgpl.en.html.
016 */
017package net.automatalib.graphs.dot;
018
019import java.io.IOException;
020import java.util.Map;
021
022import net.automatalib.commons.util.mappings.Mapping;
023
024/**
025 * Helper interface for plotting graphs using the GraphVIZ DOT format.
026 * 
027 * @author Malte Isberner <malte.isberner@gmail.com>
028 *
029 * @param <N> node class
030 * @param <E> edge class
031 */
032public interface GraphDOTHelper<N, E> {
033        
034        public static final String LABEL = "label";
035        public static final String SHAPE = "shape";
036        
037        
038        /**
039         * Called before the node and edge data are written, but <i>after</i>
040         * the opening "digraph {" statement.
041         * @param a the {@link Appendable} to write to
042         * @throws IOException if writing to <tt>a</tt> throws. 
043         */
044        public void writePreamble(Appendable a) throws IOException;
045        
046        /**
047         * Called after the node and edge data are written, but <i>before</i>
048         * the closing brace.
049         * @param a the {@link Appendable} to write to
050         * @throws IOException if writing to <tt>a</tt> throws.
051         */
052        public void writePostamble(Mapping<N,String> identifiers, Appendable a) throws IOException;
053        
054        /**
055         * Retrieves the GraphVIZ properties for rendering a single node. Additionally,
056         * the return value allows to control whether or not to omit this node from
057         * rendering. If <tt>false</tt> is returned, the node will not be rendered.
058         * Consequently, any modifications to the properties map will have no effect.
059         * 
060         * The properties are stored in the {@link Map} argument. Note that if an implementation
061         * of a base class is overridden, it is probably a good idea to call
062         * <tt>super.getNodeProperties(node, properties);</tt> at the beginning of
063         * the method.
064         * 
065         * @param node the node to be rendered
066         * @param properties the property map
067         * @return whether or not this node should be rendered
068         */
069        public boolean getNodeProperties(N node, Map<String,String> properties);
070        
071        /**
072         * Retrieves the GraphVIZ properties for rendering a single edge. Additionally,
073         * the return value allows to control whether or not to omit this edge from
074         * rendering. If <tt>false</tt> is returned, the edge will not be rendered.
075         * Consequently, any modifications to the properties map will have no effect.
076         * 
077         * The properties are stored in the {@link Map} argument. Note that if an implementation
078         * of a base class is overridden, it is probably a good idea to call
079         * <tt>super.getEdgeProperties(node, properties);</tt> at the beginning of
080         * the method.
081         * 
082         * @param edge the edge to be rendered
083         * @param properties the property map
084         * @return whether or not this edge should be rendered
085         */
086        public boolean getEdgeProperties(N src, E edge, N tgt, Map<String,String> properties);
087}