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