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 routines to perform data substitution 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 typedef struct svn_subst_keywords_t 00080 { 00081 const svn_string_t *revision; 00082 const svn_string_t *date; 00083 const svn_string_t *author; 00084 const svn_string_t *url; 00085 const svn_string_t *id; 00086 } svn_subst_keywords_t; 00087 00088 00089 /** Fill in an <tt>svn_subst_keywords_t *</tt> @a kw with the appropriate 00090 * contents given an @a keywords_string (the contents of the svn:keywords 00091 * property for the file in question), the revision @a rev, the @a url, 00092 * the @a date the file was committed on, and the @a author of the last 00093 * commit. Any of these can be @c NULL to indicate that the information is 00094 * not present, or @c 0 for @a date. 00095 * 00096 * All memory is allocated out of @a pool. 00097 */ 00098 svn_error_t * 00099 svn_subst_build_keywords (svn_subst_keywords_t *kw, 00100 const char *keywords_string, 00101 const char *rev, 00102 const char *url, 00103 apr_time_t date, 00104 const char *author, 00105 apr_pool_t *pool); 00106 00107 00108 /** Return @c TRUE if @a a and @a b do not hold the same keywords. 00109 * 00110 * If @a compare_values is @c TRUE, "same" means that the @a a and @a b 00111 * contain exactly the same set of keywords, and the values of corresponding 00112 * keywords match as well. Else if @a compare_values is @c FALSE, then 00113 * "same" merely means that @a a and @a b hold the same set of keywords, 00114 * although those keywords' values might differ. 00115 * 00116 * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is 00117 * equivalent to holding no keywords. 00118 */ 00119 svn_boolean_t 00120 svn_subst_keywords_differ (const svn_subst_keywords_t *a, 00121 const svn_subst_keywords_t *b, 00122 svn_boolean_t compare_values); 00123 00124 00125 /** Copy and translate the data in stream @a src into stream @a dst. It is 00126 * assumed that @a src is a readable stream and @a dst is a writable stream. 00127 * 00128 * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to 00129 * denote line endings with @a eol_str in the output. If @a src has an 00130 * inconsistent line ending style, then: if @a repair is @c FALSE, return 00131 * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any 00132 * line ending in @a src to @a eol_str in @a dst. Recognized line endings are: 00133 * "\\n", "\\r", and "\\r\\n". 00134 * 00135 * Expand and contract keywords using the contents of @a keywords as the 00136 * new values. If @a expand is @c TRUE, expand contracted keywords and 00137 * re-expand expanded keywords. If @a expand is @c FALSE, contract expanded 00138 * keywords and ignore contracted ones. @c NULL for any of the keyword 00139 * values (@a keywords->revision, e.g.) indicates that keyword should be 00140 * ignored (not contracted or expanded). If the @a keywords structure 00141 * itself is @c NULL, keyword substitution will be altogether ignored. 00142 * 00143 * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN 00144 * bytes, including the delimiters and the keyword itself. 00145 * 00146 * Note that a translation request is *required*: one of @a eol_str or 00147 * @a keywords must be non-@c NULL. 00148 * 00149 * Recommendation: if @a expand is false, then you don't care about the 00150 * keyword values, so pass empty strings as non-null signifiers. 00151 * 00152 * Notes: 00153 * 00154 * See @c svn_wc__get_keywords() and @c svn_wc__get_eol_style() for a 00155 * convenient way to get @a eol_str and @a keywords if in libsvn_wc. 00156 */ 00157 svn_error_t * 00158 svn_subst_translate_stream (svn_stream_t *src, 00159 svn_stream_t *dst, 00160 const char *eol_str, 00161 svn_boolean_t repair, 00162 const svn_subst_keywords_t *keywords, 00163 svn_boolean_t expand); 00164 00165 00166 /** Convenience routine: a variant of @c svn_subst_translate_stream which 00167 * operates on files. (See previous docstring for details.) 00168 * 00169 * Copy the contents of file-path @a src to file-path @a dst atomically, 00170 * either creating @a dst (or overwriting @a dst if it exists), possibly 00171 * performing line ending and keyword translations. 00172 * 00173 * If anything goes wrong during the copy, attempt to delete @a dst (if 00174 * it exists). 00175 * 00176 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte 00177 * copy. 00178 */ 00179 svn_error_t * 00180 svn_subst_copy_and_translate (const char *src, 00181 const char *dst, 00182 const char *eol_str, 00183 svn_boolean_t repair, 00184 const svn_subst_keywords_t *keywords, 00185 svn_boolean_t expand, 00186 apr_pool_t *pool); 00187 00188 /** Convenience routine: a variant of @c svn_subst_translate_stream which 00189 * operates on cstrings. (See previous docstring for details.) 00190 * 00191 * Return a new string in @a *dst, allocated in @a pool, by copying the 00192 * contents of string @a src, possibly performing line ending and keyword 00193 * translations. 00194 * 00195 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte 00196 * copy. 00197 */ 00198 svn_error_t * 00199 svn_subst_translate_cstring (const char *src, 00200 const char **dst, 00201 const char *eol_str, 00202 svn_boolean_t repair, 00203 const svn_subst_keywords_t *keywords, 00204 svn_boolean_t expand, 00205 apr_pool_t *pool); 00206 00207 00208 /* Eol conversion and character encodings */ 00209 00210 /** Translate the data in @a value (assumed to be in encoded in charset 00211 * @a encoding) to UTF8 and LF line-endings. If @a encoding is @c NULL, 00212 * then assume that @a value is in the system-default language encoding. 00213 * Return the translated data in @a *new_value, allocated in @a pool. 00214 */ 00215 svn_error_t *svn_subst_translate_string (svn_string_t **new_value, 00216 const svn_string_t *value, 00217 const char *encoding, 00218 apr_pool_t *pool); 00219 00220 /** Translate the data in @a value from UTF8 and LF line-endings into 00221 * native locale and native line-endings, or to the output locale if 00222 * @a for_output is TURE. Return the translated data in @a 00223 * *new_value, allocated in @a pool. 00224 */ 00225 svn_error_t *svn_subst_detranslate_string (svn_string_t **new_value, 00226 const svn_string_t *value, 00227 svn_boolean_t for_stdout, 00228 apr_pool_t *pool); 00229 00230 00231 00232 #ifdef __cplusplus 00233 } 00234 #endif /* __cplusplus */ 00235 00236 #endif /* SVN_SUBST_H */