content: #
  # Copyright 2023 EA Authors.
  #
  # Licensed under the Apache License, Version 2.0 (the "License");
  # you may not use this file except in compliance with the License.
  # You may obtain a copy of the License at
  #
  #    https://www.apache.org/licenses/LICENSE-2.0
  #
  # Unless required by applicable law or agreed to in writing, software
  # distributed under the License is distributed on an "AS IS" BASIS,
  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  # See the License for the specific language governing permissions and
  # limitations under the License.
  #
  # Parts of this file: (c) 2022 Python Software Foundation. All right reserved.
  # License:
  #    1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
  #    the Individual or Organization ("Licensee") accessing and otherwise using Python
  #    3.10.2 software in source or binary form and its associated documentation.
  #
  #    2. Subject to the terms and conditions of this License Agreement, PSF hereby
  #    grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
  #    analyze, test, perform and/or display publicly, prepare derivative works,
  #    distribute, and otherwise use Python 3.10.2 alone or in any derivative
  #    version, provided, however, that PSF's License Agreement and PSF's notice of
  #    copyright, i.e., "Copyright © 2001-2022 Python Software Foundation; All Rights
  #    Reserved" are retained in Python 3.10.2 alone or in any derivative version
  #    prepared by Licensee.
  #
  #    3. In the event Licensee prepares a derivative work that is based on or
  #    incorporates Python 3.10.2 or any part thereof, and wants to make the
  #    derivative work available to others as provided herein, then Licensee hereby
  #    agrees to include in any such work a brief summary of the changes made to Python
  #    3.10.2.
  #
  #    4. PSF is making Python 3.10.2 available to Licensee on an "AS IS" basis.
  #    PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
  #    EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
  #    WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
  #    USE OF PYTHON 3.10.2 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
  #
  #    5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.10.2
  #    FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
  #    MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.10.2, OR ANY DERIVATIVE
  #    THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
  #
  #    6. This License Agreement will automatically terminate upon a material breach of
  #    its terms and conditions.
  #
  #    7. Nothing in this License Agreement shall be deemed to create any relationship
  #    of agency, partnership, or joint venture between PSF and Licensee.  This License
  #    Agreement does not grant permission to use PSF trademarks or trade name in a
  #    trademark sense to endorse or promote products or services of Licensee, or any
  #    third party.
  #
  #    8. By copying, installing or otherwise using Python 3.10.2, Licensee agrees
  #    to be bound by the terms and conditions of this License Agreement.
  
  """
  Parser for command line options.
  
  This module helps scripts to parse the command line arguments in
  sys.argv.  It supports the same conventions as the Unix getopt()
  function (including the special meanings of arguments of the form `-'
  and `--').  Long options similar to those supported by GNU software
  may be used as well via an optional third argument.  This module
  provides two functions and an exception:
  
  getopt() -- Parse command line options
  gnu_getopt() -- Like getopt(), but allow option and non-option arguments
  to be intermixed.
  GetoptError -- exception (class) raised with 'opt' attribute, which is the
  option involved with the exception.
  
  Adapted from https://raw.githubusercontent.com/python/cpython/2.7/Lib/getopt.py
  """
  
  import os
  
  class GetoptError(Static[Exception]):
      def __init__(self, message: str = ""):
          super().__init__("GetoptError", message)
  
  def long_has_args(opt: str, longopts: List[str]) -> Tuple[bool, str]:
      possibilities = [o for o in longopts if o.startswith(opt)]
      if not possibilities:
          raise GetoptError(f"option --{opt} not recognized")
      # Is there an exact match?
      if opt in possibilities:
          return False, opt
      elif opt + "=" in possibilities:
          return True, opt
      # No exact match, so better be unique.
      if len(possibilities) > 1:
          # XXX since possibilities contains all valid continuations, might be
          # nice to work them into the error msg
          raise GetoptError(f"option --{opt} not a unique prefix")
      assert len(possibilities) == 1
      unique_match = possibilities[0]
      has_arg = unique_match.endswith("=")
      if has_arg:
          unique_match = unique_match[:-1]
      return has_arg, unique_match
  
  def do_longs(
      opts: List[Tuple[str, str]], opt: str, longopts: List[str], args: List[str]
  ) -> Tuple[List[Tuple[str, str]], List[str]]:
      optarg = ""
      try:
          i = opt.index("=")
          opt, optarg = opt[:i], opt[i + 1 :]
      except ValueError:
          pass
  
      has_arg, opt = long_has_args(opt, longopts)
      if has_arg:
          if optarg == "":
              if not args:
                  raise GetoptError(f"option --{opt} requires argument")
              optarg, args = args[0], args[1:]
      elif optarg != "":
          raise GetoptError(f"option --{opt} must not have an argument")
      opts.append((f"--{opt}", optarg))
      return opts, args
  
  def short_has_arg(opt: str, shortopts: str) -> bool:
      for i in range(len(shortopts)):
          if opt == shortopts[i] != ":":
              return shortopts.startswith(":", i + 1)
      raise GetoptError(f"option -{opt} not recognized")
  
  def do_shorts(
      opts: List[Tuple[str, str]], optstring: str, shortopts: str, args: List[str]
  ) -> Tuple[List[Tuple[str, str]], List[str]]:
      while optstring != "":
          opt, optstring = optstring[0], optstring[1:]
          optarg = ""
          if short_has_arg(opt, shortopts):
              if optstring == "":
                  if not args:
                      raise GetoptError(f"option -{opt} requires argument")
                  optstring, args = args[0], args[1:]
              optarg, optstring = optstring, ""
          opts.append((f"-{opt}", optarg))
      return opts, args
  
  def getopt(
      args: List[str], shortopts: str, longopts: List[str] = []
  ) -> Tuple[List[Tuple[str, str]], List[str]]:
      """
      Parses command line options and parameter list.  args is the
      argument list to be parsed, without the leading reference to the
      running program.  Typically, this means "sys.argv[1:]".  shortopts
      is the string of option letters that the script wants to
      recognize, with options that require an argument followed by a
      colon (i.e., the same format that Unix getopt() uses).  If
      specified, longopts is a list of strings with the names of the
      long options which should be supported.  The leading '--'
      characters should not be included in the option name.  Options
      which require an argument should be followed by an equal sign
      ('=').
  
      The return value consists of two elements: the first is a list of
      (option, value) pairs; the second is the list of program arguments
      left after the option list was stripped (this is a trailing slice
      of the first argument).  Each option-and-value pair returned has
      the option as its first element, prefixed with a hyphen (e.g.,
      '-x'), and the option argument as its second element, or an empty
      string if the option has no argument.  The options occur in the
      list in the same order in which they were found, thus allowing
      multiple occurrences.  Long and short options may be mixed.
  
      NOTES:
      This function works like the above-mentioned getopt(), except that GNU style scanning
      mode is used by default. This means that option and non-option
      arguments may be intermixed. The getopt() function stops
      processing options as soon as a non-option argument is
      encountered.
      If the first character of the option string is `+', or if the
      environment variable POSIXLY_CORRECT is set, then option
      processing stops as soon as a non-option argument is encountered.
      """
  
      opts = []
      prog_args = []
  
      # Allow options after non-option arguments?
      all_options_first = False
      if shortopts.startswith("+"):
          shortopts = shortopts[1:]
          all_options_first = True
      elif "POSIXLY_CORRECT" in os.environ:
          all_options_first = True
  
      while args:
          if args[0] == "--":
              prog_args += args[1:]
              break
  
          if args[0][:2] == "--":
              opts, args = do_longs(opts, args[0][2:], longopts, args[1:])
          elif args[0][:1] == "-" and args[0] != "-":
              opts, args = do_shorts(opts, args[0][1:], shortopts, args[1:])
          else:
              if all_options_first:
                  prog_args += args
                  break
              else:
                  prog_args.append(args[0])
                  args = args[1:]
  
      return opts, prog_args
  