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  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_subst.h
24  * @brief Data substitution (keywords and EOL style)
25  */
26 
27 
28 
29 #ifndef SVN_SUBST_H
30 #define SVN_SUBST_H
31 
32 #include <apr_pools.h>
33 #include <apr_hash.h>
34 #include <apr_time.h>
35 
36 #include "svn_types.h"
37 #include "svn_string.h"
38 #include "svn_io.h"
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif /* __cplusplus */
43 
44 /* EOL conversion and keyword expansion. */
45 
46 /** The EOL used in the Repository for "native" files */
47 #define SVN_SUBST_NATIVE_EOL_STR "\n"
48 
49 /** Valid states for 'svn:eol-style' property.
50  *
51  * Property nonexistence is equivalent to 'none'.
52  */
53 typedef enum svn_subst_eol_style
54 {
55  /** An unrecognized style */
57 
58  /** EOL translation is "off" or ignored value */
60 
61  /** Translation is set to client's native eol */
63 
64  /** Translation is set to one of LF, CR, CRLF */
66 
68 
69 /** Set @a *style to the appropriate @c svn_subst_eol_style_t and @a *eol to
70  * the appropriate cstring for a given svn:eol-style property value.
71  *
72  * Set @a *eol to
73  *
74  * - @c NULL for @c svn_subst_eol_style_none, or
75  *
76  * - a NULL-terminated C string containing the native eol marker
77  * for this platform, for @c svn_subst_eol_style_native, or
78  *
79  * - a NULL-terminated C string containing the eol marker indicated
80  * by the property value, for @c svn_subst_eol_style_fixed.
81  *
82  * If @a *style is NULL, it is ignored.
83  */
84 void
86  const char **eol,
87  const char *value);
88 
89 /** Indicates whether the working copy and normalized versions of a file
90  * with the given the parameters differ. If @a force_eol_check is TRUE,
91  * the routine also accounts for all translations required due to repairing
92  * fixed eol styles.
93  *
94  * @since New in 1.4
95  *
96  */
99  const char *eol,
100  apr_hash_t *keywords,
101  svn_boolean_t special,
102  svn_boolean_t force_eol_check);
103 
104 
105 /** Values used in keyword expansion.
106  *
107  * @deprecated Provided for backward compatibility with the 1.2 API.
108  */
109 typedef struct svn_subst_keywords_t
110 {
111  /**
112  * @name svn_subst_keywords_t fields
113  * String expansion of the like-named keyword, or NULL if the keyword
114  * was not selected in the svn:keywords property.
115  * @{
116  */
117  const svn_string_t *revision;
118  const svn_string_t *date;
119  const svn_string_t *author;
120  const svn_string_t *url;
121  const svn_string_t *id;
122  /** @} */
124 
125 
126 /**
127  * Set @a *kw to a new keywords hash filled with the appropriate contents
128  * given a @a keywords_string (the contents of the svn:keywords
129  * property for the file in question), the revision @a rev, the @a url,
130  * the @a date the file was committed on, the @a author of the last
131  * commit, and the URL of the repository root @a repos_root_url.
132  *
133  * Custom keywords defined in svn:keywords properties are expanded
134  * using the provided parameters and in accordance with the following
135  * format substitutions in the @a keywords_string:
136  * %a - The author.
137  * %b - The basename of the URL.
138  * %d - Short format of the date.
139  * %D - Long format of the date.
140  * %P - The file's path, relative to the repository root URL.
141  * %r - The revision.
142  * %R - The URL to the root of the repository.
143  * %u - The URL of the file.
144  * %_ - A space (keyword definitions cannot contain a literal space).
145  * %% - A literal '%'.
146  * %H - Equivalent to %P%_%r%_%d%_%a.
147  * %I - Equivalent to %b%_%r%_%d%_%a.
148  *
149  * Custom keywords are defined by appending '=' to the keyword name, followed
150  * by a string containing any combination of the format substitutions.
151  *
152  * Any of the inputs @a rev, @a url, @a date, @a author, and @a repos_root_url
153  * can be @c NULL, or @c 0 for @a date, to indicate that the information is
154  * not present. Each piece of information that is not present expands to the
155  * empty string wherever it appears in an expanded keyword value. (This can
156  * result in multiple adjacent spaces in the expansion of a multi-valued
157  * keyword such as "Id".)
158  *
159  * Hash keys are of type <tt>const char *</tt>.
160  * Hash values are of type <tt>svn_string_t *</tt>.
161  *
162  * All memory is allocated out of @a pool.
163  *
164  * @since New in 1.8.
165  */
166 svn_error_t *
167 svn_subst_build_keywords3(apr_hash_t **kw,
168  const char *keywords_string,
169  const char *rev,
170  const char *url,
171  const char *repos_root_url,
172  apr_time_t date,
173  const char *author,
174  apr_pool_t *pool);
175 
176 /** Similar to svn_subst_build_keywords3() except that it does not accept
177  * the @a repos_root_url parameter and hence supports less substitutions,
178  * and also does not support custom keyword definitions.
179  *
180  * @since New in 1.3.
181  * @deprecated Provided for backward compatibility with the 1.7 API.
182  */
184 svn_error_t *
185 svn_subst_build_keywords2(apr_hash_t **kw,
186  const char *keywords_string,
187  const char *rev,
188  const char *url,
189  apr_time_t date,
190  const char *author,
191  apr_pool_t *pool);
192 
193 /** Similar to svn_subst_build_keywords2() except that it populates
194  * an existing structure @a *kw instead of creating a keywords hash.
195  *
196  * @deprecated Provided for backward compatibility with the 1.2 API.
197  */
199 svn_error_t *
201  const char *keywords_string,
202  const char *rev,
203  const char *url,
204  apr_time_t date,
205  const char *author,
206  apr_pool_t *pool);
207 
208 
209 /** Return @c TRUE if @a a and @a b do not hold the same keywords.
210  *
211  * @a a and @a b are hashes of the form produced by
212  * svn_subst_build_keywords2().
213  *
214  * @since New in 1.3.
215  *
216  * If @a compare_values is @c TRUE, "same" means that the @a a and @a b
217  * contain exactly the same set of keywords, and the values of corresponding
218  * keywords match as well. Else if @a compare_values is @c FALSE, then
219  * "same" merely means that @a a and @a b hold the same set of keywords,
220  * although those keywords' values might differ.
221  *
222  * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is
223  * equivalent to holding no keywords.
224  */
226 svn_subst_keywords_differ2(apr_hash_t *a,
227  apr_hash_t *b,
228  svn_boolean_t compare_values,
229  apr_pool_t *pool);
230 
231 /** Similar to svn_subst_keywords_differ2() except that it compares
232  * two @c svn_subst_keywords_t structs instead of keyword hashes.
233  *
234  * @deprecated Provided for backward compatibility with the 1.2 API.
235  */
239  const svn_subst_keywords_t *b,
240  svn_boolean_t compare_values);
241 
242 
243 /**
244  * Copy and translate the data in @a src_stream into @a dst_stream. It is
245  * assumed that @a src_stream is a readable stream and @a dst_stream is a
246  * writable stream.
247  *
248  * If @a eol_str is non-@c NULL, replace whatever bytestring @a src_stream
249  * uses to denote line endings with @a eol_str in the output. If
250  * @a src_stream has an inconsistent line ending style, then: if @a repair
251  * is @c FALSE, return @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is
252  * @c TRUE, convert any line ending in @a src_stream to @a eol_str in
253  * @a dst_stream. Recognized line endings are: "\n", "\r", and "\r\n".
254  *
255  * See svn_subst_stream_translated() for details of the keyword substitution
256  * which is controlled by the @a expand and @a keywords parameters.
257  *
258  * Note that a translation request is *required*: one of @a eol_str or
259  * @a keywords must be non-@c NULL.
260  *
261  * Notes:
262  *
263  * See svn_wc__get_keywords() and svn_wc__get_eol_style() for a
264  * convenient way to get @a eol_str and @a keywords if in libsvn_wc.
265  *
266  * @since New in 1.3.
267  *
268  * @deprecated Provided for backward compatibility with the 1.5 API.
269  * Callers should use svn_subst_stream_translated() instead.
270  */
272 svn_error_t *
274  svn_stream_t *dst_stream,
275  const char *eol_str,
276  svn_boolean_t repair,
277  apr_hash_t *keywords,
278  svn_boolean_t expand,
279  apr_pool_t *scratch_pool);
280 
281 
282 /** Similar to svn_subst_translate_stream3() except relies upon a
283  * @c svn_subst_keywords_t struct instead of a hash for the keywords.
284  *
285  * @deprecated Provided for backward compatibility with the 1.2 API.
286  */
288 svn_error_t *
290  svn_stream_t *dst_stream,
291  const char *eol_str,
292  svn_boolean_t repair,
293  const svn_subst_keywords_t *keywords,
294  svn_boolean_t expand,
295  apr_pool_t *scratch_pool);
296 
297 
298 /**
299  * Same as svn_subst_translate_stream2(), but does not take a @a pool
300  * argument, instead creates a temporary subpool of the global pool, and
301  * destroys it before returning.
302  *
303  * @deprecated Provided for backward compatibility with the 1.1 API.
304  */
306 svn_error_t *
308  svn_stream_t *dst_stream,
309  const char *eol_str,
310  svn_boolean_t repair,
311  const svn_subst_keywords_t *keywords,
312  svn_boolean_t expand);
313 
314 
315 /** Return a stream which performs eol translation and keyword
316  * expansion when read from or written to. The stream @a stream
317  * is used to read and write all data.
318  *
319  * Make sure you call svn_stream_close() on the returned stream to
320  * ensure all data is flushed and cleaned up (this will also close
321  * the provided @a stream).
322  *
323  * Read operations from and write operations to the stream
324  * perform the same operation: if @a expand is @c FALSE, both
325  * contract keywords. One stream supports both read and write
326  * operations. Reads and writes may be mixed.
327  *
328  * If @a eol_str is non-@c NULL, replace whatever bytestring the input uses
329  * to denote line endings with @a eol_str in the output. If the input has
330  * an inconsistent line ending style, then: if @a repair is @c FALSE, then a
331  * subsequent read, write or other operation on the stream will return
332  * @c SVN_ERR_IO_INCONSISTENT_EOL when the inconsistency is detected, else
333  * if @a repair is @c TRUE, convert any line ending to @a eol_str.
334  * Recognized line endings are: "\n", "\r", and "\r\n".
335  *
336  * Expand and contract keywords using the contents of @a keywords as the
337  * new values. If @a expand is @c TRUE, expand contracted keywords and
338  * re-expand expanded keywords. If @a expand is @c FALSE, contract expanded
339  * keywords and ignore contracted ones. Keywords not found in the hash are
340  * ignored (not contracted or expanded). If the @a keywords hash
341  * itself is @c NULL, keyword substitution will be altogether ignored.
342  *
343  * Detect only keywords that are no longer than @c SVN_KEYWORD_MAX_LEN
344  * bytes, including the delimiters and the keyword itself.
345  *
346  * Recommendation: if @a expand is FALSE, then you don't care about the
347  * keyword values, so use empty strings as non-NULL signifiers when you
348  * build the keywords hash.
349  *
350  * The stream returned is allocated in @a result_pool.
351  *
352  * If the inner stream implements resetting via svn_stream_reset(),
353  * or marking and seeking via svn_stream_mark() and svn_stream_seek(),
354  * the translated stream will too.
355  *
356  * @since New in 1.4.
357  */
358 svn_stream_t *
360  const char *eol_str,
361  svn_boolean_t repair,
362  apr_hash_t *keywords,
363  svn_boolean_t expand,
364  apr_pool_t *result_pool);
365 
366 
367 /** Set @a *stream to a stream which performs eol translation and keyword
368  * expansion when read from or written to. The stream @a source
369  * is used to read and write all data. Make sure you call
370  * svn_stream_close() on @a stream to make sure all data are flushed
371  * and cleaned up.
372  *
373  * When @a stream is closed, then @a source will be closed.
374  *
375  * Read and write operations perform the same transformation:
376  * all data is translated to normal form.
377  *
378  * @see svn_subst_translate_to_normal_form()
379  *
380  * @since New in 1.5.
381  * @deprecated Provided for backward compatibility with the 1.5 API.
382  */
384 svn_error_t *
386  svn_stream_t *source,
387  svn_subst_eol_style_t eol_style,
388  const char *eol_str,
389  svn_boolean_t always_repair_eols,
390  apr_hash_t *keywords,
391  apr_pool_t *pool);
392 
393 
394 /** Set @a *stream to a readable stream containing the "normal form"
395  * of the special file located at @a path. The stream will be allocated
396  * in @a result_pool, and any temporary allocations will be made in
397  * @a scratch_pool.
398  *
399  * If the file at @a path is in fact a regular file, just read its content,
400  * which should be in the "normal form" for a special file. This enables
401  * special files to be written and read on platforms that do not treat them
402  * as special.
403  *
404  * @since New in 1.6.
405  */
406 svn_error_t *
408  const char *path,
409  apr_pool_t *result_pool,
410  apr_pool_t *scratch_pool);
411 
412 
413 /** Set @a *stream to a writable stream that accepts content in
414  * the "normal form" for a special file, to be located at @a path, and
415  * will create that file when the stream is closed. The stream will be
416  * allocated in @a result_pool, and any temporary allocations will be
417  * made in @a scratch_pool.
418  *
419  * If the platform does not support the semantics of the special file, write
420  * a regular file containing the "normal form" text. This enables special
421  * files to be written and read on platforms that do not treat them as
422  * special.
423  *
424  * Note: the target file is created in a temporary location, then renamed
425  * into position, so the creation can be considered "atomic".
426  *
427  * @since New in 1.6.
428  */
429 svn_error_t *
431  const char *path,
432  apr_pool_t *result_pool,
433  apr_pool_t *scratch_pool);
434 
435 
436 /** Set @a *stream to a stream which translates the special file at @a path
437  * to the internal representation for special files when read from. When
438  * written to, it does the reverse: creating a special file when the
439  * stream is closed.
440  *
441  * @since New in 1.5.
442  *
443  * @deprecated Provided for backward compatibility with the 1.5 API.
444  * Callers should use svn_subst_read_specialfile or
445  * svn_subst_create_specialfile as appropriate.
446  */
448 svn_error_t *
450  const char *path,
451  apr_pool_t *pool);
452 
453 
454 /**
455  * Copy the contents of file-path @a src to file-path @a dst atomically,
456  * either creating @a dst or overwriting @a dst if it exists, possibly
457  * performing line ending and keyword translations.
458  *
459  * The parameters @a *eol_str, @a repair, @a *keywords and @a expand are
460  * defined the same as in svn_subst_translate_stream3().
461  *
462  * In addition, it will create a special file from normal form or
463  * translate one to normal form if @a special is @c TRUE.
464  *
465  * If anything goes wrong during the copy, attempt to delete @a dst (if
466  * it exists).
467  *
468  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
469  * copy.
470  *
471  * @a cancel_func and @a cancel_baton will be called (if not NULL)
472  * periodically to check for cancellation.
473  *
474  * @since New in 1.7.
475  */
476 svn_error_t *
477 svn_subst_copy_and_translate4(const char *src,
478  const char *dst,
479  const char *eol_str,
480  svn_boolean_t repair,
481  apr_hash_t *keywords,
482  svn_boolean_t expand,
483  svn_boolean_t special,
484  svn_cancel_func_t cancel_func,
485  void *cancel_baton,
486  apr_pool_t *pool);
487 
488 
489 /**
490  * Similar to svn_subst_copy_and_translate4() but without a cancellation
491  * function and baton.
492  *
493  * @since New in 1.3.
494  * @deprecated Provided for backward compatibility with the 1.6 API.
495  */
497 svn_error_t *
498 svn_subst_copy_and_translate3(const char *src,
499  const char *dst,
500  const char *eol_str,
501  svn_boolean_t repair,
502  apr_hash_t *keywords,
503  svn_boolean_t expand,
504  svn_boolean_t special,
505  apr_pool_t *pool);
506 
507 
508 /**
509  * Similar to svn_subst_copy_and_translate3() except that @a keywords is a
510  * @c svn_subst_keywords_t struct instead of a keywords hash.
511  *
512  * @deprecated Provided for backward compatibility with the 1.2 API.
513  * @since New in 1.1.
514  */
516 svn_error_t *
517 svn_subst_copy_and_translate2(const char *src,
518  const char *dst,
519  const char *eol_str,
520  svn_boolean_t repair,
521  const svn_subst_keywords_t *keywords,
522  svn_boolean_t expand,
523  svn_boolean_t special,
524  apr_pool_t *pool);
525 
526 /**
527  * Similar to svn_subst_copy_and_translate2() except that @a special is
528  * always set to @c FALSE.
529  *
530  * @deprecated Provided for backward compatibility with the 1.0 API.
531  */
533 svn_error_t *
534 svn_subst_copy_and_translate(const char *src,
535  const char *dst,
536  const char *eol_str,
537  svn_boolean_t repair,
538  const svn_subst_keywords_t *keywords,
539  svn_boolean_t expand,
540  apr_pool_t *pool);
541 
542 
543 /**
544  * Set @a *dst to a copy of the string @a src, possibly performing line
545  * ending and keyword translations.
546  *
547  * This is a variant of svn_subst_translate_stream3() that operates on
548  * cstrings. @see svn_subst_stream_translated() for details of the
549  * translation and of @a eol_str, @a repair, @a keywords and @a expand.
550  *
551  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
552  * copy.
553  *
554  * Allocate @a *dst in @a pool.
555  *
556  * @since New in 1.3.
557  */
558 svn_error_t *
559 svn_subst_translate_cstring2(const char *src,
560  const char **dst,
561  const char *eol_str,
562  svn_boolean_t repair,
563  apr_hash_t *keywords,
564  svn_boolean_t expand,
565  apr_pool_t *pool);
566 
567 /**
568  * Similar to svn_subst_translate_cstring2() except that @a keywords is a
569  * @c svn_subst_keywords_t struct instead of a keywords hash.
570  *
571  * @deprecated Provided for backward compatibility with the 1.2 API.
572  */
574 svn_error_t *
575 svn_subst_translate_cstring(const char *src,
576  const char **dst,
577  const char *eol_str,
578  svn_boolean_t repair,
579  const svn_subst_keywords_t *keywords,
580  svn_boolean_t expand,
581  apr_pool_t *pool);
582 
583 /**
584  * Translate the file @a src in working copy form to a file @a dst in
585  * normal form.
586  *
587  * The values specified for @a eol_style, @a *eol_str, @a keywords and
588  * @a special, should be the ones used to translate the file to its
589  * working copy form. Usually, these are the values specified by the
590  * user in the files' properties.
591  *
592  * Inconsistent line endings in the file will be automatically repaired
593  * (made consistent) for some eol styles. For all others, an error is
594  * returned. By setting @a always_repair_eols to @c TRUE, eols will be
595  * made consistent even for those styles which don't have it by default.
596  *
597  * @note To translate a file FROM normal form, use
598  * svn_subst_copy_and_translate3().
599  *
600  * @since New in 1.4
601  * @deprecated Provided for backward compatibility with the 1.5 API
602  */
604 svn_error_t *
605 svn_subst_translate_to_normal_form(const char *src,
606  const char *dst,
607  svn_subst_eol_style_t eol_style,
608  const char *eol_str,
609  svn_boolean_t always_repair_eols,
610  apr_hash_t *keywords,
611  svn_boolean_t special,
612  apr_pool_t *pool);
613 
614 /**
615  * Set @a *stream_p to a stream that detranslates the file @a src from
616  * working copy form to normal form, allocated in @a pool.
617  *
618  * The values specified for @a eol_style, @a *eol_str, @a keywords and
619  * @a special, should be the ones used to translate the file to its
620  * working copy form. Usually, these are the values specified by the
621  * user in the files' properties.
622  *
623  * Inconsistent line endings in the file will be automatically repaired
624  * (made consistent) for some eol styles. For all others, an error is
625  * returned. By setting @a always_repair_eols to @c TRUE, eols will be
626  * made consistent even for those styles which don't have it by default.
627  *
628  * @since New in 1.4.
629  *
630  * @deprecated Provided for backward compatibility with the 1.5 API.
631  * Use svn_subst_stream_from_specialfile if the source is special;
632  * otherwise, use svn_subst_stream_translated_to_normal_form.
633  */
635 svn_error_t *
637  const char *src,
638  svn_subst_eol_style_t eol_style,
639  const char *eol_str,
640  svn_boolean_t always_repair_eols,
641  apr_hash_t *keywords,
642  svn_boolean_t special,
643  apr_pool_t *pool);
644 
645 
646 /* EOL conversion and character encodings */
647 
648 /** Translate the string @a value from character encoding @a encoding to
649  * UTF8, and also from its current line-ending style to LF line-endings. If
650  * @a encoding is @c NULL, translate from the system-default encoding.
651  *
652  * If @a translated_to_utf8 is not @c NULL, then set @a *translated_to_utf8
653  * to @c TRUE if at least one character of @a value in the source character
654  * encoding was translated to UTF-8, or to @c FALSE otherwise.
655  *
656  * If @a translated_line_endings is not @c NULL, then set @a
657  * *translated_line_endings to @c TRUE if at least one line ending was
658  * changed to LF, or to @c FALSE otherwise.
659  *
660  * If @a value has an inconsistent line ending style, then: if @a repair
661  * is @c FALSE, return @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is
662  * @c TRUE, convert any line ending in @a value to "\n" in
663  * @a *new_value. Recognized line endings are: "\n", "\r", and "\r\n".
664  *
665  * Set @a *new_value to the translated string, allocated in @a result_pool.
666  *
667  * @a scratch_pool is used for temporary allocations.
668  *
669  * @since New in 1.7.
670  */
671 svn_error_t *
673  svn_boolean_t *translated_to_utf8,
674  svn_boolean_t *translated_line_endings,
675  const svn_string_t *value,
676  const char *encoding,
677  svn_boolean_t repair,
678  apr_pool_t *result_pool,
679  apr_pool_t *scratch_pool);
680 
681 /** Similar to svn_subst_translate_string2(), except that the information about
682  * whether re-encoding or line ending translation were performed is discarded.
683  *
684  * @deprecated Provided for backward compatibility with the 1.6 API.
685  */
688  const svn_string_t *value,
689  const char *encoding,
690  apr_pool_t *pool);
691 
692 /** Translate the string @a value from UTF8 and LF line-endings into native
693  * character encoding and native line-endings. If @a for_output is TRUE,
694  * translate to the character encoding of the output locale, else to that of
695  * the default locale.
696  *
697  * Set @a *new_value to the translated string, allocated in @a pool.
698  */
700  const svn_string_t *value,
701  svn_boolean_t for_output,
702  apr_pool_t *pool);
703 
704 #ifdef __cplusplus
705 }
706 #endif /* __cplusplus */
707 
708 #endif /* SVN_SUBST_H */