VirtualBox

source: vbox/trunk/src/bldprogs/scm.h@ 106061

Last change on this file since 106061 was 106061, checked in by vboxsync, 8 weeks ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.0 KB
Line 
1/* $Id: scm.h 106061 2024-09-16 14:03:52Z vboxsync $ */
2/** @file
3 * IPRT Testcase / Tool - Source Code Massager.
4 */
5
6/*
7 * Copyright (C) 2010-2024 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * SPDX-License-Identifier: GPL-3.0-only
26 */
27
28#ifndef VBOX_INCLUDED_SRC_bldprogs_scm_h
29#define VBOX_INCLUDED_SRC_bldprogs_scm_h
30#ifndef RT_WITHOUT_PRAGMA_ONCE
31# pragma once
32#endif
33
34#include "scmstream.h"
35
36RT_C_DECLS_BEGIN
37
38/** Pointer to the rewriter state. */
39typedef struct SCMRWSTATE *PSCMRWSTATE;
40/** Pointer to const massager settings. */
41typedef struct SCMSETTINGSBASE const *PCSCMSETTINGSBASE;
42
43
44/** @name Subversion Access
45 * @{ */
46
47/**
48 * SVN property.
49 */
50typedef struct SCMSVNPROP
51{
52 /** The property. */
53 char *pszName;
54 /** The value.
55 * When used to record updates, this can be set to NULL to trigger the
56 * deletion of the property. */
57 char *pszValue;
58} SCMSVNPROP;
59/** Pointer to a SVN property. */
60typedef SCMSVNPROP *PSCMSVNPROP;
61/** Pointer to a const SVN property. */
62typedef SCMSVNPROP const *PCSCMSVNPROP;
63
64
65void ScmSvnInit(void);
66void ScmSvnTerm(void);
67bool ScmSvnIsDirInWorkingCopy(const char *pszDir);
68bool ScmSvnIsInWorkingCopy(PSCMRWSTATE pState);
69int ScmSvnQueryProperty(PSCMRWSTATE pState, const char *pszName, char **ppszValue);
70int ScmSvnQueryParentProperty(PSCMRWSTATE pState, const char *pszName, char **ppszValue);
71int ScmSvnSetProperty(PSCMRWSTATE pState, const char *pszName, const char *pszValue);
72int ScmSvnDelProperty(PSCMRWSTATE pState, const char *pszName);
73int ScmSvnDisplayChanges(PSCMRWSTATE pState);
74int ScmSvnApplyChanges(PSCMRWSTATE pState);
75
76/** @} */
77
78
79/** @name Code Parsing
80 * @{ */
81
82/**
83 * Comment style.
84 */
85typedef enum SCMCOMMENTSTYLE
86{
87 kScmCommentStyle_Invalid = 0,
88 kScmCommentStyle_C,
89 kScmCommentStyle_Hash,
90 kScmCommentStyle_Python, /**< Same as hash, except for copyright/license. */
91 kScmCommentStyle_Semicolon,
92 kScmCommentStyle_Rem_Upper,
93 kScmCommentStyle_Rem_Lower,
94 kScmCommentStyle_Rem_Camel,
95 kScmCommentStyle_Sql,
96 kScmCommentStyle_Tick,
97 kScmCommentStyle_Xml,
98 kScmCommentStyle_End
99} SCMCOMMENTSTYLE;
100
101/**
102 * Comment types.
103 */
104typedef enum SCMCOMMENTTYPE
105{
106 kScmCommentType_Invalid = 0, /**< Customary invalid zero value. */
107 kScmCommentType_Line, /**< Line comment. */
108 kScmCommentType_Line_JavaDoc, /**< Line comment, JavaDoc style. */
109 kScmCommentType_Line_JavaDoc_After, /**< Line comment, JavaDoc after-member style. */
110 kScmCommentType_Line_Qt, /**< Line comment, JavaDoc style. */
111 kScmCommentType_Line_Qt_After, /**< Line comment, JavaDoc after-member style. */
112 kScmCommentType_MultiLine, /**< Multi-line comment (e.g. ansi C). */
113 kScmCommentType_MultiLine_JavaDoc, /**< Multi-line comment, JavaDoc style. */
114 kScmCommentType_MultiLine_JavaDoc_After, /**< Multi-line comment, JavaDoc after-member style. */
115 kScmCommentType_MultiLine_Qt, /**< Multi-line comment, Qt style. */
116 kScmCommentType_MultiLine_Qt_After, /**< Multi-line comment, Qt after-member style. */
117 kScmCommentType_DocString, /**< Triple quoted python doc string. */
118 kScmCommentType_Xml, /**< XML comment style. */
119 kScmCommentType_End /**< Customary exclusive end value. */
120} SCMCOMMENTTYPE;
121
122
123/**
124 * Comment information.
125 */
126typedef struct SCMCOMMENTINFO
127{
128 /** Comment type. */
129 SCMCOMMENTTYPE enmType;
130 /** Start line number (0-based). */
131 uint32_t iLineStart;
132 /** Start line offset (0-based). */
133 uint32_t offStart;
134 /** End line number (0-based). */
135 uint32_t iLineEnd;
136 /** End line offset (0-based). */
137 uint32_t offEnd;
138 /** Number of blank lines before the body (@a pszBody). */
139 uint32_t cBlankLinesBefore;
140 /** Number of blank lines after the body (@a pszBody + @a cchBody). */
141 uint32_t cBlankLinesAfter;
142 /** @todo add min/max indent. Raw length. Etc. */
143} SCMCOMMENTINFO;
144/** Pointer to comment info. */
145typedef SCMCOMMENTINFO *PSCMCOMMENTINFO;
146/** Pointer to const comment info. */
147typedef SCMCOMMENTINFO const *PCSCMCOMMENTINFO;
148
149
150/**
151 * Comment enumeration callback function.
152 *
153 * @returns IPRT style status code. Failures causes immediate return. While an
154 * informational status code is saved (first one) and returned later.
155 * @param pInfo Additional comment info.
156 * @param pszBody The comment body. This is somewhat stripped.
157 * @param cchBody The comment body length.
158 * @param pvUser User callback argument.
159 */
160typedef DECLCALLBACKTYPE(int, FNSCMCOMMENTENUMERATOR,(PCSCMCOMMENTINFO pInfo, const char *pszBody, size_t cchBody, void *pvUser));
161/** Poiter to a omment enumeration callback function. */
162typedef FNSCMCOMMENTENUMERATOR *PFNSCMCOMMENTENUMERATOR;
163
164int ScmEnumerateComments(PSCMSTREAM pIn, SCMCOMMENTSTYLE enmCommentStyle, PFNSCMCOMMENTENUMERATOR pfnCallback, void *pvUser);
165
166
167/**
168 * Include directive type.
169 */
170typedef enum SCMINCLUDEDIR
171{
172 kScmIncludeDir_Invalid = 0, /**< Constomary invalid enum value. */
173 kScmIncludeDir_Quoted, /**< \#include \"filename.h\" */
174 kScmIncludeDir_Bracketed, /**< \#include \<filename.h\> */
175 kScmIncludeDir_Macro, /**< \#include MACRO_H */
176 kScmIncludeDir_End /**< End of valid enum values. */
177} SCMINCLUDEDIR;
178
179SCMINCLUDEDIR ScmMaybeParseCIncludeLine(PSCMRWSTATE pState, const char *pchLine, size_t cchLine,
180 const char **ppchFilename, size_t *pcchFilename);
181
182/**
183 * Checks if the given character is a valid C identifier lead character.
184 *
185 * @returns true / false.
186 * @param ch The character to inspect.
187 * @sa vbcppIsCIdentifierLeadChar
188 */
189DECLINLINE(bool) ScmIsCIdentifierLeadChar(char ch)
190{
191 return RT_C_IS_ALPHA(ch)
192 || ch == '_';
193}
194
195
196/**
197 * Checks if the given character is a valid C identifier character.
198 *
199 * @returns true / false.
200 * @param ch The character to inspect.
201 * @sa vbcppIsCIdentifierChar
202 */
203DECLINLINE(bool) ScmIsCIdentifierChar(char ch)
204{
205 return RT_C_IS_ALNUM(ch)
206 || ch == '_';
207}
208
209size_t ScmCalcSpacesForSrcSpan(const char *pchLine, size_t offStart, size_t offEnd, PCSCMSETTINGSBASE pSettings);
210
211/** @} */
212
213
214/** @name Rewriters
215 * @{ */
216
217/**
218 * Rewriter state.
219 */
220typedef struct SCMRWSTATE
221{
222 /** The filename. */
223 const char *pszFilename;
224 /** Set after the printing the first verbose message about a file under
225 * rewrite. */
226 bool fFirst;
227 /** Set if the file requires manual repair. */
228 bool fNeedsManualRepair;
229 /** Cached ScmSvnIsInWorkingCopy response. 0 indicates not known, 1 means it
230 * is in WC, -1 means it doesn't. */
231 int8_t fIsInSvnWorkingCopy;
232 /** The number of SVN property changes. */
233 size_t cSvnPropChanges;
234 /** Pointer to an array of SVN property changes. */
235 struct SCMSVNPROP *paSvnPropChanges;
236 /** For error propagation. */
237 int32_t rc;
238} SCMRWSTATE;
239
240/** Rewriter result. */
241typedef enum { kScmUnmodified = 0, kScmModified, kScmMaybeModified } SCMREWRITERRES;
242
243/**
244 * A rewriter.
245 *
246 * This works like a stream editor, reading @a pIn, modifying it and writing it
247 * to @a pOut.
248 *
249 * @returns kScmUnmodified, kScmModified or kScmMaybeModified.
250 * @param pIn The input stream.
251 * @param pOut The output stream.
252 * @param pSettings The settings.
253 */
254typedef SCMREWRITERRES FNSCMREWRITER(PSCMRWSTATE pState, PSCMSTREAM pIn, PSCMSTREAM pOut, PCSCMSETTINGSBASE pSettings);
255/** Pointer to a rewriter method. */
256typedef FNSCMREWRITER *PFNSCMREWRITER;
257
258FNSCMREWRITER rewrite_StripTrailingBlanks;
259FNSCMREWRITER rewrite_ExpandTabs;
260FNSCMREWRITER rewrite_ForceNativeEol;
261FNSCMREWRITER rewrite_ForceLF;
262FNSCMREWRITER rewrite_ForceCRLF;
263FNSCMREWRITER rewrite_AdjustTrailingLines;
264FNSCMREWRITER rewrite_SvnNoExecutable;
265FNSCMREWRITER rewrite_SvnNoKeywords;
266FNSCMREWRITER rewrite_SvnNoEolStyle;
267FNSCMREWRITER rewrite_SvnBinary;
268FNSCMREWRITER rewrite_SvnKeywords;
269FNSCMREWRITER rewrite_SvnSyncProcess;
270FNSCMREWRITER rewrite_UnicodeChecks;
271FNSCMREWRITER rewrite_PageChecks;
272FNSCMREWRITER rewrite_ForceHrcVrcInsteadOfRc;
273FNSCMREWRITER rewrite_Copyright_CstyleComment;
274FNSCMREWRITER rewrite_Copyright_HashComment;
275FNSCMREWRITER rewrite_Copyright_PythonComment;
276FNSCMREWRITER rewrite_Copyright_RemComment;
277FNSCMREWRITER rewrite_Copyright_SemicolonComment;
278FNSCMREWRITER rewrite_Copyright_SqlComment;
279FNSCMREWRITER rewrite_Copyright_TickComment;
280FNSCMREWRITER rewrite_Copyright_XmlComment;
281FNSCMREWRITER rewrite_Makefile_kup;
282FNSCMREWRITER rewrite_Makefile_kmk;
283FNSCMREWRITER rewrite_FixFlowerBoxMarkers;
284FNSCMREWRITER rewrite_Fix_C_and_CPP_Todos;
285FNSCMREWRITER rewrite_Fix_Err_H;
286FNSCMREWRITER rewrite_FixHeaderGuards;
287FNSCMREWRITER rewrite_C_and_CPP;
288
289/**
290 * Rewriter configuration.
291 */
292typedef struct SCMREWRITERCFG
293{
294 /** The rewriter function. */
295 PFNSCMREWRITER pfnRewriter;
296 /** The name of the rewriter. */
297 const char *pszName;
298} SCMREWRITERCFG;
299/** Pointer to a const rewriter config. */
300typedef SCMREWRITERCFG const *PCSCMREWRITERCFG;
301
302/** @} */
303
304
305/** @name Settings
306 * @{ */
307
308/**
309 * Configuration entry.
310 */
311typedef struct SCMCFGENTRY
312{
313 /** Number of rewriters. */
314 size_t cRewriters;
315 /** Pointer to an array of rewriters. */
316 PCSCMREWRITERCFG const *paRewriters;
317 /** Set if the entry handles binaries. */
318 bool fBinary;
319 /** File pattern (simple). */
320 const char *pszFilePattern;
321 /** Name (for treat as). */
322 const char *pszName;
323} SCMCFGENTRY;
324typedef SCMCFGENTRY *PSCMCFGENTRY;
325typedef SCMCFGENTRY const *PCSCMCFGENTRY;
326
327
328/** License update options. */
329typedef enum SCMLICENSE
330{
331 kScmLicense_LeaveAlone = 0, /**< Leave it alone. */
332 kScmLicense_OseGpl, /**< VBox OSE GPL if public. */
333 kScmLicense_OseDualGplCddl, /**< VBox OSE dual GPL & CDDL if public. */
334 kScmLicense_OseCddl, /**< VBox OSE CDDL if public. */
335 kScmLicense_Lgpl, /**< LGPL if public. */
336 kScmLicense_Mit, /**< MIT if public. */
337 kScmLicense_BasedOnMit, /**< Copyright us but based on someone else's MIT. */
338 kScmLicense_End
339} SCMLICENSE;
340
341/**
342 * Source Code Massager Settings.
343 */
344typedef struct SCMSETTINGSBASE
345{
346 bool fConvertEol;
347 bool fConvertTabs;
348 bool fForceFinalEol;
349 bool fForceTrailingLine;
350 bool fStripTrailingBlanks;
351 bool fStripTrailingLines;
352
353 /** Whether to fix C/C++ flower box section markers. */
354 bool fFixFlowerBoxMarkers;
355 /** The minimum number of blank lines we want before flowerbox markers. */
356 uint8_t cMinBlankLinesBeforeFlowerBoxMakers;
357
358 /** Whether to fix C/C++ header guards and \#pragma once directives. */
359 bool fFixHeaderGuards;
360 /** Whether to include a pragma once statement with the header guard. */
361 bool fPragmaOnce;
362 /** Whether to fix the \#endif part of a header guard. */
363 bool fFixHeaderGuardEndif;
364 /** Whether to add a comment on the \#endif part of the header guard. */
365 bool fEndifGuardComment;
366 /** The guard name prefix. */
367 char *pszGuardPrefix;
368 /** Header guards should be normalized using prefix and this directory.
369 * When NULL the guard identifiers found in the header is preserved. */
370 char *pszGuardRelativeToDir;
371
372 /** Whether to fix C/C++ todos. */
373 bool fFixTodos;
374 /** Whether to fix C/C++ err.h/errcore.h usage. */
375 bool fFixErrH;
376 /** No PAGE_SIZE, PAGE_SHIFT, PAGE_OFFSET_MASK allowed in C/C++, only the GUEST_
377 * or HOST_ prefixed versions. */
378 bool fOnlyGuestHostPage;
379 /** No ASMMemIsZeroPage or ASMMemZeroPage calls allowed (C/C++). */
380 bool fNoASMMemPageUse;
381 /** No rc declarations allowed, only hrc or vrc depending on the result type. */
382 bool fOnlyHrcVrcInsteadOfRc;
383
384 /** Whether to standarize kmk makefiles. */
385 bool fStandarizeKmk;
386
387 /** Update the copyright year. */
388 bool fUpdateCopyrightYear;
389 /** Only external copyright holders. */
390 bool fExternalCopyright;
391 /** Whether there should be a LGPL disclaimer. */
392 bool fLgplDisclaimer;
393 /** How to update the license. */
394 SCMLICENSE enmUpdateLicense;
395
396 /** Only process files that are part of a SVN working copy. */
397 bool fOnlySvnFiles;
398 /** Only recurse into directories containing an .svn dir. */
399 bool fOnlySvnDirs;
400 /** Set svn:eol-style if missing or incorrect. */
401 bool fSetSvnEol;
402 /** Set svn:executable according to type (unusually this means deleting it). */
403 bool fSetSvnExecutable;
404 /** Set svn:keyword if completely or partially missing. */
405 bool fSetSvnKeywords;
406 /** Skip checking svn:sync-process. */
407 bool fSkipSvnSyncProcess;
408 /** Skip the unicode checks. */
409 bool fSkipUnicodeChecks;
410 /** Tab size. */
411 uint8_t cchTab;
412 /** Optimal source code width. */
413 uint8_t cchWidth;
414 /** Free the treat as structure. */
415 bool fFreeTreatAs;
416 /** Prematched config entry. */
417 PCSCMCFGENTRY pTreatAs;
418 /** Only consider files matching these patterns. This is only applied to the
419 * base names. */
420 char *pszFilterFiles;
421 /** Filter out files matching the following patterns. This is applied to base
422 * names as well as the absolute paths. */
423 char *pszFilterOutFiles;
424 /** Filter out directories matching the following patterns. This is applied
425 * to base names as well as the absolute paths. All absolute paths ends with a
426 * slash and dot ("/."). */
427 char *pszFilterOutDirs;
428} SCMSETTINGSBASE;
429/** Pointer to massager settings. */
430typedef SCMSETTINGSBASE *PSCMSETTINGSBASE;
431
432/**
433 * File/dir pattern + options.
434 */
435typedef struct SCMPATRNOPTPAIR
436{
437 char *pszPattern;
438 char *pszOptions;
439 char *pszRelativeTo;
440 bool fMultiPattern;
441} SCMPATRNOPTPAIR;
442/** Pointer to a pattern + option pair. */
443typedef SCMPATRNOPTPAIR *PSCMPATRNOPTPAIR;
444
445
446/** Pointer to a settings set. */
447typedef struct SCMSETTINGS *PSCMSETTINGS;
448/**
449 * Settings set.
450 *
451 * This structure is constructed from the command line arguments or any
452 * .scm-settings file found in a directory we recurse into. When recursing in
453 * and out of a directory, we push and pop a settings set for it.
454 *
455 * The .scm-settings file has two kinds of setttings, first there are the
456 * unqualified base settings and then there are the settings which applies to a
457 * set of files or directories. The former are lines with command line options.
458 * For the latter, the options are preceded by a string pattern and a colon.
459 * The pattern specifies which files (and/or directories) the options applies
460 * to.
461 *
462 * We parse the base options into the Base member and put the others into the
463 * paPairs array.
464 */
465typedef struct SCMSETTINGS
466{
467 /** Pointer to the setting file below us in the stack. */
468 PSCMSETTINGS pDown;
469 /** Pointer to the setting file above us in the stack. */
470 PSCMSETTINGS pUp;
471 /** File/dir patterns and their options. */
472 PSCMPATRNOPTPAIR paPairs;
473 /** The number of entires in paPairs. */
474 uint32_t cPairs;
475 /** The base settings that was read out of the file. */
476 SCMSETTINGSBASE Base;
477} SCMSETTINGS;
478/** Pointer to a const settings set. */
479typedef SCMSETTINGS const *PCSCMSETTINGS;
480
481/** @} */
482
483
484void ScmVerboseBanner(PSCMRWSTATE pState, int iLevel);
485void ScmVerbose(PSCMRWSTATE pState, int iLevel, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
486SCMREWRITERRES ScmError(PSCMRWSTATE pState, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
487bool ScmFixManually(PSCMRWSTATE pState, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
488bool ScmFixManuallyV(PSCMRWSTATE pState, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
489
490extern const char g_szTabSpaces[16+1];
491extern const char g_szAsterisks[255+1];
492extern const char g_szSpaces[255+1];
493extern uint32_t g_uYear;
494
495RT_C_DECLS_END
496
497#endif /* !VBOX_INCLUDED_SRC_bldprogs_scm_h */
498
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette