1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
/* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
* Use of this file is governed by the BSD 3-clause license that
* can be found in the LICENSE.txt file in the project root.
*/
#pragma once
#include "antlr4-common.h"
namespace antlr4 {
/// <summary>
/// This class provides access to the current version of the ANTLR 4 runtime
/// library as compile-time and runtime constants, along with methods for
/// checking for matching version numbers and notifying listeners in the case
/// where a version mismatch is detected.
///
/// <para>
/// The runtime version information is provided by <seealso cref="#VERSION"/> and
/// <seealso cref="#getRuntimeVersion()"/>. Detailed information about these values is
/// provided in the documentation for each member.</para>
///
/// <para>
/// The runtime version check is implemented by <seealso cref="#checkVersion"/>. Detailed
/// information about incorporating this call into user code, as well as its use
/// in generated code, is provided in the documentation for the method.</para>
///
/// <para>
/// Version strings x.y and x.y.z are considered "compatible" and no error
/// would be generated. Likewise, version strings x.y-SNAPSHOT and x.y.z are
/// considered "compatible" because the major and minor components x.y
/// are the same in each.</para>
///
/// <para>
/// To trap any error messages issued by this code, use System.setErr()
/// in your main() startup code.
/// </para>
///
/// @since 4.3
/// </summary>
class ANTLR4CPP_PUBLIC RuntimeMetaData {
public:
/// A compile-time constant containing the current version of the ANTLR 4
/// runtime library.
///
/// <para>
/// This compile-time constant value allows generated parsers and other
/// libraries to include a literal reference to the version of the ANTLR 4
/// runtime library the code was compiled against. At each release, we
/// change this value.</para>
///
/// <para>Version numbers are assumed to have the form
///
/// <em>major</em>.<em>minor</em>.<em>patch</em>.<em>revision</em>-<em>suffix</em>,
///
/// with the individual components defined as follows.</para>
///
/// <ul>
/// <li><em>major</em> is a required non-negative integer, and is equal to
/// {@code 4} for ANTLR 4.</li>
/// <li><em>minor</em> is a required non-negative integer.</li>
/// <li><em>patch</em> is an optional non-negative integer. When
/// <em>patch</em> is omitted, the {@code .} (dot) appearing before it is
/// also omitted.</li>
/// <li><em>revision</em> is an optional non-negative integer, and may only
/// be included when <em>patch</em> is also included. When <em>revision</em>
/// is omitted, the {@code .} (dot) appearing before it is also omitted.</li>
/// <li><em>suffix</em> is an optional string. When <em>suffix</em> is
/// omitted, the {@code -} (hyphen-minus) appearing before it is also
/// omitted.</li>
/// </ul>
static const std::string VERSION;
/// <summary>
/// Gets the currently executing version of the ANTLR 4 runtime library.
///
/// <para>
/// This method provides runtime access to the <seealso cref="#VERSION"/> field, as
/// opposed to directly referencing the field as a compile-time constant.</para>
/// </summary>
/// <returns> The currently executing version of the ANTLR 4 library </returns>
static std::string getRuntimeVersion();
/// <summary>
/// This method provides the ability to detect mismatches between the version
/// of ANTLR 4 used to generate a parser, the version of the ANTLR runtime a
/// parser was compiled against, and the version of the ANTLR runtime which
/// is currently executing.
///
/// <para>
/// The version check is designed to detect the following two specific
/// scenarios.</para>
///
/// <ul>
/// <li>The ANTLR Tool version used for code generation does not match the
/// currently executing runtime version.</li>
/// <li>The ANTLR Runtime version referenced at the time a parser was
/// compiled does not match the currently executing runtime version.</li>
/// </ul>
///
/// <para>
/// Starting with ANTLR 4.3, the code generator emits a call to this method
/// using two constants in each generated lexer and parser: a hard-coded
/// constant indicating the version of the tool used to generate the parser
/// and a reference to the compile-time constant <seealso cref="#VERSION"/>. At
/// runtime, this method is called during the initialization of the generated
/// parser to detect mismatched versions, and notify the registered listeners
/// prior to creating instances of the parser.</para>
///
/// <para>
/// This method does not perform any detection or filtering of semantic
/// changes between tool and runtime versions. It simply checks for a
/// version match and emits an error to stderr if a difference
/// is detected.</para>
///
/// <para>
/// Note that some breaking changes between releases could result in other
/// types of runtime exceptions, such as a <seealso cref="LinkageError"/>, prior to
/// calling this method. In these cases, the underlying version mismatch will
/// not be reported here. This method is primarily intended to
/// notify users of potential semantic changes between releases that do not
/// result in binary compatibility problems which would be detected by the
/// class loader. As with semantic changes, changes that break binary
/// compatibility between releases are mentioned in the release notes
/// accompanying the affected release.</para>
///
/// <para>
/// <strong>Additional note for target developers:</strong> The version check
/// implemented by this class is designed to address specific compatibility
/// concerns that may arise during the execution of Java applications. Other
/// targets should consider the implementation of this method in the context
/// of that target's known execution environment, which may or may not
/// resemble the design provided for the Java target.</para>
/// </summary>
/// <param name="generatingToolVersion"> The version of the tool used to generate a parser.
/// This value may be null when called from user code that was not generated
/// by, and does not reference, the ANTLR 4 Tool itself. </param>
/// <param name="compileTimeVersion"> The version of the runtime the parser was
/// compiled against. This should always be passed using a direct reference
/// to <seealso cref="#VERSION"/>. </param>
static void checkVersion(const std::string &generatingToolVersion, const std::string &compileTimeVersion);
/// <summary>
/// Gets the major and minor version numbers from a version string. For
/// details about the syntax of the input {@code version}.
/// E.g., from x.y.z return x.y.
/// </summary>
/// <param name="version"> The complete version string. </param>
/// <returns> A string of the form <em>major</em>.<em>minor</em> containing
/// only the major and minor components of the version string. </returns>
static std::string getMajorMinorVersion(const std::string &version);
};
} // namespace antlr4
|
