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 */