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