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 NULL, it is ignored.
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 /** Indicates whether the working copy and normalized versions of a file
00078  * with the given the parameters differ.  If @a force_eol_check is TRUE,
00079  * the routine also accounts for all translations required due to repairing
00080  * fixed eol styles.
00081  *
00082  * @since New in 1.4
00083  *
00084  */
00085 svn_boolean_t
00086 svn_subst_translation_required(svn_subst_eol_style_t style,
00087                                const char *eol,
00088                                apr_hash_t *keywords,
00089                                svn_boolean_t special,
00090                                svn_boolean_t force_eol_check);
00091 
00092 
00093 /** Values used in keyword expansion.
00094  *
00095  * @deprecated Provided for backward compatibility with the 1.2 API.
00096  */
00097 typedef struct svn_subst_keywords_t
00098 {
00099   /**
00100    * @name svn_subst_keywords_t fields
00101    * String expansion of the like-named keyword, or NULL if the keyword
00102    * was not selected in the svn:keywords property.
00103    * @{
00104    */
00105   const svn_string_t *revision;
00106   const svn_string_t *date;
00107   const svn_string_t *author;
00108   const svn_string_t *url;
00109   const svn_string_t *id;
00110   /** @} */
00111 } svn_subst_keywords_t;
00112 
00113 
00114 /**
00115  * Set @a *kw to a new keywords hash filled with the appropriate contents
00116  * given a @a keywords_string (the contents of the svn:keywords
00117  * property for the file in question), the revision @a rev, the @a url,
00118  * the @a date the file was committed on, and the @a author of the last
00119  * commit.  Any of these can be @c NULL to indicate that the information is
00120  * not present, or @c 0 for @a date.
00121  *
00122  * Hash keys are of type <tt>const char *</tt>.
00123  * Hash values are of type <tt>svn_string_t *</tt>.
00124  *
00125  * All memory is allocated out of @a pool.
00126  *
00127  * @since New in 1.3.
00128  */
00129 svn_error_t *
00130 svn_subst_build_keywords2(apr_hash_t **kw,
00131                           const char *keywords_string,
00132                           const char *rev,
00133                           const char *url,
00134                           apr_time_t date,
00135                           const char *author,
00136                           apr_pool_t *pool);
00137 
00138 /** Similar to svn_subst_build_keywords2() except that it populates
00139  * an existing structure @a *kw instead of creating a keywords hash.
00140  *
00141  * @deprecated Provided for backward compatibility with the 1.2 API.
00142  */
00143 svn_error_t *
00144 svn_subst_build_keywords(svn_subst_keywords_t *kw,
00145                          const char *keywords_string,
00146                          const char *rev,
00147                          const char *url,
00148                          apr_time_t date,
00149                          const char *author,
00150                          apr_pool_t *pool);
00151 
00152 
00153 /** Return @c TRUE if @a a and @a b do not hold the same keywords.
00154  *
00155  * @a a and @a b are hashes of the form produced by
00156  * svn_subst_build_keywords2().
00157  *
00158  * @since New in 1.3.
00159  *
00160  * If @a compare_values is @c TRUE, "same" means that the @a a and @a b
00161  * contain exactly the same set of keywords, and the values of corresponding
00162  * keywords match as well.  Else if @a compare_values is @c FALSE, then
00163  * "same" merely means that @a a and @a b hold the same set of keywords,
00164  * although those keywords' values might differ.
00165  *
00166  * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is
00167  * equivalent to holding no keywords.
00168  */
00169 svn_boolean_t
00170 svn_subst_keywords_differ2(apr_hash_t *a,
00171                            apr_hash_t *b,
00172                            svn_boolean_t compare_values,
00173                            apr_pool_t *pool);
00174 
00175 /** Similar to svn_subst_keywords_differ2() except that it compares
00176  * two @c svn_subst_keywords_t structs instead of keyword hashes.
00177  *
00178  * @deprecated Provided for backward compatibility with the 1.2 API.
00179  */
00180 svn_boolean_t
00181 svn_subst_keywords_differ(const svn_subst_keywords_t *a,
00182                           const svn_subst_keywords_t *b,
00183                           svn_boolean_t compare_values);
00184 
00185 
00186 /**
00187  * Copy and translate the data in stream @a src into stream @a dst.  It is
00188  * assumed that @a src is a readable stream and @a dst is a writable stream.
00189  *
00190  * @since New in 1.3.
00191  *
00192  * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to
00193  * denote line endings with @a eol_str in the output.  If @a src has an
00194  * inconsistent line ending style, then: if @a repair is @c FALSE, return
00195  * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any
00196  * line ending in @a src to @a eol_str in @a dst.  Recognized line endings are:
00197  * "\n", "\r", and "\r\n".
00198  *
00199  * Expand and contract keywords using the contents of @a keywords as the
00200  * new values.  If @a expand is @c TRUE, expand contracted keywords and
00201  * re-expand expanded keywords.  If @a expand is @c FALSE, contract expanded
00202  * keywords and ignore contracted ones.  Keywords not found in the hash are
00203  * ignored (not contracted or expanded).  If the @a keywords hash
00204  * itself is @c NULL, keyword substitution will be altogether ignored.
00205  *
00206  * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN
00207  * bytes, including the delimiters and the keyword itself.
00208  *
00209  * Note that a translation request is *required*:  one of @a eol_str or
00210  * @a keywords must be non-@c NULL.
00211  *
00212  * Recommendation: if @a expand is FALSE, then you don't care about the
00213  * keyword values, so use empty strings as non-NULL signifiers when you
00214  * build the keywords hash.
00215  *
00216  * Notes:
00217  *
00218  * See svn_wc__get_keywords() and svn_wc__get_eol_style() for a
00219  * convenient way to get @a eol_str and @a keywords if in libsvn_wc.
00220  */
00221 svn_error_t *
00222 svn_subst_translate_stream3(svn_stream_t *src,
00223                             svn_stream_t *dst,
00224                             const char *eol_str,
00225                             svn_boolean_t repair,
00226                             apr_hash_t *keywords,
00227                             svn_boolean_t expand,
00228                             apr_pool_t *pool);
00229 
00230 /** Return a stream which performs eol translation and keyword
00231  * expansion when read from or written to.  The stream @a stream
00232  * is used to read and write all data.  Make sure you call
00233  * svn_stream_close() on @a stream to make sure all data are flushed
00234  * and cleaned up.
00235  *
00236  * Read operations from and write operations to the stream
00237  * perform the same operation: if @a expand is @c FALSE, both
00238  * contract keywords.  One stream supports both read and write
00239  * operations.  Reads and writes may be mixed.
00240  *
00241  * The stream returned is allocated in @a pool.
00242  *
00243  * @since New in 1.4.
00244  */
00245 svn_stream_t *
00246 svn_subst_stream_translated(svn_stream_t *stream,
00247                             const char *eol_str,
00248                             svn_boolean_t repair,
00249                             apr_hash_t *keywords,
00250                             svn_boolean_t expand,
00251                             apr_pool_t *pool);
00252 
00253 /** Return a stream which performs eol translation and keyword
00254  * expansion when read from or written to.  The stream @a stream
00255  * is used to read and write all data.  Make sure you call
00256  * svn_stream_close() on @a stream to make sure all data are flushed
00257  * and cleaned up.
00258  *
00259  * Read and write operations perform the same transformation:
00260  * all data is translated to normal form.
00261  *
00262  * @see svn_subst_translate_to_normal_form()
00263  *
00264  * @since New in 1.5.
00265  */
00266 svn_error_t *
00267 svn_subst_stream_translated_to_normal_form(svn_stream_t **stream,
00268                                            svn_stream_t *source,
00269                                            svn_subst_eol_style_t eol_style,
00270                                            const char *eol_str,
00271                                            svn_boolean_t always_repair_eols,
00272                                            apr_hash_t *keywords,
00273                                            apr_pool_t *pool);
00274 
00275 
00276 /** Returns a stream which translates the special file at @a path to
00277  * the internal representation for special files when read from.  When
00278  * written to, it does the reverse: creating a special file when the
00279  * stream is closed.
00280  *
00281  * @since New in 1.5.
00282  */
00283 svn_error_t *
00284 svn_subst_stream_from_specialfile(svn_stream_t **stream,
00285                                   const char *path,
00286                                   apr_pool_t *pool);
00287 
00288 
00289 /** Similar to svn_subst_translate_stream3() except relies upon a
00290  * @c svn_subst_keywords_t struct instead of a hash for the keywords.
00291  *
00292  * @deprecated Provided for backward compatibility with the 1.2 API.
00293  */
00294 svn_error_t *
00295 svn_subst_translate_stream2(svn_stream_t *src,
00296                             svn_stream_t *dst,
00297                             const char *eol_str,
00298                             svn_boolean_t repair,
00299                             const svn_subst_keywords_t *keywords,
00300                             svn_boolean_t expand,
00301                             apr_pool_t *pool);
00302 
00303 
00304 /**
00305  * Same as svn_subst_translate_stream2(), but does not take a @a pool
00306  * argument, instead creates a temporary subpool of the global pool, and
00307  * destroys it before returning.
00308  *
00309  * @deprecated Provided for backward compatibility with the 1.1 API.
00310  */
00311 svn_error_t *
00312 svn_subst_translate_stream(svn_stream_t *src,
00313                            svn_stream_t *dst,
00314                            const char *eol_str,
00315                            svn_boolean_t repair,
00316                            const svn_subst_keywords_t *keywords,
00317                            svn_boolean_t expand);
00318 
00319 
00320 /**
00321  * Translates the file at path @a src into a file at path @a dst.  The
00322  * parameters @a *eol_str, @a repair, @a *keywords and @a expand are
00323  * defined the same as in svn_subst_translate_stream3().
00324  *
00325  * In addition, it will create a special file from normal form or
00326  * translate one to normal form if @a special is @c TRUE.
00327  *
00328  * Copy the contents of file-path @a src to file-path @a dst atomically,
00329  * either creating @a dst (or overwriting @a dst if it exists), possibly
00330  * performing line ending and keyword translations.
00331  *
00332  * If anything goes wrong during the copy, attempt to delete @a dst (if
00333  * it exists).
00334  *
00335  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
00336  * copy.
00337  *
00338  * @since New in 1.3.
00339  */
00340 svn_error_t *
00341 svn_subst_copy_and_translate3(const char *src,
00342                               const char *dst,
00343                               const char *eol_str,
00344                               svn_boolean_t repair,
00345                               apr_hash_t *keywords,
00346                               svn_boolean_t expand,
00347                               svn_boolean_t special,
00348                               apr_pool_t *pool);
00349 
00350 /**
00351  * Similar to svn_subst_copy_and_translate3() except that @a keywords is a
00352  * @c svn_subst_keywords_t struct instead of a keywords hash.
00353  *
00354  * @deprecated Provided for backward compatibility with the 1.2 API.
00355  * @since New in 1.1.
00356  */
00357 svn_error_t *
00358 svn_subst_copy_and_translate2(const char *src,
00359                               const char *dst,
00360                               const char *eol_str,
00361                               svn_boolean_t repair,
00362                               const svn_subst_keywords_t *keywords,
00363                               svn_boolean_t expand,
00364                               svn_boolean_t special,
00365                               apr_pool_t *pool);
00366 
00367 /**
00368  * Similar to svn_subst_copy_and_translate2() except that @a special is
00369  * always set to @c FALSE.
00370  *
00371  * @deprecated Provided for backward compatibility with the 1.0 API.
00372  */
00373 svn_error_t *
00374 svn_subst_copy_and_translate(const char *src,
00375                              const char *dst,
00376                              const char *eol_str,
00377                              svn_boolean_t repair,
00378                              const svn_subst_keywords_t *keywords,
00379                              svn_boolean_t expand,
00380                              apr_pool_t *pool);
00381 
00382 
00383 /**
00384  * Convenience routine: a variant of svn_subst_translate_stream3() which
00385  * operates on cstrings.
00386  *
00387  * @since New in 1.3.
00388  *
00389  * Return a new string in @a *dst, allocated in @a pool, by copying the
00390  * contents of string @a src, possibly performing line ending and keyword
00391  * translations.
00392  *
00393  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
00394  * copy.
00395  */
00396 svn_error_t *
00397 svn_subst_translate_cstring2(const char *src,
00398                              const char **dst,
00399                              const char *eol_str,
00400                              svn_boolean_t repair,
00401                              apr_hash_t *keywords,
00402                              svn_boolean_t expand,
00403                              apr_pool_t *pool);
00404 
00405 /**
00406  * Similar to svn_subst_translate_cstring2() except that @a keywords is a
00407  * @c svn_subst_keywords_t struct instead of a keywords hash.
00408  *
00409  * @deprecated Provided for backward compatibility with the 1.2 API.
00410  */
00411 svn_error_t *
00412 svn_subst_translate_cstring(const char *src,
00413                             const char **dst,
00414                             const char *eol_str,
00415                             svn_boolean_t repair,
00416                             const svn_subst_keywords_t *keywords,
00417                             svn_boolean_t expand,
00418                             apr_pool_t *pool);
00419 
00420 /**
00421  * Translates a file @a src in working copy form to a file @a dst in
00422  * normal form.
00423  *
00424  * The values specified for @a eol_style, @a *eol_str, @a keywords and
00425  * @a special, should be the ones used to translate the file to its
00426  * working copy form.  Usually, these are the values specified by the
00427  * user in the files' properties.
00428  *
00429  * Inconsistent line endings in the file will be automatically repaired
00430  * (made consistent) for some eol styles.  For all others, an error is
00431  * returned.  By setting @a always_repair_eols to @c TRUE, eols will be
00432  * made consistent even for those styles which don't have it by default.
00433  *
00434  * @note To translate a file FROM normal form, use
00435  *       svn_subst_copy_and_translate3().
00436  *
00437  * @since New in 1.4
00438  *
00439  */
00440 svn_error_t *
00441 svn_subst_translate_to_normal_form(const char *src,
00442                                    const char *dst,
00443                                    svn_subst_eol_style_t eol_style,
00444                                    const char *eol_str,
00445                                    svn_boolean_t always_repair_eols,
00446                                    apr_hash_t *keywords,
00447                                    svn_boolean_t special,
00448                                    apr_pool_t *pool);
00449 
00450 /**
00451  * Set @a *stream_p to a stream that detranslates the file @a src from
00452  * working copy form to normal form, allocated in @a pool.
00453  *
00454  * The values specified for @a eol_style, @a *eol_str, @a keywords and
00455  * @a special, should be the ones used to translate the file to its
00456  * working copy form.  Usually, these are the values specified by the
00457  * user in the files' properties.
00458  *
00459  * Inconsistent line endings in the file will be automatically repaired
00460  * (made consistent) for some eol styles.  For all others, an error is
00461  * returned.  By setting @a always_repair_eols to @c TRUE, eols will be
00462  * made consistent even for those styles which don't have it by default.
00463  *
00464  * @since New in 1.4.
00465  *
00466  */
00467 svn_error_t *
00468 svn_subst_stream_detranslated(svn_stream_t **stream_p,
00469                               const char *src,
00470                               svn_subst_eol_style_t eol_style,
00471                               const char *eol_str,
00472                               svn_boolean_t always_repair_eols,
00473                               apr_hash_t *keywords,
00474                               svn_boolean_t special,
00475                               apr_pool_t *pool);
00476 
00477 
00478 /* EOL conversion and character encodings */
00479 
00480 /** Translate the data in @a value (assumed to be in encoded in charset
00481  * @a encoding) to UTF8 and LF line-endings.  If @a encoding is @c NULL,
00482  * then assume that @a value is in the system-default language encoding.
00483  * Return the translated data in @a *new_value, allocated in @a pool.
00484  */
00485 svn_error_t *svn_subst_translate_string(svn_string_t **new_value,
00486                                         const svn_string_t *value,
00487                                         const char *encoding,
00488                                         apr_pool_t *pool);
00489 
00490 /** Translate the data in @a value from UTF8 and LF line-endings into
00491  * native locale and native line-endings, or to the output locale if
00492  * @a for_output is TRUE.  Return the translated data in @a
00493  * *new_value, allocated in @a pool.
00494  */
00495 svn_error_t *svn_subst_detranslate_string(svn_string_t **new_value,
00496                                           const svn_string_t *value,
00497                                           svn_boolean_t for_output,
00498                                           apr_pool_t *pool);
00499 
00500 
00501 
00502 #ifdef __cplusplus
00503 }
00504 #endif /* __cplusplus */
00505 
00506 #endif /* SVN_SUBST_H */

Generated on Sun Dec 21 20:02:54 2008 for Subversion by doxygen 1.3.5