subversion/include/svn_subst.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_subst.h
  19  * @brief Data substitution (keywords and EOL style)
  20  */
  21
  22
  23 \f
  24 #ifndef SVN_SUBST_H
  25 #define SVN_SUBST_H
  26
  27 #include "svn_types.h"
  28 #include "svn_string.h"
  29 #include "svn_io.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif /* __cplusplus */
  34
  35 /* EOL conversion and keyword expansion. */
  36
  37 /** Valid states for 'svn:eol-style' property.
  38  *
  39  * Property nonexistence is equivalent to 'none'.
  40  */
  41 typedef enum svn_subst_eol_style
  42 {
  43   /** An unrecognized style */
  44   svn_subst_eol_style_unknown,
  45
  46   /** EOL translation is "off" or ignored value */
  47   svn_subst_eol_style_none,
  48
  49   /** Translation is set to client's native eol */
  50   svn_subst_eol_style_native,
  51
  52   /** Translation is set to one of LF, CR, CRLF */
  53   svn_subst_eol_style_fixed
  54
  55 } svn_subst_eol_style_t;
  56
  57 /** Set @a *style to the appropriate @c svn_subst_eol_style_t and @a *eol to
  58  * the appropriate cstring for a given svn:eol-style property value.
  59  *
  60  * Set @a *eol to
  61  *
  62  *    - @c NULL for @c svn_subst_eol_style_none, or
  63  *
  64  *    - a NULL-terminated C string containing the native eol marker
  65  *      for this platform, for @c svn_subst_eol_style_native, or
  66  *
  67  *    - a NULL-terminated C string containing the eol marker indicated
  68  *      by the property value, for @c svn_subst_eol_style_fixed.
  69  *
  70  * If @a *style is NULL, it is ignored.
  71  */
  72 void
  73 svn_subst_eol_style_from_value(svn_subst_eol_style_t *style,
  74                                const char **eol,
  75                                const char *value);
  76
  77 /** Indicates whether the working copy and normalized versions of a file
  78  * with the given the parameters differ.  If @a force_eol_check is TRUE,
  79  * the routine also accounts for all translations required due to repairing
  80  * fixed eol styles.
  81  *
  82  * @since New in 1.4
  83  *
  84  */
  85 svn_boolean_t
  86 svn_subst_translation_required(svn_subst_eol_style_t style,
  87                                const char *eol,
  88                                apr_hash_t *keywords,
  89                                svn_boolean_t special,
  90                                svn_boolean_t force_eol_check);
  91
  92
  93 /** Values used in keyword expansion.
  94  *
  95  * @deprecated Provided for backward compatibility with the 1.2 API.
  96  */
  97 typedef struct svn_subst_keywords_t
  98 {
  99   /**
 100    * @name svn_subst_keywords_t fields
 101    * String expansion of the like-named keyword, or NULL if the keyword
 102    * was not selected in the svn:keywords property.
 103    * @{
 104    */
 105   const svn_string_t *revision;
 106   const svn_string_t *date;
 107   const svn_string_t *author;
 108   const svn_string_t *url;
 109   const svn_string_t *id;
 110   /** @} */
 111 } svn_subst_keywords_t;
 112
 113
 114 /**
 115  * Set @a *kw to a new keywords hash filled with the appropriate contents
 116  * given a @a keywords_string (the contents of the svn:keywords
 117  * property for the file in question), the revision @a rev, the @a url,
 118  * the @a date the file was committed on, and the @a author of the last
 119  * commit.  Any of these can be @c NULL to indicate that the information is
 120  * not present, or @c 0 for @a date.
 121  *
 122  * Hash keys are of type <tt>const char *</tt>.
 123  * Hash values are of type <tt>svn_string_t *</tt>.
 124  *
 125  * All memory is allocated out of @a pool.
 126  *
 127  * @since New in 1.3.
 128  */
 129 svn_error_t *
 130 svn_subst_build_keywords2(apr_hash_t **kw,
 131                           const char *keywords_string,
 132                           const char *rev,
 133                           const char *url,
 134                           apr_time_t date,
 135                           const char *author,
 136                           apr_pool_t *pool);
 137
 138 /** Similar to svn_subst_build_keywords2() except that it populates
 139  * an existing structure @a *kw instead of creating a keywords hash.
 140  *
 141  * @deprecated Provided for backward compatibility with the 1.2 API.
 142  */
 143 svn_error_t *
 144 svn_subst_build_keywords(svn_subst_keywords_t *kw,
 145                          const char *keywords_string,
 146                          const char *rev,
 147                          const char *url,
 148                          apr_time_t date,
 149                          const char *author,
 150                          apr_pool_t *pool);
 151
 152
 153 /** Return @c TRUE if @a a and @a b do not hold the same keywords.
 154  *
 155  * @a a and @a b are hashes of the form produced by
 156  * svn_subst_build_keywords2().
 157  *
 158  * @since New in 1.3.
 159  *
 160  * If @a compare_values is @c TRUE, "same" means that the @a a and @a b
 161  * contain exactly the same set of keywords, and the values of corresponding
 162  * keywords match as well.  Else if @a compare_values is @c FALSE, then
 163  * "same" merely means that @a a and @a b hold the same set of keywords,
 164  * although those keywords' values might differ.
 165  *
 166  * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is
 167  * equivalent to holding no keywords.
 168  */
 169 svn_boolean_t
 170 svn_subst_keywords_differ2(apr_hash_t *a,
 171                            apr_hash_t *b,
 172                            svn_boolean_t compare_values,
 173                            apr_pool_t *pool);
 174
 175 /** Similar to svn_subst_keywords_differ2() except that it compares
 176  * two @c svn_subst_keywords_t structs instead of keyword hashes.
 177  *
 178  * @deprecated Provided for backward compatibility with the 1.2 API.
 179  */
 180 svn_boolean_t
 181 svn_subst_keywords_differ(const svn_subst_keywords_t *a,
 182                           const svn_subst_keywords_t *b,
 183                           svn_boolean_t compare_values);
 184
 185
 186 /**
 187  * Copy and translate the data in stream @a src into stream @a dst.  It is
 188  * assumed that @a src is a readable stream and @a dst is a writable stream.
 189  *
 190  * @since New in 1.3.
 191  *
 192  * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to
 193  * denote line endings with @a eol_str in the output.  If @a src has an
 194  * inconsistent line ending style, then: if @a repair is @c FALSE, return
 195  * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any
 196  * line ending in @a src to @a eol_str in @a dst.  Recognized line endings are:
 197  * "\n", "\r", and "\r\n".
 198  *
 199  * Expand and contract keywords using the contents of @a keywords as the
 200  * new values.  If @a expand is @c TRUE, expand contracted keywords and
 201  * re-expand expanded keywords.  If @a expand is @c FALSE, contract expanded
 202  * keywords and ignore contracted ones.  Keywords not found in the hash are
 203  * ignored (not contracted or expanded).  If the @a keywords hash
 204  * itself is @c NULL, keyword substitution will be altogether ignored.
 205  *
 206  * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN
 207  * bytes, including the delimiters and the keyword itself.
 208  *
 209  * Note that a translation request is *required*:  one of @a eol_str or
 210  * @a keywords must be non-@c NULL.
 211  *
 212  * Recommendation: if @a expand is FALSE, then you don't care about the
 213  * keyword values, so use empty strings as non-NULL signifiers when you
 214  * build the keywords hash.
 215  *
 216  * Notes:
 217  *
 218  * See svn_wc__get_keywords() and svn_wc__get_eol_style() for a
 219  * convenient way to get @a eol_str and @a keywords if in libsvn_wc.
 220  */
 221 svn_error_t *
 222 svn_subst_translate_stream3(svn_stream_t *src,
 223                             svn_stream_t *dst,
 224                             const char *eol_str,
 225                             svn_boolean_t repair,
 226                             apr_hash_t *keywords,
 227                             svn_boolean_t expand,
 228                             apr_pool_t *pool);
 229
 230 /** Return a stream which performs eol translation and keyword
 231  * expansion when read from or written to.  The stream @a stream
 232  * is used to read and write all data.  Make sure you call
 233  * svn_stream_close() on @a stream to make sure all data are flushed
 234  * and cleaned up.
 235  *
 236  * Read operations from and write operations to the stream
 237  * perform the same operation: if @a expand is @c FALSE, both
 238  * contract keywords.  One stream supports both read and write
 239  * operations.  Reads and writes may be mixed.
 240  *
 241  * The stream returned is allocated in @a pool.
 242  *
 243  * @since New in 1.4.
 244  */
 245 svn_stream_t *
 246 svn_subst_stream_translated(svn_stream_t *stream,
 247                             const char *eol_str,
 248                             svn_boolean_t repair,
 249                             apr_hash_t *keywords,
 250                             svn_boolean_t expand,
 251                             apr_pool_t *pool);
 252
 253 /** Return a stream which performs eol translation and keyword
 254  * expansion when read from or written to.  The stream @a stream
 255  * is used to read and write all data.  Make sure you call
 256  * svn_stream_close() on @a stream to make sure all data are flushed
 257  * and cleaned up.
 258  *
 259  * Read and write operations perform the same transformation:
 260  * all data is translated to normal form.
 261  *
 262  * @see svn_subst_translate_to_normal_form()
 263  *
 264  * @since New in 1.5.
 265  */
 266 svn_error_t *
 267 svn_subst_stream_translated_to_normal_form(svn_stream_t **stream,
 268                                            svn_stream_t *source,
 269                                            svn_subst_eol_style_t eol_style,
 270                                            const char *eol_str,
 271                                            svn_boolean_t always_repair_eols,
 272                                            apr_hash_t *keywords,
 273                                            apr_pool_t *pool);
 274
 275
 276 /** Returns a stream which translates the special file at @a path to
 277  * the internal representation for special files when read from.  When
 278  * written to, it does the reverse: creating a special file when the
 279  * stream is closed.
 280  *
 281  * @since New in 1.5.
 282  */
 283 svn_error_t *
 284 svn_subst_stream_from_specialfile(svn_stream_t **stream,
 285                                   const char *path,
 286                                   apr_pool_t *pool);
 287
 288
 289 /** Similar to svn_subst_translate_stream3() except relies upon a
 290  * @c svn_subst_keywords_t struct instead of a hash for the keywords.
 291  *
 292  * @deprecated Provided for backward compatibility with the 1.2 API.
 293  */
 294 svn_error_t *
 295 svn_subst_translate_stream2(svn_stream_t *src,
 296                             svn_stream_t *dst,
 297                             const char *eol_str,
 298                             svn_boolean_t repair,
 299                             const svn_subst_keywords_t *keywords,
 300                             svn_boolean_t expand,
 301                             apr_pool_t *pool);
 302
 303
 304 /**
 305  * Same as svn_subst_translate_stream2(), but does not take a @a pool
 306  * argument, instead creates a temporary subpool of the global pool, and
 307  * destroys it before returning.
 308  *
 309  * @deprecated Provided for backward compatibility with the 1.1 API.
 310  */
 311 svn_error_t *
 312 svn_subst_translate_stream(svn_stream_t *src,
 313                            svn_stream_t *dst,
 314                            const char *eol_str,
 315                            svn_boolean_t repair,
 316                            const svn_subst_keywords_t *keywords,
 317                            svn_boolean_t expand);
 318
 319
 320 /**
 321  * Translates the file at path @a src into a file at path @a dst.  The
 322  * parameters @a *eol_str, @a repair, @a *keywords and @a expand are
 323  * defined the same as in svn_subst_translate_stream3().
 324  *
 325  * In addition, it will create a special file from normal form or
 326  * translate one to normal form if @a special is @c TRUE.
 327  *
 328  * Copy the contents of file-path @a src to file-path @a dst atomically,
 329  * either creating @a dst (or overwriting @a dst if it exists), possibly
 330  * performing line ending and keyword translations.
 331  *
 332  * If anything goes wrong during the copy, attempt to delete @a dst (if
 333  * it exists).
 334  *
 335  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
 336  * copy.
 337  *
 338  * @since New in 1.3.
 339  */
 340 svn_error_t *
 341 svn_subst_copy_and_translate3(const char *src,
 342                               const char *dst,
 343                               const char *eol_str,
 344                               svn_boolean_t repair,
 345                               apr_hash_t *keywords,
 346                               svn_boolean_t expand,
 347                               svn_boolean_t special,
 348                               apr_pool_t *pool);
 349
 350 /**
 351  * Similar to svn_subst_copy_and_translate3() except that @a keywords is a
 352  * @c svn_subst_keywords_t struct instead of a keywords hash.
 353  *
 354  * @deprecated Provided for backward compatibility with the 1.2 API.
 355  * @since New in 1.1.
 356  */
 357 svn_error_t *
 358 svn_subst_copy_and_translate2(const char *src,
 359                               const char *dst,
 360                               const char *eol_str,
 361                               svn_boolean_t repair,
 362                               const svn_subst_keywords_t *keywords,
 363                               svn_boolean_t expand,
 364                               svn_boolean_t special,
 365                               apr_pool_t *pool);
 366
 367 /**
 368  * Similar to svn_subst_copy_and_translate2() except that @a special is
 369  * always set to @c FALSE.
 370  *
 371  * @deprecated Provided for backward compatibility with the 1.0 API.
 372  */
 373 svn_error_t *
 374 svn_subst_copy_and_translate(const char *src,
 375                              const char *dst,
 376                              const char *eol_str,
 377                              svn_boolean_t repair,
 378                              const svn_subst_keywords_t *keywords,
 379                              svn_boolean_t expand,
 380                              apr_pool_t *pool);
 381
 382
 383 /**
 384  * Convenience routine: a variant of svn_subst_translate_stream3() which
 385  * operates on cstrings.
 386  *
 387  * @since New in 1.3.
 388  *
 389  * Return a new string in @a *dst, allocated in @a pool, by copying the
 390  * contents of string @a src, possibly performing line ending and keyword
 391  * translations.
 392  *
 393  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
 394  * copy.
 395  */
 396 svn_error_t *
 397 svn_subst_translate_cstring2(const char *src,
 398                              const char **dst,
 399                              const char *eol_str,
 400                              svn_boolean_t repair,
 401                              apr_hash_t *keywords,
 402                              svn_boolean_t expand,
 403                              apr_pool_t *pool);
 404
 405 /**
 406  * Similar to svn_subst_translate_cstring2() except that @a keywords is a
 407  * @c svn_subst_keywords_t struct instead of a keywords hash.
 408  *
 409  * @deprecated Provided for backward compatibility with the 1.2 API.
 410  */
 411 svn_error_t *
 412 svn_subst_translate_cstring(const char *src,
 413                             const char **dst,
 414                             const char *eol_str,
 415                             svn_boolean_t repair,
 416                             const svn_subst_keywords_t *keywords,
 417                             svn_boolean_t expand,
 418                             apr_pool_t *pool);
 419
 420 /**
 421  * Translates a file @a src in working copy form to a file @a dst in
 422  * normal form.
 423  *
 424  * The values specified for @a eol_style, @a *eol_str, @a keywords and
 425  * @a special, should be the ones used to translate the file to its
 426  * working copy form.  Usually, these are the values specified by the
 427  * user in the files' properties.
 428  *
 429  * Inconsistent line endings in the file will be automatically repaired
 430  * (made consistent) for some eol styles.  For all others, an error is
 431  * returned.  By setting @a always_repair_eols to @c TRUE, eols will be
 432  * made consistent even for those styles which don't have it by default.
 433  *
 434  * @note To translate a file FROM normal form, use
 435  *       svn_subst_copy_and_translate3().
 436  *
 437  * @since New in 1.4
 438  *
 439  */
 440 svn_error_t *
 441 svn_subst_translate_to_normal_form(const char *src,
 442                                    const char *dst,
 443                                    svn_subst_eol_style_t eol_style,
 444                                    const char *eol_str,
 445                                    svn_boolean_t always_repair_eols,
 446                                    apr_hash_t *keywords,
 447                                    svn_boolean_t special,
 448                                    apr_pool_t *pool);
 449
 450 /**
 451  * Set @a *stream_p to a stream that detranslates the file @a src from
 452  * working copy form to normal form, allocated in @a pool.
 453  *
 454  * The values specified for @a eol_style, @a *eol_str, @a keywords and
 455  * @a special, should be the ones used to translate the file to its
 456  * working copy form.  Usually, these are the values specified by the
 457  * user in the files' properties.
 458  *
 459  * Inconsistent line endings in the file will be automatically repaired
 460  * (made consistent) for some eol styles.  For all others, an error is
 461  * returned.  By setting @a always_repair_eols to @c TRUE, eols will be
 462  * made consistent even for those styles which don't have it by default.
 463  *
 464  * @since New in 1.4.
 465  *
 466  */
 467 svn_error_t *
 468 svn_subst_stream_detranslated(svn_stream_t **stream_p,
 469                               const char *src,
 470                               svn_subst_eol_style_t eol_style,
 471                               const char *eol_str,
 472                               svn_boolean_t always_repair_eols,
 473                               apr_hash_t *keywords,
 474                               svn_boolean_t special,
 475                               apr_pool_t *pool);
 476
 477 \f
 478 /* EOL conversion and character encodings */
 479
 480 /** Translate the data in @a value (assumed to be in encoded in charset
 481  * @a encoding) to UTF8 and LF line-endings.  If @a encoding is @c NULL,
 482  * then assume that @a value is in the system-default language encoding.
 483  * Return the translated data in @a *new_value, allocated in @a pool.
 484  */
 485 svn_error_t *svn_subst_translate_string(svn_string_t **new_value,
 486                                         const svn_string_t *value,
 487                                         const char *encoding,
 488                                         apr_pool_t *pool);
 489
 490 /** Translate the data in @a value from UTF8 and LF line-endings into
 491  * native locale and native line-endings, or to the output locale if
 492  * @a for_output is TRUE.  Return the translated data in @a
 493  * *new_value, allocated in @a pool.
 494  */
 495 svn_error_t *svn_subst_detranslate_string(svn_string_t **new_value,
 496                                           const svn_string_t *value,
 497                                           svn_boolean_t for_output,
 498                                           apr_pool_t *pool);
 499
 500
 501
 502 #ifdef __cplusplus
 503 }
 504 #endif /* __cplusplus */
 505
 506 #endif /* SVN_SUBST_H */