common/dconf-paths.c

   1 /*
   2  * Copyright © 2008-2009 Ryan Lortie
   3  * Copyright © 2010 Codethink Limited
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the licence, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Ryan Lortie <desrt@desrt.ca>
  21  */
  22
  23 #include "dconf-paths.h"
  24
  25 /**
  26  * SECTION:paths
  27  * @title: DConf Paths
  28  * @short_description: utility functions to validate dconf paths
  29  *
  30  * Various places in the dconf API speak of "paths", "keys", "dirs" and
  31  * relative versions of each of these.  This file contains functions to
  32  * check if a given string is a valid member of each of these classes
  33  * and to report errors when a string is not.
  34  *
  35  * See each function in this section for a precise description of what
  36  * makes a string a valid member of a given class.
  37  **/
  38
  39 #define vars gchar c, l
  40
  41 #define DCONF_ERROR 0
  42 #define DCONF_ERROR_PATH 0
  43
  44 #define nonnull \
  45   if (string == NULL) {                                                 \
  46     g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                  \
  47                  "%s not specified", type);                             \
  48     return FALSE;                                                       \
  49   }
  50
  51
  52 #define absolute \
  53   if ((l = *string++) != '/')                                           \
  54     {                                                                   \
  55       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  56                    "dconf %s must begin with a slash", type);           \
  57       return FALSE;                                                     \
  58     }
  59
  60 #define relative \
  61   if (*string == '/')                                                   \
  62     {                                                                   \
  63       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  64                    "dconf %s must not begin with a slash", type);       \
  65       return FALSE;                                                     \
  66     }                                                                   \
  67   l = '/'
  68
  69 #define no_double_slash \
  70   while ((c = *string++))                                               \
  71     {                                                                   \
  72       if (c == '/' && l == '/')                                         \
  73         {                                                               \
  74           g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,            \
  75                        "dconf %s must not contain two "                 \
  76                        "consecutive slashes", type);                    \
  77           return FALSE;                                                 \
  78         }                                                               \
  79       l = c;                                                            \
  80     }                                                                   \
  81
  82 #define path \
  83   return TRUE
  84
  85 #define key \
  86   if (l == '/')                                                         \
  87     {                                                                   \
  88       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  89                    "dconf %s must not end with a slash", type);         \
  90       return FALSE;                                                     \
  91     }                                                                   \
  92   return TRUE
  93
  94 #define dir \
  95   if (l != '/')                                                         \
  96     {                                                                   \
  97       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  98                    "dconf %s must end with a slash", type);             \
  99       return FALSE;                                                     \
 100     }                                                                   \
 101   return TRUE
 102
 103
 104
 105 /**
 106  * dconf_is_path:
 107  * @string: a string
 108  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 109  *
 110  * Checks if @string is a valid dconf path.  dconf keys must start with
 111  * '/' and not contain '//'.
 112  *
 113  * A dconf path may be either a key or a dir.  See dconf_is_key() and
 114  * dconf_is_dir() for examples of each.
 115  *
 116  * Returns: %TRUE if @string is a path
 117  **/
 118 gboolean
 119 dconf_is_path (const gchar  *string,
 120                GError      **error)
 121 {
 122 #define type "path"
 123   vars; nonnull; absolute; no_double_slash; path;
 124 #undef type
 125 }
 126
 127 /**
 128  * dconf_is_key:
 129  * @string: a string
 130  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 131  *
 132  * Checks if @string is a valid dconf key.  dconf keys must start with
 133  * '/', not contain '//' and not end with '/'.
 134  *
 135  * A dconf key is the potential location of a single value within the
 136  * database.
 137  *
 138  * "/a", "/a/b" and "/a/b/c" are examples of keys.  "", "/", "a", "a/b",
 139  * "//a/b", "/a//b", and "/a/" are examples of strings that are not
 140  * keys.
 141  *
 142  * Returns: %TRUE if @string is a key
 143  **/
 144 gboolean
 145 dconf_is_key (const gchar *string,
 146               GError      **error)
 147 {
 148 #define type "key"
 149   vars; nonnull; absolute; no_double_slash; key;
 150 #undef type
 151 }
 152
 153 /**
 154  * dconf_is_dir:
 155  * @string: a string
 156  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 157  *
 158  * Checks if @string is a valid dconf dir.  dconf dirs must start and
 159  * end with '/' and not contain '//'.
 160  *
 161  * A dconf dir refers to a subtree of the database that can contain
 162  * other dirs or keys.  If @string is a dir, then it will be a prefix of
 163  * any key or dir contained within it.
 164  *
 165  * "/", "/a/" and "/a/b/" are examples of dirs.  "", "a/", "a/b/",
 166  * "//a/b/", "/a//b/" and "/a" are examples of strings that are not
 167  * dirs.
 168  *
 169  * Returns: %TRUE if @string is a dir
 170  **/
 171 gboolean
 172 dconf_is_dir (const gchar  *string,
 173               GError      **error)
 174 {
 175 #define type "dir"
 176   vars; nonnull; absolute; no_double_slash; dir;
 177 #undef type
 178 }
 179
 180 /**
 181  * dconf_is_rel_path:
 182  * @string: a string
 183  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 184  *
 185  * Checks if @string is a valid dconf relative path.  A relative path is
 186  * a string that, when concatenated to a dir, forms a valid dconf path.
 187  * This means that a rel must not start with a '/' or contain '//'.
 188  *
 189  * A dconf rel may be either a relative key or a relative dir.  See
 190  * dconf_is_rel_key() and dconf_is_rel_dir() for examples of each.
 191  *
 192  * Returns: %TRUE if @string is a relative path
 193  **/
 194 gboolean
 195 dconf_is_rel_path (const gchar  *string,
 196                    GError      **error)
 197 {
 198 #define type "relative path"
 199   vars; nonnull; relative; no_double_slash; path;
 200 #undef type
 201 }
 202
 203
 204 /**
 205  * dconf_is_rel_key:
 206  * @string: a string
 207  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 208  *
 209  * Checks if @string is a valid dconf relative key.  A relative key is a
 210  * string that, when concatenated to a dir, forms a valid dconf key.
 211  * This means that a relative key must not start or end with a '/' or
 212  * contain '//'.
 213  *
 214  * "a", "a/b" and "a/b/c" are examples of relative keys.  "", "/", "/a",
 215  * "/a/b", "//a/b", "/a//b", and "a/" are examples of strings that are
 216  * not relative keys.
 217  *
 218  * Returns: %TRUE if @string is a relative key
 219  **/
 220 gboolean
 221 dconf_is_rel_key (const gchar  *string,
 222                   GError      **error)
 223 {
 224 #define type "relative key"
 225   vars; nonnull; relative; no_double_slash; key;
 226 #undef type
 227 }
 228
 229 /**
 230  * dconf_is_rel_dir:
 231  * @string: a string
 232  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 233  *
 234  * Checks if @string is a valid dconf relative dir.  A relative dir is a
 235  * string that, when appended to a dir, forms a valid dconf dir.  This
 236  * means that a relative dir must not start with a '/' or contain '//'
 237  * and must end with a '/' except in the case that it is the empty
 238  * string (in which case the path specified by appending the rel to a
 239  * directory is the original directory).
 240  *
 241  * "", "a/" and "a/b/" are examples of relative dirs.  "/", "/a/",
 242  * "/a/b/", "//a/b/", "a//b/" and "a" are examples of strings that are
 243  * not relative dirs.
 244  *
 245  * Returns: %TRUE if @string is a relative dir
 246  **/
 247 gboolean
 248 dconf_is_rel_dir (const gchar  *string,
 249                   GError      **error)
 250 {
 251 #define type "relative dir"
 252   vars; nonnull; relative; no_double_slash; dir;
 253 #undef type
 254 }