Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_subst.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_subst.h
00019  * @brief Data substitution (keywords and EOL style)
00020  */
00021 
00022 
00023 
00024 #ifndef SVN_SUBST_H
00025 #define SVN_SUBST_H
00026 
00027 #include "svn_types.h"
00028 #include "svn_string.h"
00029 #include "svn_io.h"
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif /* __cplusplus */
00034 
00035 /* EOL conversion and keyword expansion. */
00036 
00037 /** Valid states for 'svn:eol-style' property.
00038  *
00039  * Property nonexistence is equivalent to 'none'.
00040  */
00041 typedef enum svn_subst_eol_style
00042 {
00043   /** An unrecognized style */
00044   svn_subst_eol_style_unknown,
00045 
00046   /** EOL translation is "off" or ignored value */
00047   svn_subst_eol_style_none,
00048 
00049   /** Translation is set to client's native eol */
00050   svn_subst_eol_style_native,
00051 
00052   /** Translation is set to one of LF, CR, CRLF */
00053   svn_subst_eol_style_fixed
00054 
00055 } svn_subst_eol_style_t;
00056 
00057 /** Set @a *style to the appropriate @c svn_subst_eol_style_t and @a *eol to 
00058  * the appropriate cstring for a given svn:eol-style property value.
00059  *
00060  * Set @a *eol to
00061  *
00062  *    - @c NULL for @c svn_subst_eol_style_none, or
00063  *
00064  *    - a null-terminated C string containing the native eol marker
00065  *      for this platform, for @c svn_subst_eol_style_native, or
00066  *            
00067  *    - a null-terminated C string containing the eol marker indicated
00068  *      by the property value, for @c svn_subst_eol_style_fixed.
00069  *
00070  * If @a *style is @c NULL, then @a value was not a valid property value.
00071  */
00072 void
00073 svn_subst_eol_style_from_value (svn_subst_eol_style_t *style,
00074                                 const char **eol,
00075                                 const char *value);
00076 
00077 
00078 /** Values used in keyword expansion.
00079  *
00080  * @deprecated Provided for backward compatibility with the 1.2 API.
00081  */
00082 typedef struct svn_subst_keywords_t
00083 {
00084   /**
00085    * @name svn_subst_keywords_t fields
00086    * String expansion of the like-named keyword, or NULL if the keyword
00087    * was not selected in the svn:keywords property.
00088    * @{
00089    */
00090   const svn_string_t *revision;
00091   const svn_string_t *date;
00092   const svn_string_t *author;
00093   const svn_string_t *url;
00094   const svn_string_t *id;
00095   /** @} */
00096 } svn_subst_keywords_t;
00097 
00098 
00099 /**
00100  * Set @a *kw to a new keywords hash filled with the appropriate contents
00101  * given a @a keywords_string (the contents of the svn:keywords
00102  * property for the file in question), the revision @a rev, the @a url, 
00103  * the @a date the file was committed on, and the @a author of the last 
00104  * commit.  Any of these can be @c NULL to indicate that the information is
00105  * not present, or @c 0 for @a date.
00106  *
00107  * Hash keys are of type <tt>const char *</tt>.
00108  * Hash values are of type <tt>svn_string_t *</tt>.
00109  * 
00110  * All memory is allocated out of @a pool.
00111  *
00112  * @since New in 1.3.
00113  */
00114 svn_error_t *
00115 svn_subst_build_keywords2 (apr_hash_t **kw,
00116                            const char *keywords_string,
00117                            const char *rev,
00118                            const char *url,
00119                            apr_time_t date,
00120                            const char *author,
00121                            apr_pool_t *pool);
00122 
00123 /** Similar to svn_subst_build_keywords2() except that it populates
00124  * an existing structure @a *kw instead of creating a keywords hash.
00125  *
00126  * @deprecated Provided for backward compatibility with the 1.2 API.
00127  */
00128 svn_error_t *
00129 svn_subst_build_keywords (svn_subst_keywords_t *kw,
00130                           const char *keywords_string,
00131                           const char *rev,
00132                           const char *url,
00133                           apr_time_t date,
00134                           const char *author,
00135                           apr_pool_t *pool);
00136 
00137 
00138 /** Return @c TRUE if @a a and @a b do not hold the same keywords.
00139  *
00140  * @a a and @a b are hashes of the form produced by
00141  * svn_subst_build_keywords2().
00142  *
00143  * @since New in 1.3.
00144  *
00145  * If @a compare_values is @c TRUE, "same" means that the @a a and @a b 
00146  * contain exactly the same set of keywords, and the values of corresponding
00147  * keywords match as well.  Else if @a compare_values is @c FALSE, then
00148  * "same" merely means that @a a and @a b hold the same set of keywords,
00149  * although those keywords' values might differ.
00150  *
00151  * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is
00152  * equivalent to holding no keywords.
00153  */
00154 svn_boolean_t 
00155 svn_subst_keywords_differ2 (apr_hash_t *a,
00156                             apr_hash_t *b,
00157                             svn_boolean_t compare_values,
00158                             apr_pool_t *pool);
00159 
00160 /** Similar to svn_subst_keywords_differ2() except that it compares
00161  * two @c svn_subst_keywords_t structs instead of keyword hashes.
00162  *
00163  * @deprecated Provided for backward compatibility with the 1.2 API.
00164  */
00165 svn_boolean_t 
00166 svn_subst_keywords_differ (const svn_subst_keywords_t *a,
00167                            const svn_subst_keywords_t *b,
00168                            svn_boolean_t compare_values);
00169 
00170 
00171 /** 
00172  * Copy and translate the data in stream @a src into stream @a dst.  It is
00173  * assumed that @a src is a readable stream and @a dst is a writable stream.
00174  *
00175  * @since New in 1.3.
00176  *
00177  * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to
00178  * denote line endings with @a eol_str in the output.  If @a src has an
00179  * inconsistent line ending style, then: if @a repair is @c FALSE, return
00180  * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any
00181  * line ending in @a src to @a eol_str in @a dst.  Recognized line endings are:
00182  * "\n", "\r", and "\r\n".
00183  *
00184  * Expand and contract keywords using the contents of @a keywords as the
00185  * new values.  If @a expand is @c TRUE, expand contracted keywords and
00186  * re-expand expanded keywords.  If @a expand is @c FALSE, contract expanded
00187  * keywords and ignore contracted ones.  Keywords not found in the hash are
00188  * ignored (not contracted or expanded).  If the @a keywords hash
00189  * itself is @c NULL, keyword substitution will be altogether ignored.
00190  *
00191  * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN
00192  * bytes, including the delimiters and the keyword itself.
00193  *
00194  * Note that a translation request is *required*:  one of @a eol_str or
00195  * @a keywords must be non-@c NULL.
00196  *
00197  * Recommendation: if @a expand is false, then you don't care about the
00198  * keyword values, so use empty strings as non-null signifiers when you
00199  * build the keywords hash.
00200  *
00201  * Notes: 
00202  *
00203  * See svn_wc__get_keywords() and svn_wc__get_eol_style() for a
00204  * convenient way to get @a eol_str and @a keywords if in libsvn_wc.
00205  */
00206 svn_error_t *
00207 svn_subst_translate_stream3 (svn_stream_t *src,
00208                              svn_stream_t *dst,
00209                              const char *eol_str,
00210                              svn_boolean_t repair,
00211                              apr_hash_t *keywords,
00212                              svn_boolean_t expand,
00213                              apr_pool_t *pool);
00214 
00215 /** Similar to svn_subst_translate_stream3() except relies upon a
00216  * @c svn_subst_keywords_t struct instead of a hash for the keywords.
00217  *
00218  * @deprecated Provided for backward compatibility with the 1.2 API.
00219  */
00220 svn_error_t *
00221 svn_subst_translate_stream2 (svn_stream_t *src,
00222                              svn_stream_t *dst,
00223                              const char *eol_str,
00224                              svn_boolean_t repair,
00225                              const svn_subst_keywords_t *keywords,
00226                              svn_boolean_t expand,
00227                              apr_pool_t *pool);
00228 
00229 
00230 /**
00231  * Same as svn_subst_translate_stream2(), but does not take a @a pool
00232  * argument, instead creates a temporary subpool of the global pool, and
00233  * destroys it before returning.
00234  *
00235  * @deprecated Provided for backward compatibility with the 1.1 API.
00236  */
00237 svn_error_t *
00238 svn_subst_translate_stream (svn_stream_t *src,
00239                             svn_stream_t *dst,
00240                             const char *eol_str,
00241                             svn_boolean_t repair,
00242                             const svn_subst_keywords_t *keywords,
00243                             svn_boolean_t expand);
00244 
00245 
00246 /**
00247  * Convenience routine: a variant of svn_subst_translate_stream3()
00248  * which operates on files.  In addition, it will create/detranslate a special
00249  * file if @a special is @c TRUE.
00250  *
00251  * Copy the contents of file-path @a src to file-path @a dst atomically,
00252  * either creating @a dst (or overwriting @a dst if it exists), possibly
00253  * performing line ending and keyword translations.
00254  *
00255  * If anything goes wrong during the copy, attempt to delete @a dst (if
00256  * it exists).
00257  *
00258  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
00259  * copy.
00260  *
00261  * @since New in 1.3.
00262  */
00263 svn_error_t *
00264 svn_subst_copy_and_translate3 (const char *src,
00265                                const char *dst,
00266                                const char *eol_str,
00267                                svn_boolean_t repair,
00268                                apr_hash_t *keywords,
00269                                svn_boolean_t expand,
00270                                svn_boolean_t special,
00271                                apr_pool_t *pool);
00272 
00273 /**
00274  * Similar to svn_subst_copy_and_translate3() except that @a keywords is a
00275  * @c svn_subst_keywords_t struct instead of a keywords hash.
00276  *
00277  * @deprecated Provided for backward compatibility with the 1.2 API.
00278  * @since New in 1.1.
00279  */
00280 svn_error_t *
00281 svn_subst_copy_and_translate2 (const char *src,
00282                                const char *dst,
00283                                const char *eol_str,
00284                                svn_boolean_t repair,
00285                                const svn_subst_keywords_t *keywords,
00286                                svn_boolean_t expand,
00287                                svn_boolean_t special,
00288                                apr_pool_t *pool);
00289 
00290 /**
00291  * Similar to svn_subst_copy_and_translate2() except that @a special is
00292  * always set to @c FALSE.
00293  *
00294  * @deprecated Provided for backward compatibility with the 1.0 API.
00295  */
00296 svn_error_t *
00297 svn_subst_copy_and_translate (const char *src,
00298                               const char *dst,
00299                               const char *eol_str,
00300                               svn_boolean_t repair,
00301                               const svn_subst_keywords_t *keywords,
00302                               svn_boolean_t expand,
00303                               apr_pool_t *pool);
00304 
00305 
00306 /**
00307  * Convenience routine: a variant of svn_subst_translate_stream3() which
00308  * operates on cstrings.
00309  *
00310  * @since New in 1.3.
00311  *
00312  * Return a new string in @a *dst, allocated in @a pool, by copying the
00313  * contents of string @a src, possibly performing line ending and keyword
00314  * translations.
00315  *
00316  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
00317  * copy.
00318  */
00319 svn_error_t *
00320 svn_subst_translate_cstring2 (const char *src,
00321                               const char **dst,
00322                               const char *eol_str,
00323                               svn_boolean_t repair,
00324                               apr_hash_t *keywords,
00325                               svn_boolean_t expand,
00326                               apr_pool_t *pool);
00327 
00328 /**
00329  * Similar to svn_subst_translate_cstring2() except that @a keywords is a
00330  * @c svn_subst_keywords_t struct instead of a keywords hash.
00331  *
00332  * @deprecated Provided for backward compatibility with the 1.2 API.
00333  */
00334 svn_error_t *
00335 svn_subst_translate_cstring (const char *src,
00336                              const char **dst,
00337                              const char *eol_str,
00338                              svn_boolean_t repair,
00339                              const svn_subst_keywords_t *keywords,
00340                              svn_boolean_t expand,
00341                              apr_pool_t *pool);
00342 
00343 
00344 /* EOL conversion and character encodings */
00345 
00346 /** Translate the data in @a value (assumed to be in encoded in charset
00347  * @a encoding) to UTF8 and LF line-endings.  If @a encoding is @c NULL, 
00348  * then assume that @a value is in the system-default language encoding.
00349  * Return the translated data in @a *new_value, allocated in @a pool.  
00350  */
00351 svn_error_t *svn_subst_translate_string (svn_string_t **new_value,
00352                                          const svn_string_t *value,
00353                                          const char *encoding,
00354                                          apr_pool_t *pool);
00355 
00356 /** Translate the data in @a value from UTF8 and LF line-endings into
00357  * native locale and native line-endings, or to the output locale if
00358  * @a for_output is TRUE.  Return the translated data in @a
00359  * *new_value, allocated in @a pool.
00360  */
00361 svn_error_t *svn_subst_detranslate_string (svn_string_t **new_value,
00362                                            const svn_string_t *value,
00363                                            svn_boolean_t for_stdout,
00364                                            apr_pool_t *pool);
00365 
00366 
00367 
00368 #ifdef __cplusplus
00369 }
00370 #endif /* __cplusplus */
00371 
00372 #endif /* SVN_SUBST_H */

Generated on Mon Jun 19 20:42:19 2006 for Subversion by doxygen 1.3.5