#       package, even when it is being used by native Tcl.  If needed,
  #       prior to loading this package, the native Tcl auto-path should
  #       be modified to include the "Eagle1.0" directory (i.e. the one
  #       containing the Eagle core script library file "init.eagle").
  #
  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 " " [getLookupVersion $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.
  #
  proc formatResult { code result } {
    switch -exact -- $code {
      0 {set codeString ok}
      1 {set codeString error}
      2 {set codeString return}
      3 {set codeString break}
      4 {set codeString continue}
      default {set codeString [appendArgs unknown( $code )]}
    }

    if {[string length $result] > 0} then {
      return [appendArgs $codeString ": " [list $result]]
    } else {
      return $codeString
    }
  }

  #
  # NOTE: This procedure emits a message to the package repository client
  #       log.  The string argument is the content of the message to emit.
  #
  # <public>
  proc pkgLog { string } {
    catch {
      tclLog [appendArgs [pid] " : " [clock seconds] " : pkgr : " $string]
    }
  }

  #
  # NOTE: This procedure attempts to determine if a string is a valid list
  #       and returns non-zero when that is true.  The value argument is
  #       the string to check.
  #
  proc stringIsList { value } {
    if {[isEagle]} then {
      return [string is list $value]
    } else {
      global tcl_version

      if {[info exists tcl_version] && $tcl_version >= 8.5} then {
        return [string is list $value]
      } elseif {[catch {llength $value}] == 0} then {
        return true
      } else {
        return false
      }
    }
  }

  #
  # NOTE: This procedure returns non-zero if the specified string value
  #       looks like a Harpy (script) certificate.  The value argument
  #       is the string to check.
  #
  # <public>
  proc isHarpyCertificate { value } {
    if {[string length $value] == 0 || [string first [string trim {
      <Certificate xmlns="https://eagle.to/2011/harpy"
    }] $value] != -1} then {
      return true
    } else {
      return false
    }
  }

  #
  # NOTE: This procedure returns non-zero if the specified string value
  #       looks like a PGP signature.  The value argument is the string
  #       to check.
  #
  # <public>
  proc isPgpSignature { value } {
    if {[string length $value] == 0 || [string first [string trim {
      -----BEGIN PGP SIGNATURE-----
    }] $value] != -1} then {
      return true
    } else {
      return false
    }
  }

  #
  # NOTE: This procedure returns a unique temporary file name.  A script
  #       error is raised if this task cannot be accomplished.  There are
  #       no arguments.
  #
  proc getFileTempName {} {
    if {[isEagle]} then {
      return [file tempname]
    } else {
      global env

      if {[info exists env(PKGR_TEMP)]} then {

        }

        incr counter
      }
    }
  }

  #
  # NOTE: This procedure attempts to verify the PGP signature contained in
  #       the specified (named) file.  Non-zero is only returned if the PGP
  #       signature is verified successfully.  A script error should not be
  #       raised by this procedure.  The fileName argument must be the fully
  #       qualified path and file name of the PGP signature file to verify.
  #
  # <public>
  proc verifyPgpSignature { fileName } {
    variable pgpCommand

    if {[isEagle]} then {
      set fileName [appendArgs \" $fileName \"]

      if {[catch {

        return true
      }
    }

    return false
  }

  #
  # NOTE: This procedure returns the prefix for fully qualified variable
  #       names that MAY be present in the global namespace.  There are
  #       no arguments.
  #
  proc getLookupVarNamePrefix {} {
    return ::pkgr_; # TODO: Make non-global?
  }

  #
  # NOTE: This procedure returns a unique suffix for a fully qualified
  #       variable name that MAY be present in the global namespace.
  #       It is used (internally) to avoid any name collisions with
  #       variables and commands in the global namespace.  There are
  #       no arguments.
  #
  proc getLookupVarNameSuffix {} {
    return [appendArgs \
        [string trim [pid] -] _ [string trim [clock seconds] -] _ \
        [string trim [clock clicks -milliseconds] -]]; # TODO: Bad?
  }

  #
  # NOTE: This procedure returns the list of API keys to use when looking
  #       up packages via the package repository server.  An empty list
  #       is returned if no API keys are currently configured.  There are
  #       no arguments.
  #
  proc getLookupApiKeys {} {
    set varName [appendArgs [getLookupVarNamePrefix] api_keys]

    if {[info exists $varName]} then {
      return [set $varName]
    }

    if {[info exists env($varName)]} then {
      return $env($varName)
    }

    return https://urn.to/r/pkg; # NOTE: System default.
  }

  #
  # NOTE: This procedure returns the full URI to use when looking up a
  #       specific package via the package repository server.  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 name
  #       of the package being looked up, it cannot be an empty string.
  #       The version argument is the specific version being looked up
  #       -OR- an empty string for any available version.  No HTTP request
  #       is issued by this procedure; it just returns the URI to use.
  #
  proc getLookupUri { apiKey package version } {
    set baseUri [getLookupBaseUri]

    if {[string length $baseUri] == 0} then {
      return ""
    }

      return [appendArgs \
          $baseUri ? [http::formatQuery raw 1 method lookup apiKey $apiKey \
          package $package version $version]]
    }
  }

  #
  # NOTE: This procedure returns the version of the package that should be
  #       used to lookup the associated [package ifneeded] script -OR- an
  #       empty string if no such version exists.  The package argument is
  #       the name of the package, it cannot be an empty string.  The
  #       version argument is the specific version being looked up -OR- an
  #       empty string for any available version.
  #
  proc getIfNeededVersion { package version } {
    if {[string length $version] > 0} then {
      return $version
    }

    return [lindex [package versions $package] 0]
  }

  #
  # 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 getLookupVersion { requirement } {
    if {[set index [string first - $requirement]] != -1} then {
      incr index -1; set requirement [string range $requirement 0 $index]
    }

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

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

    return $requirement
  }

  #
  # 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
  #       name of the package, it cannot be an empty string.  The version
  #       argument is the specific version being looked up -OR- an empty
  #       string for any available version.  This procedure may raise script
  #       errors.
  #
  proc getLookupData { apiKey package version } {
    variable verboseUriDownload

    set uri [getLookupUri $apiKey $package $version]

    if {[string length $uri] == 0} then {
      return ""
    }

    if {$verboseUriDownload} then {
      pkgLog [appendArgs \
          "attempting to download URI \"" $uri \"...]
    }

    if {[isEagle]} then {
      set data [uri download -inline $uri]
    } else {

      set quiet [expr {!$verboseUriDownload}]
      set data [getFileViaHttp $uri 10 stdout $quiet]
    }

    if {$verboseUriDownload} then {
      pkgLog [appendArgs \
          "raw response data is: " $data]
    }

    set data [string map [list &lt\; < &gt\; > &quot\; \" &amp\; &] $data]
    set data [string map [list \r\n \n \r \n] $data]
    set data [string map [list \n \r\n] $data]
    set data [string trim $data]

    return $data
  }

  #
  # NOTE: This procedure attempts to extract the lookup code from the raw
  #       HTTP response data.  The data argument is the raw HTTP response
  #       data.  An empty string is returned if no lookup code is available.
  #
  proc getLookupCodeFromData { data } {
    if {![stringIsList $data] || [llength $data] < 1} then {
      return ""
    }

    return [lindex $data 0]
  }

  #
  # NOTE: This procedure attempts to extract the lookup result from the raw
  #       HTTP response data.  The data argument is the raw HTTP response
  #       data.  An empty string is returned if no lookup result is available.
  #
  proc getLookupResultFromData { data } {
    if {![stringIsList $data] || [llength $data] < 2} then {
      return ""
    }

    return [lindex $data 1]
  }

  #
  # NOTE: This procedure returns non-zero if the specified lookup response
  #       code indicates success.  The code argument is the extracted HTTP
  #       lookup response code.
  #
  proc isLookupCodeOk { code } {
    #
    # 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 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 language for the package script.  It must be an empty
    #       string, "Tcl", or "Eagle".  If it is an empty string, "Eagle"
    #       will be assumed.

        if {$language ne "Tcl"} then {
          error "repository package is not for Tcl"
        }
      }
    }

    #
    # 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(language) $language
      set metadata(script) $script
      set metadata(certificate) $certificate
    }
  }

  #
  # NOTE: This procedure, which may only be used from an Eagle script, checks
  #       if a native Tcl library is loaded and ready.  If not, a script error
  #       is raised.
  #
  proc tclMustBeReady {} {
    #
    # NOTE: This procedure is not allowed to actually load a native Tcl
    #       library; therefore, one must already be loaded.
    #
    if {![isEagle]} then {
      error "already running in Tcl language"
    }

    if {![tcl ready]} then {
      error "cannot use Tcl language, supporting library is not loaded"
    }
  }

  #
  # NOTE: This procedure, which may only be used from a native Tcl script,
  #       checks if Garuda and Eagle are loaded and ready.  If not, a script
  #       error is raised.
  #
  proc eagleMustBeReady {} {
    #
    # NOTE: This procedure is not allowed to actually load Garuda (and
    #       Eagle); therefore, they must already be loaded.
    #
    if {[isEagle]} then {
      error "already running in Eagle language"
    }

    if {[llength [info commands eagle]] == 0} then {
      error "cannot use Eagle language, supporting package is not loaded"
    }
  }

  #
  # NOTE: This procedure returns non-zero if the current script is being
  #       evaluated in Eagle with signed-only script security enabled.
  #       There are no arguments.
  #
  proc eagleHasSecurity {} {
    #
    # NOTE: If possible, check if the current interpreter has security
    #       enabled.
    #
    if {[isEagle] && [llength [info commands object]] > 0} then {
      if {[catch {
        object invoke -flags +NonPublic Interpreter.GetActive HasSecurity
      } security] == 0 && $security} then {
        return true
      }
    }

    return false
  }

  #
  # NOTE: This procedure uses the package lookup metadata.  If the package
  #       script is properly signed, an attempt will be made to evaluate it
  #       in the target language.  If the script was signed using PGP, then
  #       a conforming implementation of the OpenPGP specification (e.g.
  #       gpg2) must be installed locally.  If the script was signed using
  #       Harpy then Garuda, Eagle, and Harpy must be installed locally.
  #       This procedure is designed to work for both native Tcl and Eagle
  #       packages.  Additionally, it is designed to work when evaluated
  #       using either native Tcl or Eagle; however, it is up to the package
  #       script itself to either add the package or provide the package to
  #       the language(s) supported by that package.  The varName argument
  #       is the name of an array variable in the call frame of the
  #       immediate caller, that contains the package lookup metadata.  This
  #       procedure may raise script errors.
  #
  proc processLookupMetadata { varName } {
    #
    # NOTE: If the metadata variable name appears to be invalid, fail.
    #
    if {[string length $varName] == 0} then {
      error "bad metadata"
    }

        }
      }
    } else {
      error "unsupported script certificate"
    }
  }

  #
  # NOTE: This procedure performs initial setup of the package repository
  #       client, using the current configuration parameters.  There are
  #       no arguments.  It may load the Garuda package when evaluated in
  #       native Tcl.  It may load a native Tcl library when evaluated in
  #       Eagle.  It may install the [package unknown] hook.
  #
  proc setupPackageUnknownHandler {} {
    variable autoHook
    variable autoLoadTcl
    variable autoRequireGaruda

    if {$autoRequireGaruda && ![isEagle]} then {
      #

      # NOTE: Install our [package unknown] handler and save the original
      #       one for our use as well.
      #
      hookPackageUnknownHandler
    }
  }

  #
  # NOTE: This procedure returns non-zero if the [package unknown] handler
  #       has already been hooked by the package repository client.  There
  #       are no arguments.
  #
  proc isPackageUnknownHandlerHooked {} {
    return [info exists [appendArgs \
        [getLookupVarNamePrefix] saved_package_unknown]]
  }

  #
  # NOTE: This procedure attempts to hook the [package unknown] handler.  It
  #       will raise a script error if this has already been done.  The old
  #       [package unknown] handler is saved and will be used by the new one
  #       as part of the overall package loading process.  There are no
  #       arguments.
  #
  proc hookPackageUnknownHandler {} {
    set varName [appendArgs [getLookupVarNamePrefix] saved_package_unknown]

    if {[info exists $varName]} then {
      error "package unknown handler already hooked"
    }

    set $varName [package unknown]
    package unknown [appendArgs [namespace current] ::packageUnknownHandler]
  }

  #
  # NOTE: This procedure attempts to unhook the [package unknown] handler.
  #       It will raise a script error if the [package unknown] handler is
  #       not hooked.  The old [package unknown] handler is restored and
  #       the saved [package unknown] handler is cleared.  There are no
  #       arguments.
  #
  proc unhookPackageUnknownHandler {} {
    set varName [appendArgs [getLookupVarNamePrefix] saved_package_unknown]

    if {![info exists $varName]} then {
      error "package unknown handler is not hooked"
    }

    package unknown [set $varName]
    unset $varName
  }

  #
  # NOTE: The procedure runs the saved [package unknown] handler.  Any script
  #       errors are raised to the caller.  The package and version arguments
  #       are passed in from the current [package unknown] handler verbatim.
  #
  proc runSavedPackageUnknownHandler { package version } {
    #
    # NOTE: See if there is a saved [package unknown] handler.  If so, then
    #       attempt to use it.
    #
    set varName [appendArgs [getLookupVarNamePrefix] saved_package_unknown]
    set oldHandler [expr {[info exists $varName] ? [set $varName] : ""}]

    if {[string length $oldHandler] > 0} then {
      lappend oldHandler $package $version; uplevel #0 $oldHandler
    }
  }

  #
  # NOTE: This procedure is the [package unknown] handler entry point called
  #       by native Tcl and Eagle.  The package argument is the name of the
  #       package being sought, it cannot be an empty string.  The version
  #       argument must be a specific version -OR- a package specification
  #       that conforms to TIP #268.  This version argument must be optional
  #       here, because Eagle does not add a version argument when one is
  #       not explicitly supplied to the [package require] sub-command.
  #
  proc packageUnknownHandler { package {version ""} } {
    variable verboseUnknownResult

    #
    # NOTE: First, run our [package unknown] handler.
    #

        pkgLog [appendArgs \
            "package \"" [formatPackageName $package $version] \
            "\" was not loaded"]
      }
    }
  }

  #
  # NOTE: This procedure evaluates the package repository client settings
  #       script file, if it exists.  Any script errors raised are not
  #       masked.  The script argument must be the fully qualified path
  #       and file name for the primary package repository client script
  #       file.
  #
  proc maybeReadSettingsFile { script } {
    if {[string length $script] == 0 || \
        ![file exists $script] || ![file isfile $script]} then {
      return
    }

    set fileName [appendArgs \
        [file rootname $script] .settings [file extension $script]]

    if {[file exists $fileName] && [file isfile $fileName]} then {
      uplevel 1 [list source $fileName]
    }
  }


  #
  # NOTE: This procedure sets up the default values for all configuration
  #       parameters used by the package repository client.  There are no
  #       arguments.

  #



  proc setupPackageUnknownVars {} {
    #
    # NOTE: Automatically install our [package unknown] handler when this
    #       package is loaded?
    #
    variable autoHook; # DEFAULT: true

    if {![info exists autoHook]} then {

    variable verboseUriDownload; # DEFAULT: false

    if {![info exists verboseUriDownload]} then {
      set verboseUriDownload false
    }
  }

  #
  # NOTE: This procedure is the primary entry point to the package repository
  #       client.  It attempts to lookup the specified package using the
  #       currently configured package repository server.  The package
  #       argument is the name of the package being sought, it cannot be an
  #       empty string.  The version argument must be a specific version -OR-
  #       a package specification that conforms to TIP #268.  The caller
  #       argument must be an empty string -OR- the literal string "handler".
  #
  # <public>
  proc main { package version caller } {
    #
    # NOTE: Get the list of API keys and try each one, in order, until
    #       the package is found.
    #
    set apiKeys [getLookupApiKeys]; lappend apiKeys ""


  if {![isEagle]} then {
    ###########################################################################
    ############################# BEGIN Tcl ONLY ##############################
    ###########################################################################

    #
    # NOTE: This procedure was stolen from the "getEagle.tcl" script.  It is
    #       designed to emit a progress indicator while an HTTP request is
    #       being processed.  The channel argument is the Tcl channel where
    #       the progress indicator should be emitted.  The type argument is
    #       the single-character progress indicator.  The milliseconds
    #       argument is the number of milliseconds to wait until the next
    #       periodic progress indicator should be emitted.  This procedure
    #       reschedules its own execution.
    #
    proc pageProgress { channel type milliseconds } {
      #
      # NOTE: This variable is used to keep track of the currently scheduled
      #       (i.e. pending) [after] event.
      #
      variable afterForPageProgress

      #
      # NOTE: Show that something is happening...
      #
      catch {puts -nonewline $channel $type; flush $channel}

      #
      # NOTE: Make sure that we are scheduled to run again, if requested.
      #
      if {$milliseconds > 0} then {
        set afterForPageProgress [after $milliseconds \
            [namespace code [list pageProgress $channel $type \
            $milliseconds]]]
      } else {
        unset afterForPageProgress
      }
    }

    #
    # NOTE: This procedure was stolen from the "getEagle.tcl" script.  It is
    #       designed to process a single HTTP request, including any HTTP
    #       3XX redirects (up to the specified limit), and return the raw
    #       HTTP response data.  It does not contain special code to handle
    #       HTTP status codes other than 3XX (e.g. 4XX, 5XX, etc).
    #
    # <public>
    proc getFileViaHttp { uri redirectLimit channel quiet args } {
      #
      # NOTE: This variable is used to keep track of the currently scheduled
      #       (i.e. pending) [after] event.
      #
      variable afterForPageProgress

      #
      # NOTE: This procedure requires the modern version of the HTTP package,
      #       which is typically included with the Tcl core distribution.
      #
      package require http 2.0

      #

            #       kind of supported HTTP redirect.
            #
            set data [::http::data $token]
            ::http::cleanup $token; break
          }
        }
      }

      #
      # NOTE: If there is a currently scheduled [after] event, cancel it.
      #
      if {[info exists afterForPageProgress]} then {
        catch {after cancel $afterForPageProgress}
      }

      #
      # NOTE: If progress messages were emitted, start a fresh line.
      #
      if {!$quiet} then {
        catch {puts $channel [appendArgs " " $uri]; flush $channel}
      }