Sanitise incoming GAL config options using mapping tables

When reading config options from files, it's important to make sure the
value makes sense - the incoming data could be anything, and may have
incompatible values or be otherwise unreliable.

This introduces a simple way to define and use "mapping tables" which
can map between a "native" value, probably an enum (but not necessarily)
and some external value, for example the value written to file.

This provides a decoupling between the two values, as well as sanitising
inputs and outputs. This is important, as over time, if there isn't a
decoupled interface, changing options result in corrupt configs, or a
proliferation of obsolete enum values kept for compatibility.

common/gal/gal_display_options.cpp

@@ -1,7 +1,7 @@
 /*
 * This program source code file is part of KICAD, a free EDA CAD application.
 *
-* Copyright (C) 2016 Kicad Developers, see change_log.txt for contributors.
+* Copyright (C) 2016-2017 Kicad Developers, see change_log.txt for contributors.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
@@ -24,6 +24,8 @@
 #include <gal/gal_display_options.h>
 #include <wx/config.h>
 
+#include <config_map.h>
+
 using namespace KIGFX;
 
 /*
@@ -35,6 +37,23 @@ static const wxString GalGridLineWidthConfig( "GridLineWidth" );
 static const wxString GalGridMaxDensityConfig( "GridMaxDensity" );
 
 
+static const UTIL::CFG_MAP<KIGFX::OPENGL_ANTIALIASING_MODE> aaModeConfigVals =
+{
+    { KIGFX::OPENGL_ANTIALIASING_MODE::NONE,                0 },
+    { KIGFX::OPENGL_ANTIALIASING_MODE::SUBSAMPLE_HIGH,      1 },
+    { KIGFX::OPENGL_ANTIALIASING_MODE::SUBSAMPLE_ULTRA,     2 },
+    { KIGFX::OPENGL_ANTIALIASING_MODE::SUPERSAMPLING_X2,    3 },
+    { KIGFX::OPENGL_ANTIALIASING_MODE::SUPERSAMPLING_X4,    4 },
+};
+
+
+static const UTIL::CFG_MAP<KIGFX::GRID_STYLE> gridStyleConfigVals =
+{
+    { KIGFX::GRID_STYLE::DOTS,       0 },
+    { KIGFX::GRID_STYLE::LINES,      1 },
+};
+
+
 GAL_DISPLAY_OPTIONS::GAL_DISPLAY_OPTIONS()
     : gl_antialiasing_mode( OPENGL_ANTIALIASING_MODE::NONE ),
       m_gridStyle( GRID_STYLE::DOTS )
@@ -43,13 +62,15 @@ GAL_DISPLAY_OPTIONS::GAL_DISPLAY_OPTIONS()
 
 void GAL_DISPLAY_OPTIONS::ReadConfig( wxConfigBase* aCfg, wxString aBaseName )
 {
-    aCfg->Read( aBaseName + GalGLAntialiasingKeyword,
-                reinterpret_cast<long*>( &gl_antialiasing_mode ),
-                static_cast<long>( KIGFX::OPENGL_ANTIALIASING_MODE::NONE ) );
+    long readLong; // Temp value buffer
 
-    aCfg->Read( aBaseName + GalGridStyleConfig,
-                reinterpret_cast<long*>( &m_gridStyle ),
+    aCfg->Read( aBaseName + GalGLAntialiasingKeyword, &readLong,
+                static_cast<long>( KIGFX::OPENGL_ANTIALIASING_MODE::NONE ) );
+    gl_antialiasing_mode = UTIL::GetValFromConfig( aaModeConfigVals, readLong );
+
+    aCfg->Read( aBaseName + GalGridStyleConfig, &readLong,
                 static_cast<long>( KIGFX::GRID_STYLE::DOTS ) );
+    m_gridStyle = UTIL::GetValFromConfig( gridStyleConfigVals, readLong );
 
     aCfg->Read( aBaseName + GalGridLineWidthConfig,
                 &m_gridLineWidth, 0.5 );
@@ -64,10 +85,10 @@ void GAL_DISPLAY_OPTIONS::ReadConfig( wxConfigBase* aCfg, wxString aBaseName )
 void GAL_DISPLAY_OPTIONS::WriteConfig( wxConfigBase* aCfg, wxString aBaseName )
 {
     aCfg->Write( aBaseName + GalGLAntialiasingKeyword,
-                 static_cast<long>( gl_antialiasing_mode ) );
+                 UTIL::GetConfigForVal( aaModeConfigVals, gl_antialiasing_mode ) );
 
     aCfg->Write( aBaseName + GalGridStyleConfig,
-                 static_cast<long>( m_gridStyle ) );
+                 UTIL::GetConfigForVal( gridStyleConfigVals, m_gridStyle ) );
 
     aCfg->Write( aBaseName + GalGridLineWidthConfig,
                  m_gridLineWidth );

include/config_map.h

@@ -0,0 +1,116 @@
+/*
+ * This program source code file is part of KiCad, a free EDA CAD application.
+ *
+ * Copyright (C) 2017 Kicad Developers, see change_log.txt for contributors.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * 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.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, you may find one here:
+ * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * or you may search the http://www.gnu.org website for the version 2 license,
+ * or you may write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
+ */
+
+#ifndef CONFIG_MAP__H_
+#define CONFIG_MAP__H_
+
+#include <map>
+
+namespace UTIL
+{
+
+/**
+ * A config value table is a list of native values (usually enums)
+ * to a different set of values, for example, the values used to
+ * represent the enum in a config file, or the index used to represent
+ * it in a selection list.
+ *
+ * It can be important to decouple from the internal representation,
+ * especially in the case of persistent config files, as adding,
+ * removing or modifying the order of items internally can easily
+ * result in configs being read incorrectly, and, even if otherwise
+ * carefully managed, results in obsolete values being kept in enums
+ * as placeholders.
+ *
+ * The first item in the list is used default if no matching value is
+ * found during lookup.
+ */
+template<typename T>
+using CFG_MAP = std::vector<std::pair<T, long> >;
+
+/**
+ * The "native" type of a CFG_MAP: probably an enum type
+ */
+template<typename MAP>
+using CFG_NATIVE_VAL = typename MAP::value_type::first_type;
+
+
+/**
+ * Get the mapped config value (the one to write to file, or use in
+ * an index) from the given native (probably enum) value.
+ *
+ * The default (first item) is returned if the value is not found
+ * in the list.
+ *
+ * @param aMap the value-config mapping table
+ * @param aVal the value to look up
+ */
+template<typename MAP>
+static long GetConfigForVal( const MAP& aMap, CFG_NATIVE_VAL<MAP> aVal )
+{
+    // default is first entry
+    long aConf = aMap[0].second;
+
+    for( const auto& mapping : aMap )
+    {
+        if( mapping.first == aVal )
+        {
+            aConf = mapping.second;
+            break;
+        }
+    }
+
+    return aConf;
+}
+
+/**
+ * Get the native value corresponding to the config value
+ * (read from file or UI, probably) and find it in the mapping table.
+ *
+ * The default item is returned if the mapping fails.
+ *
+ * @param aMap the value-config mapping table
+ * @param aVal the config value to look up
+ */
+template<typename MAP>
+static CFG_NATIVE_VAL<MAP> GetValFromConfig(
+        const MAP& aMap, long aConf )
+{
+    // default is first entry
+    CFG_NATIVE_VAL<MAP> aVal = aMap[0].first;
+
+    for( const auto& mapping : aMap )
+    {
+        if( mapping.second == aConf )
+        {
+            aVal = mapping.first;
+            break;
+        }
+    }
+
+    return aVal;
+}
+
+}
+
+#endif /* CONFIG_MAP__H_ */

include/gal/gal_display_options.h

@@ -40,13 +40,13 @@ namespace KIGFX
         DOTS     ///< Use dots for the grid
     };
 
-    enum class OPENGL_ANTIALIASING_MODE : long
+    enum class OPENGL_ANTIALIASING_MODE
     {
-        NONE = 0,
-        SUBSAMPLE_HIGH = 1,
-        SUBSAMPLE_ULTRA = 2,
-        SUPERSAMPLING_X2 = 3,
-        SUPERSAMPLING_X4 = 4
+        NONE,
+        SUBSAMPLE_HIGH,
+        SUBSAMPLE_ULTRA,
+        SUPERSAMPLING_X2,
+        SUPERSAMPLING_X4,
     };
 
     class GAL_DISPLAY_OPTIONS;