package require Eagle.Library

  #
  # NOTE: This procedure returns a formatted, possibly version-specific,
  #       package name, for use in logging.
  #
  proc formatPackageName { package version } {
    return [string trim [appendArgs $package " " $version]]

  }

  #
  # NOTE: This procedure returns a formatted script result.  If the string
  #       result is empty, only the return code is used.  The code argument
  #       must be an integer Tcl return code (e.g. from [catch]) and the
  #       result argument is the script result or error message.

  #
  # NOTE: This procedure accepts a package requirement (spec) and returns
  #       a simple package version, if possible.  An empty string will be
  #       returned, if appropriate (i.e. any version should be allowed).
  #       The requirement argument must be a package specification that
  #       conforms to TIP #268.
  #
  proc packageRequirementToVersion { requirement } {
    set result $requirement

    if {[set index [string first - $result]] != -1} then {
      incr index -1; set result [string range $result 0 $index]
    }

    if {[set index [string first a $result]] != -1 || \
        [set index [string first b $result]] != -1} then {
      incr index -1; set result [string range $result 0 $index]
    }

    if {$result eq "0"} then {
      set result ""
    } elseif {[regexp -- {^\d+$} $result]} then {
      append result .0
    }

    return $result
  }

  #
  # NOTE: This procedure issues an HTTP request that should return metadata
  #       that can be used to load and/or provide the specified package.
  #       The apiKey argument is the API key to use -OR- an empty string if
  #       a public package is being looked up.  The package argument is the

    #
    # NOTE: The code must be the literal string "OK" for the package lookup
    #       request to be considered successful.
    #
    return [expr {$code eq "OK"}]
  }

  #
  # NOTE: This procedure was stolen from the "common.tcl" script used by the
  #       package repository server.  It has been modified to support both
  #       native Tcl and Eagle.  It should be noted here that TIP #268 syntax
  #       is not supported by Eagle.  For native Tcl, the requirement argument
  #       must be a package version or requirement conforming to the TIP #268
  #       syntax.  For Eagle, the requirement argument must be a simple dotted
  #       package version, with up to four components, without any 'a' or 'b'.
  #       The emptyOk argument should be non-zero if an empty string should be
  #       considered to be valid by the caller.  The rangeOk argument should
  #       be non-zero if the version range syntax is allowed; this argument is
  #       ignored for Eagle because it requires TIP #268 support.
  #
  proc isValidPackageRequirement { requirement rangeOk {emptyOk false} } {
    if {$emptyOk && [string length $requirement] == 0} then {
      return true
    }

    if {[isEagle]} then {
      #
      # NOTE: Eagle does not support TIP #268.  Use the built-in sub-command
      #       that checks a version number.
      #
      return [string is version -strict $requirement]
    } else {
      #
      # HACK: If a version range is not allowed, make sure that the dash
      #       character is not present.
      #
      if {!$rangeOk && [string first - $requirement] != -1} then {
        return false
      }

      #
      # HACK: There is no direct way to check if a package requirement
      #       that uses the TIP #268 syntax is valid; however, we can
      #       purposely "misuse" the [package present] command for this
      #       purpose.  We know the "Tcl" package is always present;
      #       therefore, if an error is raised here, then the package
      #       requirement is probably invalid.  Unfortunately, the error
      #       message text has to be checked as well; otherwise, there
      #       is no way to verify version numbers that happen to be less
      #       than the running patch level of Tcl.
      #
      if {[catch {package present Tcl $requirement} error] == 0} then {
        return true
      } else {
        #
        # TODO: Maybe this will require updates in the future?
        #
        set pattern(1) "expected version number but got *"
        set pattern(2) "expected versionMin-versionMax but got *"

        if {![string match $pattern(1) $error] && \
            ![string match $pattern(2) $error]} then {
          return true
        } else {
          return false
        }
      }
    }
  }

  #
  # NOTE: This procedure attempts to extract the package lookup metadata from
  #       the lookup result.  The result argument is the lookup result.  The
  #       varName argument is the name of an array variable, in the call frame
  #       of the immediate caller, that should receive the extracted package
  #       lookup metadata.  The caller argument must be an empty string -OR-
  #       the literal string "handler".
  #
  proc extractAndVerifyLookupMetadata { result varName caller } {
    variable strictUnknownLanguage

    #
    # NOTE: Grab the returned patch level.  It cannot be an empty string
    #       and it must conform to the TIP #268 requirements for a single
    #       package version.
    #
    set patchLevel [getDictionaryValue $result PatchLevel]

    if {[string length $patchLevel] == 0} then {
      error "missing patch level"
    }

    if {![isValidPackageRequirement $patchLevel false]} then {
      error "bad patch level"
    }

    #
    # NOTE: Grab the language for the package script.  It must be an empty
    #       string, "Tcl", or "Eagle".  If it is an empty string, "Eagle"
    #       will be assumed.
    #
    set language [getDictionaryValue $result Language]

    #
    # NOTE: If the caller wants the package lookup metadata, use their
    #       array variable name.
    #
    if {[string length $varName] > 0} then {
      upvar 1 $varName metadata

      set metadata(patchLevel) $patchLevel
      set metadata(language) $language
      set metadata(script) $script
      set metadata(certificate) $certificate
    }
  }

  #

    #
    # NOTE: If the entire package metadata array is missing, fail.
    #
    if {![info exists metadata]} then {
      error "missing metadata"
    }

    #
    # NOTE: If the patch level for the package is mising, fail.
    #
    if {![info exists metadata(patchLevel)]} then {
      error "missing patch level"
    }

    #
    # NOTE: If the language for the package script is mising, fail.
    #
    if {![info exists metadata(language)]} then {
      error "missing language"
    }

    }

    #
    # NOTE: Maybe check for the package and then optionally log results.
    #
    if {$verboseUnknownResult} then {
      set ifNeededVersion [getIfNeededVersion \
          $package [packageRequirementToVersion $version]]

      if {[string length $ifNeededVersion] > 0} then {
        set command [list package ifneeded $package $ifNeededVersion]

        if {[catch $command result(3)] == 0 && \
            [string length $result(3)] > 0} then {
          pkgLog [appendArgs \

    #
    set apiKeys [getLookupApiKeys]; lappend apiKeys ""

    foreach apiKey $apiKeys {
      #
      # NOTE: Issue the lookup request to the remote package repository.
      #
      set data [getLookupData $apiKey $package $version]


      #
      # NOTE: Attempt to grab the lookup code from the response data.
      #
      set code [getLookupCodeFromData $data]

      #