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 "config.h"
  24
  25 #include "dconf-paths.h"
  26
  27 #include "dconf-error.h"
  28
  29 /**
  30  * SECTION:paths
  31  * @title: dconf Paths
  32  * @short_description: utility functions to validate dconf paths
  33  *
  34  * Various places in the dconf API speak of "paths", "keys", "dirs" and
  35  * relative versions of each of these.  This file contains functions to
  36  * check if a given string is a valid member of each of these classes
  37  * and to report errors when a string is not.
  38  *
  39  * See each function in this section for a precise description of what
  40  * makes a string a valid member of a given class.
  41  **/
  42
  43 #define vars gchar c, l
  44
  45 #define nonnull \
  46   if (string == NULL) {                                                 \
  47     g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                  \
  48                  "%s not specified", type);                             \
  49     return FALSE;                                                       \
  50   }
  51
  52
  53 #define absolute \
  54   if ((l = *string++) != '/')                                           \
  55     {                                                                   \
  56       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  57                    "dconf %s must begin with a slash", type);           \
  58       return FALSE;                                                     \
  59     }
  60
  61 #define relative \
  62   if (*string == '/')                                                   \
  63     {                                                                   \
  64       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  65                    "dconf %s must not begin with a slash", type);       \
  66       return FALSE;                                                     \
  67     }                                                                   \
  68   l = '/'
  69
  70 #define no_double_slash \
  71   while ((c = *string++))                                               \
  72     {                                                                   \
  73       if (c == '/' && l == '/')                                         \
  74         {                                                               \
  75           g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,            \
  76                        "dconf %s must not contain two "                 \
  77                        "consecutive slashes", type);                    \
  78           return FALSE;                                                 \
  79         }                                                               \
  80       l = c;                                                            \
  81     }                                                                   \
  82
  83 #define path \
  84   return TRUE
  85
  86 #define key \
  87   if (l == '/')                                                         \
  88     {                                                                   \
  89       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  90                    "dconf %s must not end with a slash", type);         \
  91       return FALSE;                                                     \
  92     }                                                                   \
  93   return TRUE
  94
  95 #define dir \
  96   if (l != '/')                                                         \
  97     {                                                                   \
  98       g_set_error (error, DCONF_ERROR, DCONF_ERROR_PATH,                \
  99                    "dconf %s must end with a slash", type);             \
 100       return FALSE;                                                     \
 101     }                                                                   \
 102   return TRUE
 103
 104
 105
 106 /**
 107  * dconf_is_path:
 108  * @string: a string
 109  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 110  *
 111  * Checks if @string is a valid dconf path.  dconf keys must start with
 112  * '/' and not contain '//'.
 113  *
 114  * A dconf path may be either a key or a dir.  See dconf_is_key() and
 115  * dconf_is_dir() for examples of each.
 116  *
 117  * Returns: %TRUE if @string is a path
 118  **/
 119 gboolean
 120 dconf_is_path (const gchar  *string,
 121                GError      **error)
 122 {
 123 #define type "path"
 124   vars; nonnull; absolute; no_double_slash; path;
 125 #undef type
 126 }
 127
 128 /**
 129  * dconf_is_key:
 130  * @string: a string
 131  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 132  *
 133  * Checks if @string is a valid dconf key.  dconf keys must start with
 134  * '/', not contain '//' and not end with '/'.
 135  *
 136  * A dconf key is the potential location of a single value within the
 137  * database.
 138  *
 139  * "/a", "/a/b" and "/a/b/c" are examples of keys.  "", "/", "a", "a/b",
 140  * "//a/b", "/a//b", and "/a/" are examples of strings that are not
 141  * keys.
 142  *
 143  * Returns: %TRUE if @string is a key
 144  **/
 145 gboolean
 146 dconf_is_key (const gchar *string,
 147               GError      **error)
 148 {
 149 #define type "key"
 150   vars; nonnull; absolute; no_double_slash; key;
 151 #undef type
 152 }
 153
 154 /**
 155  * dconf_is_dir:
 156  * @string: a string
 157  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 158  *
 159  * Checks if @string is a valid dconf dir.  dconf dirs must start and
 160  * end with '/' and not contain '//'.
 161  *
 162  * A dconf dir refers to a subtree of the database that can contain
 163  * other dirs or keys.  If @string is a dir, then it will be a prefix of
 164  * any key or dir contained within it.
 165  *
 166  * "/", "/a/" and "/a/b/" are examples of dirs.  "", "a/", "a/b/",
 167  * "//a/b/", "/a//b/" and "/a" are examples of strings that are not
 168  * dirs.
 169  *
 170  * Returns: %TRUE if @string is a dir
 171  **/
 172 gboolean
 173 dconf_is_dir (const gchar  *string,
 174               GError      **error)
 175 {
 176 #define type "dir"
 177   vars; nonnull; absolute; no_double_slash; dir;
 178 #undef type
 179 }
 180
 181 /**
 182  * dconf_is_rel_path:
 183  * @string: a string
 184  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 185  *
 186  * Checks if @string is a valid dconf relative path.  A relative path is
 187  * a string that, when concatenated to a dir, forms a valid dconf path.
 188  * This means that a rel must not start with a '/' or contain '//'.
 189  *
 190  * A dconf rel may be either a relative key or a relative dir.  See
 191  * dconf_is_rel_key() and dconf_is_rel_dir() for examples of each.
 192  *
 193  * Returns: %TRUE if @string is a relative path
 194  **/
 195 gboolean
 196 dconf_is_rel_path (const gchar  *string,
 197                    GError      **error)
 198 {
 199 #define type "relative path"
 200   vars; nonnull; relative; no_double_slash; path;
 201 #undef type
 202 }
 203
 204
 205 /**
 206  * dconf_is_rel_key:
 207  * @string: a string
 208  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 209  *
 210  * Checks if @string is a valid dconf relative key.  A relative key is a
 211  * string that, when concatenated to a dir, forms a valid dconf key.
 212  * This means that a relative key must not start or end with a '/' or
 213  * contain '//'.
 214  *
 215  * "a", "a/b" and "a/b/c" are examples of relative keys.  "", "/", "/a",
 216  * "/a/b", "//a/b", "/a//b", and "a/" are examples of strings that are
 217  * not relative keys.
 218  *
 219  * Returns: %TRUE if @string is a relative key
 220  **/
 221 gboolean
 222 dconf_is_rel_key (const gchar  *string,
 223                   GError      **error)
 224 {
 225 #define type "relative key"
 226   vars; nonnull; relative; no_double_slash; key;
 227 #undef type
 228 }
 229
 230 /**
 231  * dconf_is_rel_dir:
 232  * @string: a string
 233  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 234  *
 235  * Checks if @string is a valid dconf relative dir.  A relative dir is a
 236  * string that, when appended to a dir, forms a valid dconf dir.  This
 237  * means that a relative dir must not start with a '/' or contain '//'
 238  * and must end with a '/' except in the case that it is the empty
 239  * string (in which case the path specified by appending the rel to a
 240  * directory is the original directory).
 241  *
 242  * "", "a/" and "a/b/" are examples of relative dirs.  "/", "/a/",
 243  * "/a/b/", "//a/b/", "a//b/" and "a" are examples of strings that are
 244  * not relative dirs.
 245  *
 246  * Returns: %TRUE if @string is a relative dir
 247  **/
 248 gboolean
 249 dconf_is_rel_dir (const gchar  *string,
 250                   GError      **error)
 251 {
 252 #define type "relative dir"
 253   vars; nonnull; relative; no_double_slash; dir;
 254 #undef type
 255 }