cpp/third_party/antlr4-cpp-runtime-4/runtime/src/RuntimeMetaData.h

/* 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