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  * Returns: %TRUE if @string is a path
 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 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  * Returns: %TRUE if @string is a key
 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 gboolean
 143 dconf_is_key (const gchar *string,
 144               GError      **error)
 145 {
 146 #define type "key"
 147   vars; nonnull; absolute; no_double_slash; key;
 148 #undef type
 149 }
 150
 151 /**
 152  * dconf_is_dir:
 153  * @string: a string
 154  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 155  * Returns: %TRUE if @string is a dir
 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 gboolean
 169 dconf_is_dir (const gchar  *string,
 170               GError      **error)
 171 {
 172 #define type "dir"
 173   vars; nonnull; absolute; no_double_slash; dir;
 174 #undef type
 175 }
 176
 177 /**
 178  * dconf_is_rel:
 179  * @string: a string
 180  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 181  * Returns: %TRUE if @string is a relative path
 182  *
 183  * Checks if @string is a valid dconf relative path.  A relative path is
 184  * a string that, when concatenated to a dir, forms a valid dconf path.
 185  * This means that a rel must not start with a '/' or contain '//'.
 186  *
 187  * A dconf rel may be either a relative key or a relative dir.  See
 188  * dconf_is_rel_key() and dconf_is_rel_dir() for examples of each.
 189  **/
 190 gboolean
 191 dconf_is_rel (const gchar  *string,
 192               GError      **error)
 193 {
 194 #define type "relative path"
 195   vars; nonnull; relative; no_double_slash; path;
 196 #undef type
 197 }
 198
 199
 200 /**
 201  * dconf_is_rel_key:
 202  * @string: a string
 203  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 204  * Returns: %TRUE if @string is a relative key
 205  *
 206  * Checks if @string is a valid dconf relative key.  A relative key is a
 207  * string that, when concatenated to a dir, forms a valid dconf key.
 208  * This means that a relative key must not start or end with a '/' or
 209  * contain '//'.
 210  *
 211  * "a", "a/b" and "a/b/c" are examples of relative keys.  "", "/", "/a",
 212  * "/a/b", "//a/b", "/a//b", and "a/" are examples of strings that are
 213  * not relative keys.
 214  **/
 215 gboolean
 216 dconf_is_rel_key (const gchar  *string,
 217                   GError      **error)
 218 {
 219 #define type "relative key"
 220   vars; nonnull; relative; no_double_slash; key;
 221 #undef type
 222 }
 223
 224 /**
 225  * dconf_is_rel_dir:
 226  * @string: a string
 227  * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned
 228  * Returns: %TRUE if @string is a relative dir
 229  *
 230  * Checks if @string is a valid dconf relative dir.  A relative dir is a
 231  * string that, when appended to a dir, forms a valid dconf dir.  This
 232  * means that a relative dir must not start with a '/' or contain '//'
 233  * and must end with a '/' except in the case that it is the empty
 234  * string (in which case the path specified by appending the rel to a
 235  * directory is the original directory).
 236  *
 237  * "", "a/" and "a/b/" are examples of relative dirs.  "/", "/a/",
 238  * "/a/b/", "//a/b/", "a//b/" and "a" are examples of strings that are
 239  * not relative dirs.
 240  **/
 241 gboolean
 242 dconf_is_rel_dir (const gchar  *string,
 243                   GError      **error)
 244 {
 245 #define type "relative dir"
 246   vars; nonnull; relative; no_double_slash; dir;
 247 #undef type
 248 }