Subversion
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
subversion
include
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 */
51
svn_subst_eol_style_unknown
,
52
53
/** EOL translation is "off" or ignored value */
54
svn_subst_eol_style_none
,
55
56
/** Translation is set to client's native eol */
57
svn_subst_eol_style_native
,
58
59
/** Translation is set to one of LF, CR, CRLF */
60
svn_subst_eol_style_fixed
61
62
}
svn_subst_eol_style_t
;
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
80
svn_subst_eol_style_from_value
(
svn_subst_eol_style_t
*style,
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
*/
92
svn_boolean_t
93
svn_subst_translation_required
(
svn_subst_eol_style_t
style,
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
/** @} */
118
}
svn_subst_keywords_t
;
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
*/
150
SVN_DEPRECATED
151
svn_error_t
*
152
svn_subst_build_keywords
(
svn_subst_keywords_t
*kw,
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
*/
177
svn_boolean_t
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
*/
188
SVN_DEPRECATED
189
svn_boolean_t
190
svn_subst_keywords_differ
(
const
svn_subst_keywords_t
*a,
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
*/
233
SVN_DEPRECATED
234
svn_error_t
*
235
svn_subst_translate_stream3
(
svn_stream_t
*src_stream,
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
*/
249
SVN_DEPRECATED
250
svn_error_t
*
251
svn_subst_translate_stream2
(
svn_stream_t
*src_stream,
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
*/
267
SVN_DEPRECATED
268
svn_error_t
*
269
svn_subst_translate_stream
(
svn_stream_t
*src_stream,
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
*
295
svn_subst_stream_translated
(
svn_stream_t
*stream,
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
*/
319
SVN_DEPRECATED
320
svn_error_t
*
321
svn_subst_stream_translated_to_normal_form
(
svn_stream_t
**stream,
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
*
338
svn_subst_read_specialfile
(
svn_stream_t
**stream,
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
*
353
svn_subst_create_specialfile
(
svn_stream_t
**stream,
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
*/
370
SVN_DEPRECATED
371
svn_error_t
*
372
svn_subst_stream_from_specialfile
(
svn_stream_t
**stream,
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
*/
414
SVN_DEPRECATED
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
*/
431
SVN_DEPRECATED
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
*/
470
SVN_DEPRECATED
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
*/
500
SVN_DEPRECATED
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
*/
531
SVN_DEPRECATED
532
svn_error_t
*
533
svn_subst_stream_detranslated
(
svn_stream_t
**stream_p,
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
*/
550
svn_error_t
*
svn_subst_translate_string
(
svn_string_t
**new_value,
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
*/
560
svn_error_t
*
svn_subst_detranslate_string
(
svn_string_t
**new_value,
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 */
Generated on Sat Apr 30 2016 03:37:52 for Subversion by
1.8.1.2