gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/RuntimeMetaData.h

   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