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