Debian Codegraph @

modules/lsp-runtime-lib/include/lsp-plug.in/expr/format.h

raw
1 /*
2 * Copyright (C) 2020 Linux Studio Plugins Project <https://lsp-plug.in/>
3 * (C) 2020 Vladimir Sadovnikov <[email protected]>
4 *
5 * This file is part of lsp-runtime-lib
6 * Created on: 25 февр. 2020 г.
7 *
8 * lsp-runtime-lib is free software: you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation, either version 3 of the License, or
11 * any later version.
12 *
13 * lsp-runtime-lib is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with lsp-runtime-lib. If not, see <https://www.gnu.org/licenses/>.
20 */
21
22 #ifndef LSP_PLUG_IN_EXPR_FORMAT_H_
23 #define LSP_PLUG_IN_EXPR_FORMAT_H_
24
25 #include <lsp-plug.in/runtime/version.h>
26 #include <lsp-plug.in/io/IOutSequence.h>
27 #include <lsp-plug.in/io/IInSequence.h>
28 #include <lsp-plug.in/expr/Parameters.h>
29
30 namespace lsp
31 {
32 namespace expr
33 {
34 /**
35 * Format string syntax:
36 * format-string: element
37 * element: { character | escape_sequence | format_specifier } [element]
38 * character: any character except '\', '{', '}'
39 * escape_sequence: '\' { '\' | '{' | '}' }
40 * format_specifier: '{' format_description '}'
41 * format_description: modifiers
42 * modifiers: { parameter_name | parameter_index | padding | alignment | type | width } [ modifiers ]
43 * parameter_name: '@' identifier_first [identifier_next]
44 * parameter_index: '[' parameter_number ']'
45 * padding: { padding_left | padding_right }
46 * alignment: { align_left | align_to_left | align_from_left | align_middle | align_from_right | align_to_right | align_right }
47 * type: '%' [ type_sign ] [ type_width ] [ type_specifier ]
48 * width: ':' decimal_digits
49 * identifier_first: any character of 'a'-'z', 'A'-'Z' and '_'
50 * identifier_next: { identifier_first | '0'-'9' } [ identifier_next ]
51 * parameter_number: decimal_digits
52 * decimal_digits: '0'-'9' [ decimal_digits ]
53 * padding_left: '^' character
54 * padding_right: '$' character
55 * character: any possible character except '\0'
56 * align_left: '<'
57 * align_to_left: '<' '|'
58 * align_from_left: '>' '|'
59 * align_middle: '|'
60 * align_from_right: '|' '<'
61 * align_to_right: '|' '>'
62 * align_right: '>'
63 * type_sign: '+'
64 * type_width: decimal_digits [ type_fraction ]
65 * type_fraction: '.' decimal_digits
66 * type_specifier: '%' { decimal_type | float_type | binary_type | octal_type | hexadecimal_type | boolean_type | string_type | text_type }
67 * decimal_type: { 'i' | 'd' | 'u' }
68 * float_type: { 'f' | 'F' | 'e' | 'E' }
69 * binary_type: 'b'
70 * octal_type: 'o'
71 * hexadecimal_type: { 'x' | 'X' }
72 * boolean_type: { 'l' | 'L' } [ { 'l' | 'L' } ]
73 * string_type: 's'
74 * text_type: { 't' | 'T' } [ { 't' | 'T' } ]
75 *
76 * Example formats:
77 * "The value with name 'x' is: {@x}"
78 * "The value with index 1 is: {[1]}"
79 * "The zero-padded integer from left is: {>^0@x}"
80 * "The hex integer from left is: {>^0@x}"
81 * "The 8-digit octal number inside of underscored field of 16 digits aligned to center: {|^_%8o:16$_}"
82 *
83 * Each format specifier can contain:
84 * Parameter reference:
85 * - named: {@parameter}
86 * - indexed: [parameter_index]
87 * Padding character specification:
88 * - preceding character: ^character
89 * - subsequent character: $character
90 * Alignment:
91 * - left alignment: <
92 * - right alignment: >
93 * - middle alignment: |
94 * - middle alignment with left offset: <|
95 * - middle alignment with right offset: |>
96 * - left alignment with 1/4 offset: |<
97 * - right alignment with 1/4 offset: >|
98 * Type specifier:
99 * - permanent sign presence flag: +
100 * - value width - minimum number of digits (including dot character for floating point values)
101 * - fraction width (number of fraction digits for floating point values)
102 * - data type specifier:
103 * - E: exponential floating point value upper-case 'INF' and 'NAN' values
104 * - F: floating point value with upper-case 'INF' and 'NAN' values
105 * - L: upper-case boolean value ('TRUE' and 'FALSE')
106 * - Ll: camel-case boolean value ('True' and 'False')
107 * - S: string (same as s)
108 * - T: text, all characters in upper-case
109 * - Tt: text, first character in upper-case, all others in lower-case
110 * - X: upper-case hexadecimal integers
111 * - b: binary integers
112 * - d: decimal integers (same to i)
113 * - e: exponential floating point value lower-case 'inf' and 'nan' values
114 * - f: floating point value with lower-case 'inf' and 'nan' values
115 * - i: decimal integers (same to d)
116 * - l: lower-case boolean value ('true' and 'false')
117 * - lL: reverse camel-case boolean value ('tRUE' and 'fALSE')
118 * - o: octal integers
119 * - s: string (same as S)
120 * - t: text, all characters in lower-case
121 * - tT: text, first character in lower-case, all others in upper-case
122 * - u: unsigned integers
123 * - x: lower-case hexadecimal integers
124 * Width specifier - the minimum number of characters to allocate for printing the value
125 *
126 */
127
128 /**
129 * Format the set of parameters provided by Resolver using input character
130 * sequence as format specifier and output the result to output character
131 * sequence
132 *
133 * @param out output character sequence
134 * @param fmt format specifier
135 * @param r parameter resolver
136 * @return status of operation
137 */
138 status_t format(io::IOutSequence *out, io::IInSequence *fmt, const Parameters *r);
139
140 /**
141 * Format the set of parameters provided by Resolver using format string
142 * and output the result to output character sequence
143 *
144 * @param out output character sequence
145 * @param fmt format specifier (UTF-8 character sequence)
146 * @param r parameter resolver
147 * @return status of operation
148 */
149 status_t format(io::IOutSequence *out, const char *fmt, const Parameters *r);
150
151 /**
152 * Format the set of parameters provided by Resolver using format string
153 * and output the result to output character sequence
154 *
155 * @param out output character sequence
156 * @param fmt format specifier
157 * @param r parameter resolver
158 * @return status of operation
159 */
160 status_t format(io::IOutSequence *out, const LSPString *fmt, const Parameters *r);
161
162 /**
163 * Format the set of parameters provided by Resolver using input character
164 * sequence as format specifier and output the result to string
165 *
166 * @param out output string
167 * @param fmt format specifier
168 * @param r parameter resolver
169 * @return status of operation
170 */
171 status_t format(LSPString *out, io::IInSequence *fmt, const Parameters *r);
172
173 /**
174 * Format the set of parameters provided by Resolver using format string
175 * and output the result to string
176 *
177 * @param out output string
178 * @param fmt format specifier (UTF-8 character sequence)
179 * @param r parameter resolver
180 * @return status of operation
181 */
182 status_t format(LSPString *out, const char *fmt, const Parameters *r);
183
184 /**
185 * Format the set of parameters provided by Resolver using format string
186 * and output the result to string
187 *
188 * @param out output string
189 * @param fmt format specifier
190 * @param r parameter resolver
191 * @return status of operation
192 */
193 status_t format(LSPString *out, const LSPString *fmt, const Parameters *r);
194 }
195 }
196
197
198 #endif /* LSP_PLUG_IN_EXPR_FORMAT_H_ */