ADDED doc/v1.html
Index: doc/v1.html
==================================================================
--- doc/v1.html
+++ doc/v1.html
@@ -0,0 +1,1747 @@
+
+
+
Private Procedure "setupCommonVariables"
+
+
+
Required argument "force"
+
+
+This procedure was stolen from the "getEagle.tcl" script. This
+procedure sets up the default values for all HTTP configuration
+parameters used by this package. If the force argument is
+non-zero, any existing values will be overwritten and set back
+to their default values.
+
+
+
Private Procedure "pageOut"
+
+
+
Required argument "channel"
+
+
Required argument "string"
+
+
+This procedure was stolen from the "getEagle.tcl" script. It is
+designed to emit a message to the console. The channel argument
+is the channel where the message should be written. The string
+argument is the content of the message to emit. If the channel
+argument is an empty string, nothing is written.
+
+
+
Private Procedure "pageLog"
+
+
+
Required argument "string"
+
+
+This procedure was stolen from the "getEagle.tcl" script. It is
+designed to emit a message to the HTTP client log. The string
+argument is the content of the message to emit. If the string
+argument is an empty string, nothing is written.
+
+
+
Private Procedure "pageProgress"
+
+
+
Required argument "channel"
+
+
Required argument "type"
+
+
Required argument "milliseconds"
+
+
+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.
+
+
+
Public API Procedure "getFileViaHttp"
+
+
+
Required argument "uri"
+
+
Required argument "redirectLimit"
+
+
Required argument "channel"
+
+
Required argument "quiet"
+
+
Required argument "args"
+
+
+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 may raise any number of script errors.
+
+
+
+
Private Procedure "pkgLog"
+
+
+
Required argument "string"
+
+
+This procedure emits a message to the package downloader client
+log. The string argument is the content of the message to emit.
+
+
+
Private Procedure "setupDownloadServerVars"
+
+
+
Required argument "force"
+
+
+This procedure sets up the default values for all URN configuration
+parameters used by the package downloader client. If the force
+argument is non-zero, any existing values will be overwritten and
+set back to their default values.
+
+
+
Private Procedure "setupDownloadVersionVars"
+
+
+
Required argument "force"
+
+
+This procedure sets up the default values for all version
+configuration parameters used by the package downloader client.
+If the force argument is non-zero, any existing values will be
+overwritten and set back to their default values.
+
+
+
Private Procedure "setupDownloadUriVars"
+
+
+
Required argument "force"
+
+
+This procedure sets up the default values for all URI configuration
+parameters used by the package downloader client. If the force
+argument is non-zero, any existing values will be overwritten and
+set back to their default values.
+
+
+
Private Procedure "setupDownloadVars"
+
+
+
Required argument "script"
+
+
+This procedure sets up the default values for all configuration
+parameters used by the package downloader client. The script
+argument is the fully qualified path and file name for the script
+being evaluated.
+
+
+
Public API Procedure "useServerId"
+
+
+
Optional argument "serverId" with default value ""
+
+
+This procedure modifies the URN variables used by the package
+downloader client so that one or more alternative (private?)
+backend file servers may be used. The serverId argument must
+consist only of alphanumeric characters and it must begin with
+a letter.
+
+
+
Public API Procedure "useVersionId"
+
+
+
Optional argument "versionId" with default value ""
+
+
+This procedure modifies the version variables used by the package
+downloader client so that a specific version will be used. The
+versionId argument must consist only of hexadecimal characters.
+
+
+
Private Procedure "uriEscape"
+
+
+
Required argument "name"
+
+
Required argument "value"
+
+
+This procedure escapes a single name/value pair for use in a URI
+query string. The name argument is the name of the parameter.
+The value argument is the value of the parameter.
+
+
+
Private Procedure "getPersistentRootDirectory"
+
+
+This procedure returns the root directory where any packages that
+are downloaded should be saved to permanent storage for subsequent
+use. There are no arguments.
+
+
+
Private Procedure "verifyPersistentRootDirectory"
+
+
+This procedure checks the configured persistent root directory for
+downloaded packages. If any checks fail, a script error is raised.
+There are no arguments. The return value is undefined.
+
+
+
Private Procedure "getPackageIndexFileName"
+
+
+
Required argument "language"
+
+
+This procedure returns the name of the package index file for the
+language specified by the language argument. An empty string will
+be returned if the language is unsupported or unrecognized.
+
+
+
Private Procedure "maybeCreateMasterTclPackageIndex"
+
+
+This procedure, which is only used for native Tcl, generates a
+"master" package index file (i.e. "pkgIndex.tcl") suitable for
+use with native Tcl 8.4 (or higher). It will recursively scan
+for all other native Tcl package index files that are within the
+configured persistent root directory and [source] them, thereby
+causing all packages located within them to become available.
+Since Eagle (by default) already performs recursive searches for
+its package index files, this procedure is not needed for Eagle.
+The return value is undefined.
+
+
+
Internal API Procedure "downloadAndSaveOpenPgpKeyFile"
+
+
+
Required argument "fileName"
+
+
+This procedure attempts to download the Package Signing Keys from
+the remote server and save it to a local file. This procedure may
+raise script errors. The fileName argument is the name of the file
+where the downloaded data should be written. This procedure is only
+intended to be used from the "pkgr_setup.eagle" tool script and may
+go away in later versions of this package.
+
+
+
Private Procedure "isOpenPgpSignatureFileName"
+
+
+
Required argument "fileName"
+
+
Required argument "nameOnly"
+
+
+This procedure returns non-zero if the specified file seems to be
+an OpenPGP signature file. The fileName argument is the name of
+the file to check, which may or may not exist. The nameOnly
+argument should be non-zero to ignore the contents of the file.
+
+
+
Private Procedure "getAutoPath"
+
+
+
Required argument "language"
+
+
+This procedure returns the auto-path for the language specified by
+the language argument. An empty list is returned if the auto-path
+does not exist in the target language. This procedure may raise
+script errors.
+
+
+
Private Procedure "addToAutoPath"
+
+
+
Required argument "language"
+
+
Required argument "directory"
+
+
+This procedure adds a directory to the auto-path of the specified
+language (i.e. native Tcl or Eagle). The directory will not be
+added if it is already present. The language argument must be the
+literal string "eagle" or the literal string "tcl". The directory
+argument is the fully qualified path for the directory to add to
+the auto-path.
+
+
+
Private Procedure "maybeAddToAutoPath"
+
+
+
Required argument "language"
+
+
Required argument "directory"
+
+
+This procedure adds a directory to the auto-path of the specified
+language (i.e. native Tcl or Eagle). The directory will not be
+added if it is already present. The language argument must be the
+literal string "eagle" or the literal string "tcl". The directory
+argument is the fully qualified path for the directory to add to
+the auto-path. The directory will not be added if it falls under
+a directory already in the auto-path.
+
+
+
Private Procedure "isMonoInstalled"
+
+
+This procedure attempts to verify that an instance of Mono and its
+associated runtimes are installed locally. There are no arguments.
+The return value is non-zero if Mono appears to be installed and
+available for use; otherwise, the return value is zero.
+
+
+
Private Procedure "canUseMsilPlatform"
+
+
+This procedure attempts to verify that some runtime is available to
+run CLR applications locally (e.g. the .NET Framework or Mono JIT).
+There are no arguments. The return value is non-zero if it appears
+that CLR applications should be runnable locally; otherwise, the
+return value is zero.
+
+
+
Internal API Procedure "verifyPackageName"
+
+
+
Required argument "packageName"
+
+
+This procedure verifies that the specified value is indeed a valid
+package name. The packageName argument is the value to verify.
+This procedure may raise script errors.
+
+
+
Internal API Procedure "verifyPackagePatchLevel"
+
+
+
Required argument "patchLevel"
+
+
+This procedure verifies that the specified value is indeed a valid
+patch level. The patchLevel argument is the value to verify. This
+procedure may raise script errors.
+
+
+
Internal API Procedure "verifyLanguageAndVersion"
+
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "varName"
+
+
+This procedure verifies the combination of language and version
+specified by the caller. The language argument must be one of the
+literal strings "eagle", "tcl", or "client". The version argument
+must be one of the literal strings "8.4", "8.5", or "8.6" when the
+language is "tcl" -OR- the literal string "1.0" when the language
+is "eagle". When the language is "client", the version match the
+major and minor portions of "1.0" and any remaining portions must
+be numeric. The varName argument is the name of a scalar variable
+in the context of the immediate caller that will receive a boolean
+value indicating if the specified language is actually a reference
+to the package downloader client itself.
+
+
+
Internal API Procedure "getPlatform"
+
+
+This procedure returns the name of the current platform. There are
+no arguments. An empty string will be returned if the name of the
+current platform cannot be determined for any reason.
+
+
+
Internal API Procedure "verifyVersionId"
+
+
+
Required argument "versionId"
+
+
+This procedure verifies that the specified value is indeed a valid
+version identifier. The versionId argument is the value to verify.
+This procedure may raise script errors.
+
+
+
Internal API Procedure "verifyPlatform"
+
+
+
Required argument "platform"
+
+
Required argument "varName"
+
+
+This procedure verifies the platform specified by the caller. The
+platform argument must be an empty string -OR- one of the literal
+strings "msil" or "neutral", or one of the values returned by the
+[getPlatform] procedure. An empty string means that the associated
+entity does not require a specific platform. The varName argument
+is the name of a variable in the context of the immediate caller
+that will receive a modified platform name, if applicable. Upon
+failure, a script error will be raised. The return value is
+undefined.
+
+
+
Private Procedure "getPackageFile"
+
+
+
Required argument "uri"
+
+
+This procedure issues a request to an HTTP(S) server. It returns
+the raw response data verbatim. It may raise a script error. It
+will always use the currently configured HTTP(S) login cookie, if
+any; therefore, it should really only be used for requests to the
+package file server. The uri argument is the fully qualified URI
+to request.
+
+
+
Private Procedure "getDownloadVarNamePrefix"
+
+
+This procedure returns the prefix for fully qualified variable
+names that MAY be present in the global namespace. There are
+no arguments.
+
+
+
Public API Procedure "resetCookieAndLoginSimple"
+
+
+This procedure resets the currently configured login cookie, if
+any, and then attempts to login using the configured package
+repository server API key -OR- using the public access account.
+Upon success, it will set the login cookie to the one from the
+raw response data. Upon failure, a script error will be raised.
+There are no arguments.
+
+
+
Internal API Procedure "maybeResetCookieAndLoginSimple"
+
+
+This procedure attempts to login using the configured package
+repository server API key -OR- using the public access account,
+if not already logged in. Upon success, it will set the login
+cookie to the one from the raw response data. Upon failure, a
+script error will be raised. There are no arguments.
+
+
+
Public API Procedure "resetCookieAndLogin"
+
+
+
Required argument "userName"
+
+
Required argument "password"
+
+
+This procedure resets the currently configured login cookie, if
+any, and then attempts to login using the specified user name and
+password. Upon success, it will set the login cookie to the one
+from the raw response data. Upon failure, a script error will be
+raised. The userName argument must be the name of a package file
+server user with at least Fossil Check-Out (o) permissions on the
+package file server. The password argument must be the plaintext
+password that is associated with the specified user name.
+
+
+
Public API Procedure "logoutAndResetCookie"
+
+
+This procedure attempts to logout using the currently configured
+login cookie, if any, and then resets the login cookie. There
+are no arguments. This procedure may raise a script error.
+
+
+
Private Procedure "getUniqueTempDirectory"
+
+
+
Optional argument "prefix" with default value ""
+
+
+This procedure returns a unique temporary directory where one or
+more files may be saved. The prefix argument is a prefix for the
+directory name and it may be an empty string. There is no attempt
+to actually create the resulting directory.
+
+
+
Public API Procedure "checkForHigherVersion"
+
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "platform"
+
+
Required argument "packageName"
+
+
Required argument "usePgp"
+
+
+This procedure checks if there is a higher version available of the
+specified package on the package file server. The language argument
+must be one of the literal strings "eagle", "tcl", or "client". The
+version argument must be one of the literal strings "8.4", "8.5", or
+"8.6" when the language is "tcl" -OR- the literal string "1.0" when
+the language is either "eagle" or "client". The platform argument
+must be an empty string -OR- one of the literal strings "msil" or
+"neutral", or one of the values returned by the [getPlatform]
+procedure. An empty string means that the associated package does
+not require a specific platform. The packageName argument is a
+directory name relative to the language and version-specific
+directory on the package file server and may be an empty string.
+The usePgp argument should be non-zero when an OpenPGP signature
+file needs to be downloaded and verified for the downloaded file.
+
+
+
Private Procedure "guessPackageNameFromFileNames"
+
+
+
Required argument "language"
+
+
Required argument "fileNames"
+
+
+This procedure attempts to guess a package name based on a list of
+its files. It relies upon the fact that all packages must include
+a package index file. The language argument must be one of the
+literal strings "eagle", "tcl", or "client". The fileNames argument
+must be the list of file names to be downloaded. The package name,
+if one can be detected, is returned; otherwise, an empty string will
+be returned.
+
+
+
Private Procedure "downloadAllPlatforms"
+
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "packageName"
+
+
Required argument "fileNames"
+
+
Required argument "usePgp"
+
+
+This procedure downloads a manitest from the package file server,
+writing its contents to the specified local file name. It can also
+verify the OpenPGP signature. The language argument must be one of
+the literal strings "eagle", "tcl", or "client". The version
+argument must be one of the literal strings "8.4", "8.5", or "8.6"
+when the language is "tcl" -OR- the literal string "1.0" when the
+language is either "eagle" or "client". The packageName argument
+is a directory name relative to the language and version-specific
+directory on the package file server and may be an empty string.
+The fileNames argument is the list of file names to be downloaded.
+The usePgp argument should be non-zero when an OpenPGP signature
+needs to be verified for the downloaded file.
+
+
+
Private Procedure "downloadOneUriToFile"
+
+
+
Required argument "localFileName"
+
+
Required argument "uri"
+
+
Required argument "usePgp"
+
+
Required argument "forcePgp"
+
+
+This procedure downloads a single URI from the package file server
+and writes the result to a local file. The localFileName argument
+is the file name where the downloaded file should be written. The
+The uri argument is the URI to download. The usePgp argument should
+be non-zero when the OpenPGP signature file needs to be verified for
+the downloaded file. The return value is undefined.
+
+
+
Private Procedure "downloadOneFile"
+
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "platform"
+
+
Required argument "fileName"
+
+
Required argument "localFileName"
+
+
Required argument "usePgp"
+
+
+This procedure downloads a single file from the package file server,
+writing its contents to the specified local file name. It can also
+verify the OpenPGP signatures. When an OpenPGP signature file is
+downloaded, this procedure assumes the corresponding data file was
+already downloaded (i.e. since OpenPGP needs both to perform the
+signature checks). The language argument must be one of the
+literal strings "eagle", "tcl", or "client". The version argument
+must be one of the literal strings "8.4", "8.5", or "8.6" when the
+language is "tcl" -OR- the literal string "1.0" when the language
+is either "eagle" or "client". The platform argument must be an
+empty string -OR- one of the literal strings "msil" or "neutral", or
+one of the values returned by the [getPlatform] procedure. An empty
+string means that the associated package does not require a specific
+platform. The fileName argument is a file name relative to the
+language and version-specific directory on the package file server.
+The localFileName argument is the file name where the downloaded
+file should be written. The usePgp argument should be non-zero when
+the OpenPGP signature file needs to be verified for the downloaded
+file.
+
+
+
Public API Procedure "downloadFiles"
+
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "platform"
+
+
Required argument "fileNames"
+
+
Required argument "options"
+
+
+This procedure attempts to download a list of files, optionally
+persistening them for subsequent uses by the target language.
+The language argument must be one of the literal strings "eagle",
+"tcl", or "client". The version argument must be one of the
+literal strings "8.4", "8.5", or "8.6" when the language is "tcl"
+-OR- the literal string "1.0" when the language is either "eagle"
+or "client". The platform argument must be an empty string -OR-
+one of the literal strings "msil" or "neutral", or one of the values
+returned by the [getPlatform] procedure.. An empty string means
+that the associated package does not require a specific platform.
+The fileNames argument must be a well-formed list of file names to
+download, each one relative to the language and version-specific
+directory on the package file server. The options argument must
+be a dictionary of name/value pairs. The -persistent option should
+be non-zero if the downloaded files should be saved to permanent
+storage for subsequent use. The -usePgp option should be non-zero
+when an OpenPGP signature file needs to be downloaded and verified
+for each downloaded file. The -useAutoPath option should be
+non-zero to modify the auto-path to include the temporary or
+persistent directories containing the downloaded files. The
+-allowUpdate option should be non-zero to allow existing package
+files to be overwritten.
+
+
+
+
Private Procedure "setupRepositoryServerVars"
+
+
+
Required argument "force"
+
+
+This procedure sets up the default values for all URN configuration
+parameters used by the package repository client. If the force
+argument is non-zero, any existing values will be overwritten and
+set back to their default values.
+
+
+
Private Procedure "setupRepositoryUriVars"
+
+
+
Required argument "force"
+
+
+This procedure sets up the default values for all URI configuration
+parameters used by the package repository client. If the force
+argument is non-zero, any existing values will be overwritten and
+set back to their default values.
+
+
+
Internal API Procedure "formatExecArgument"
+
+
+
Required argument "value"
+
+
+This procedure returns a string argument value, which may contain
+spaces, for use with the [exec] command. The value argument is
+the string value to format as an [exec] argument.
+
+
+
Private Procedure "formatPackageName"
+
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+This procedure returns a formatted, possibly version-specific,
+package name, for use in logging. The package argument is the
+name of the package. The version argument is the version of the
+package.
+
+
+
Private Procedure "formatResult"
+
+
+
Required argument "code"
+
+
Required argument "result"
+
+
+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.
+
+
+
Private Procedure "pkgLog"
+
+
+
Required argument "string"
+
+
+This procedure emits a message to the package repository client
+log. The string argument is the content of the message to emit.
+
+
+
Private Procedure "stringIsList"
+
+
+
Required argument "value"
+
+
+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.
+
+
+
Public API Procedure "isHarpyCertificate"
+
+
+
Required argument "value"
+
+
+This procedure returns non-zero if the specified string value
+looks like a Harpy (script) certificate. The value argument is
+the string to check. The value 14 used within this procedure is
+the length of the literal string "</Certificate>".
+
+
+
Public API Procedure "isOpenPgpSignature"
+
+
+
Required argument "value"
+
+
+This procedure returns non-zero if the specified string value
+looks like an OpenPGP signature. The value argument is the string
+to check. The value 27 used within this procedure is the length
+of the literal string "-----END PGP SIGNATURE-----".
+
+
+
Public API Procedure "getFileTempDirectory"
+
+
+
Optional argument "envVarName" with default value ""
+
+
+This procedure returns the fully qualified name of the directory
+where temporary files should be written. The envVarName argument
+is an optional extra environment variable to check (first).
+
+
+
Private Procedure "getFileTempName"
+
+
+This procedure returns a unique temporary file name. A script
+error is raised if this task cannot be accomplished. There are
+no arguments.
+
+
+
Internal API Procedure "probeForOpenPgpInstallation"
+
+
+This procedure attempts to check for an OpenPGP installation being
+installed at the default location. There are no arguments. If the
+OpenPGP installation is detected and is not yet present in the PATH,
+an attempt will be made to add it. Non-zero will be returned if the
+OpenPGP installation directory was successfully detected and added
+to the PATH -OR- detecting and adding it was not necessary because
+it already appeared to be available for use.
+
+
+
Public API Procedure "openPgpMustBeInstalled"
+
+
+This procedure attempts to verify that a configured implementation
+of OpenPGP is installed locally. There are no arguments. Script
+errors are raised if any problems are found. The return value is
+undefined.
+
+
+
Public API Procedure "verifyOpenPgpSignature"
+
+
+
Required argument "fileName"
+
+
+This procedure attempts to verify the OpenPGP signature contained
+in the specified (named) file. Non-zero is only returned if the
+OpenPGP 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 OpenPGP signature
+file to verify.
+
+
+
Private Procedure "getOpenPgpPassphraseFile"
+
+
+This procedure returns the name of the file containing the OpenPGP
+passphrase. This procedure is only used when creating an OpenPGP
+signature. There are no arguments.
+
+
+
Internal API Procedure "createHarpyCertificate"
+
+
+
Required argument "fileName"
+
+
+This procedure attempts to create a Harpy (script) certificate for
+the specified (named) file. Non-zero is only returned if the Harpy
+(script) certificate is created 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 file to be signed. This
+procedure assumes that the Harpy package for Eagle is installed and
+ready for use (i.e. it can find a valid license certificate).
+
+
+
Public API Procedure "createOpenPgpSignature"
+
+
+
Required argument "fileName"
+
+
+This procedure attempts to create an OpenPGP signature for the
+specified (named) file. Non-zero is only returned if the OpenPGP
+signature is created 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 file to be signed.
+
+
+
Internal API Procedure "importOpenPgpKeyFile"
+
+
+
Required argument "fileName"
+
+
Required argument "varName"
+
+
+This procedure attempts to import the OpenPGP keys contained in
+the specified (named) file. Non-zero is only returned if the
+OpenPGP keys are imported 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 OpenPGP key file
+to import. This procedure is only intended to be used from the
+"pkgr_setup.eagle" tool script and may go away in later versions
+of this package.
+
+
+
Private Procedure "getLookupVarNamePrefix"
+
+
+This procedure returns the prefix for fully qualified variable
+names that MAY be present in the global namespace. There are
+no arguments.
+
+
+
Public API Procedure "getUniqueSuffix"
+
+
+
Optional argument "paranoia" with default value "1"
+
+
+This procedure returns a name suffix (directory, variable, etc)
+that is unique to the running process at the current point in
+time. It is used (internally) to avoid name collisions with any
+preexisting variables or commands that may be present in the
+global namespace. The paranoia argument represents the relative
+level of paranoia required by the caller; the higher this level,
+the more uniqueness is required.
+
+
+
Internal API Procedure "getApiKeys"
+
+
+
Optional argument "prefix" with default value ""
+
+
Optional argument "prefixOnly" with default value "false"
+
+
+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. The prefix
+argument is an extra variable name prefix to check prior to any
+that are already configured. The prefixOnly argument should be
+non-zero to exclude any API keys other than those based on the
+prefix specified by the caller.
+
+
+
Internal API Procedure "verifyMetadataLanguage"
+
+
+
Required argument "language"
+
+
+This procedure verifies the language specified by the caller. The
+language argument must be an empty string -OR- the literal string
+"Eagle" or "Tcl". This procedure may raise script errors.
+
+
+
Internal API Procedure "verifyServerId"
+
+
+
Required argument "serverId"
+
+
+This procedure verifies that the specified value is indeed a valid
+server identifier. The serverId argument is the value to verify.
+This procedure may raise script errors.
+
+
+
Public API Procedure "useServerId"
+
+
+
Optional argument "serverId" with default value ""
+
+
+This procedure modifies the URN variables used by the package
+repository client so that one or more alternative (private?)
+backend repository servers may be used. The serverId argument
+must consist only of alphanumeric characters and it must begin
+with a letter.
+
+
+
Private Procedure "getLookupBaseUri"
+
+
+This procedure returns the base URI for the package repository
+server endpoint that is used to lookup packages. There are no
+arguments.
+
+
+
Internal API Procedure "getSubmitBaseUri"
+
+
+This procedure returns the base URI for the package repository
+server endpoint that is used to submit packages. There are no
+arguments.
+
+
+
Private Procedure "getLookupUri"
+
+
+
Required argument "apiKeys"
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+This procedure returns the full URI to use when looking up a
+specific package via the package repository server. The apiKeys
+argument is the list of API keys to use -OR- an empty list 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. There
+are no HTTP requests issued by this procedure; it simply returns
+the URI to use.
+
+
+
Private Procedure "getIfNeededVersion"
+
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+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.
+
+
+
Private Procedure "packageRequirementToVersion"
+
+
+
Required argument "requirement"
+
+
+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.
+
+
+
Private Procedure "getLookupData"
+
+
+
Required argument "apiKeys"
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+This procedure issues an HTTP request that should return metadata
+that can be used to load and/or provide the specified package.
+The apiKeys argument is the list of API keys to use -OR- an empty
+list 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. All line-endings are normalized to Unix-style;
+therefore, all script signatures must assume this.
+
+
+
Internal API Procedure "getResponseCodeFromRawData"
+
+
+
Required argument "data"
+
+
+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.
+
+
+
Internal API Procedure "getResponseResultFromRawData"
+
+
+
Required argument "data"
+
+
+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.
+
+
+
Internal API Procedure "isResponseCodeOk"
+
+
+
Required argument "code"
+
+
+This procedure returns non-zero if the specified lookup response
+code indicates success. The code argument is the extracted HTTP
+lookup response code.
+
+
+
Private Procedure "isValidPackageRequirement"
+
+
+
Required argument "requirement"
+
+
Required argument "rangeOk"
+
+
Optional argument "emptyOk" with default value "false"
+
+
+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.
+
+
+
Private Procedure "extractAndVerifyLookupMetadata"
+
+
+
Required argument "result"
+
+
Required argument "varName"
+
+
Required argument "caller"
+
+
+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".
+
+
+
Private Procedure "tclMustBeReady"
+
+
+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. There are no arguments.
+
+
+
Internal API Procedure "makeTclReady"
+
+
+This procedure is designed for Eagle. It attempts to load the
+"best" native Tcl library. It may raise any number of script
+errors. There are no arguments.
+
+
+
Internal API Procedure "eagleMustBeReady"
+
+
+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. There are no arguments.
+
+
+
Internal API Procedure "makeEagleReady"
+
+
+This procedure is designed for native Tcl. It attempts to load
+the Garuda package and gain access to Eagle. It may raise any
+number of script errors. There are no arguments.
+
+
+
Private Procedure "eagleHasSecurity"
+
+
+This procedure returns non-zero if the current script is being
+evaluated in Eagle with signed-only script security enabled.
+There are no arguments.
+
+
+
Private Procedure "processLookupMetadata"
+
+
+
Required argument "varName"
+
+
+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 OpenPGP,
+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.
+
+
+
Private Procedure "isPackagePresent"
+
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+This procedure returns non-zero if the specified package appears to
+be present. 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.
+
+
+
Private Procedure "isPackageAvailable"
+
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+This procedure returns non-zero if the specified package appears to
+be available. 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.
+
+
+
Private Procedure "canDownloadPackage"
+
+
+
Required argument "package"
+
+
+This procedure returns non-zero if the specified package can be
+downloaded, i.e. because it is not required for the downloading
+process itself to be functional, etc. The package argument is
+the name of the package to check.
+
+
+
Private Procedure "setupPackageUnknownHandler"
+
+
+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.
+
+
+
Private Procedure "isPackageUnknownHandlerHooked"
+
+
+This procedure returns non-zero if the [package unknown] handler
+has already been hooked by the package repository client. There
+are no arguments.
+
+
+
Private Procedure "hookPackageUnknownHandler"
+
+
+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.
+
+
+
Private Procedure "unhookPackageUnknownHandler"
+
+
+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.
+
+
+
Private Procedure "runSavedPackageUnknownHandler"
+
+
+
Required argument "package"
+
+
Required argument "version"
+
+
+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.
+
+
+
Private Procedure "packageUnknownHandler"
+
+
+
Required argument "package"
+
+
Optional argument "version" with default value ""
+
+
+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.
+
+
+
Public API Procedure "maybeReadSettingsFile"
+
+
+
Required argument "script"
+
+
+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.
+
+
+
Private Procedure "maybeReadApiKeysFile"
+
+
+This procedure evaluates a package repository client API keys
+script file, if it has been configured -AND- actually exists.
+Any script errors raised are not masked. The evaluated script
+file should (normally) modify the "::pkgr_api_keys" variable
+in order to add API keys for use with the package repository
+client.
+
+
+
Private Procedure "setupRepositoryOpenPgpVars"
+
+
+This procedure sets up the default values for all configuration
+parameters used to interact with the OpenPGP implementation.
+There are no arguments.
+
+
+
Private Procedure "setupPackageUnknownVars"
+
+
+This procedure sets up the default values for all configuration
+parameters used by the package repository client. There are no
+arguments.
+
+
+
Public API Procedure "getPackageFromRepository"
+
+
+
Required argument "package"
+
+
Required argument "version"
+
+
Required argument "caller"
+
+
+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".
+
+
+
+
Private Procedure "setupUploadVars"
+
+
+This procedure sets up the default values for all configuration
+parameters used by the package uploader client. There are no
+arguments.
+
+
+
Private Procedure "setupCheckoutVars"
+
+
+This procedure sets up the default values for all configuration
+parameters used by the package uploader client that require the
+location of the checkout directory. There are no arguments.
+
+
+
Private Procedure "formatStringMapValue"
+
+
+
Required argument "value"
+
+
+This procedure returns a string value, formatted for use within a
+script block being processed by the [string map] command. The
+value argument is the string value to format. No return value is
+reserved to indicate an error. This procedure may not raise any
+script errors.
+
+
+
Private Procedure "countCommonPathParts"
+
+
+
Required argument "path1"
+
+
Required argument "path2"
+
+
+This procedure counts the common path components for two paths. The
+count is returned, zero if there are no common path components. The
+path1 and path2 arguments are the paths to compare. This procedure
+may not raise script errors.
+
+
+
Private Procedure "getCommonContainingDirectory"
+
+
+
Required argument "fileNames"
+
+
+This procedure processes a list of (fully?) qualified file names and
+tries to determine their common containing directory, if any. The
+fileNames argument is the list of (fully?) qualified file names to
+process. This procedure may not raise script errors. If there is
+no common containing directory, an empty string is returned.
+
+
+
Private Procedure "getRelativeFileNames"
+
+
+
Required argument "fileNames"
+
+
Required argument "maximumLevels"
+
+
+This procedure attempts to process a list of (fully?) qualified file
+names and return the corresponding list of relative file names. The
+fileNames argument is the list of (fully?) qualified file names to
+process. The maximumLevels argument is the maximum path depth that
+is allowed for all file names. This procedure may raise script
+errors.
+
+
+
Private Procedure "getScriptChunkForFileNames"
+
+
+
Required argument "fileNames"
+
+
Required argument "maximumLevels"
+
+
+This procedure attempts to create a script chunk that appends the
+specified list of file names to a list variable. The fileNames
+argument is the list of (fully?) qualified file names to append to
+the list variable. The maximumLevels argument is the maximum path
+depth that is allowed for all file names. This procedure may raise
+script errors.
+
+
+
Private Procedure "createRepositoryScript"
+
+
+
Required argument "serverId"
+
+
Required argument "versionId"
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "platform"
+
+
Required argument "fileNames"
+
+
Required argument "options"
+
+
+This procedure creates and returns a script block designed for use
+with the package repository server in order to download and provide
+a package consisting of a set of files. The serverId argument is
+the identifier for the specific server to use, if any. The
+versionId argument is the identifier for the specific version to use,
+if any. The language argument must be the literal string "eagle" or
+the literal string "tcl". The version argument must be one of the
+literal strings "8.4", "8.5", or "8.6" when the language is "tcl"
+-OR- the literal string "1.0" when the language is "eagle". The
+platform argument must be an empty string -OR- one of the literal
+strings "neutral", "win32-arm", "win32-x86", "win64-arm64",
+"win64-ia64", or "win64-x64". The fileNames argument is the list of
+(fully?) qualified file names to be downloaded when the associated
+package is being provided. The options argument is reserved for
+future use, it should be an empty list.
+
+
+
Private Procedure "createMultipartFormData"
+
+
+
Required argument "boundary"
+
+
Required argument "request"
+
+
+This procedure creates textual data that conforms to the content
+type "multipart/form-data", per RFC 2388. The boundary argument
+is a boundary value, as specified in section 4.1 of the RFC. The
+request argument is the dictionary of name/value pairs to include
+in the form body. This procedure may not raise script errors.
+
+
+
Private Procedure "getSubmitUri"
+
+
+This procedure returns the full URI to use when submitting a new
+package to the package repository server. There are no arguments.
+This procedure may raise script errors.
+
+
+
Private Procedure "submitPackageMetadata"
+
+
+
Required argument "apiKey"
+
+
Required argument "package"
+
+
Required argument "patchLevel"
+
+
Required argument "language"
+
+
Required argument "script"
+
+
Required argument "certificate"
+
+
+This procedure attempts to submit the metadata for a new package to
+the package repository server. Upon success, an empty string will
+be returned. Upon failure, a script error will be raised. The
+apiKey argument is the list of API keys to use. The package argument
+is the name of the package. The patchLevel argument is the specific
+patch level being submitted. The language argument must be an empty
+string, "Tcl", or "Eagle". If it is an empty string, the current
+language will be assumed. The script argument is the script to be
+evaluated when the package needs to be provided. The certificate
+argument is the certificate associated with the script, which may be
+an OpenPGP signature or a Harpy script certificate.
+
+
+
Private Procedure "getCheckoutId"
+
+
+This procedure attempts to query the identifier of the Fossil
+checkout. There are no arguments. An empty string is returned if
+the information cannot be determined.
+
+
+
Private Procedure "getCheckoutDirectory"
+
+
+This procedure attempts to query the root directory of the Fossil
+checkout. There are no arguments. An empty string is returned if
+the information cannot be determined.
+
+
+
Private Procedure "joinPath"
+
+
+
Required argument "args"
+
+
+This procedure builds a native path using the specified parts and
+returns it. All arguments are considered to be parts of the path.
+
+
+
Private Procedure "verifyCheckoutDirectory"
+
+
+This procedure attempts to verify that the root directory of the
+Fossil checkout is present, valid, and is actually a directory.
+There are no arguments. Script errors will be raised if any of
+the checks fail.
+
+
+
Private Procedure "fossilMustBeInstalled"
+
+
+This procedure attempts to verify that an implementation of Fossil
+is installed locally. There are no arguments. Script errors are
+raised if any problems are found. The return value is undefined.
+
+
+
Private Procedure "verifyThereAreNoChanges"
+
+
+This procedure attempts to verify that the checkout directory does
+not contain any (stray) changes. There are no arguments. Non-zero
+is returned if the verification is successful.
+
+
+
Private Procedure "verifyThisIsTheCorrectProject"
+
+
+This procedure attempts to verify that the checkout directory does
+belong to the correct project. There are no arguments. Non-zero
+is returned if the verification is successful.
+
+
+
Private Procedure "verifyThisIsTheCorrectBranch"
+
+
+This procedure attempts to verify that the checkout directory does
+belong to the correct branch. There are no arguments. Non-zero
+is returned if the verification is successful.
+
+
+
Private Procedure "changeToTheCorrectBranch"
+
+
+This procedure attempts to change the branch for the checkout
+directory. There are no arguments. This procedure may raise
+script errors.
+
+
+
Private Procedure "stageOnePackageFile"
+
+
+
Required argument "targetDirectory"
+
+
Required argument "fileName"
+
+
+This procedure attempts to stage the specified package file using
+Fossil. The targetDirectory argument is the fully qualified path
+to the package platform directory. The fileName argument is the
+relative name of the file to be staged. This procedure may raise
+script errors.
+
+
+
Private Procedure "stagePackageFiles"
+
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "platform"
+
+
Required argument "fileNames"
+
+
+This procedure attempts to stage the specified package files using
+Fossil. The fileNames argument is a list of (fully?) qualified
+local file names to stage.
+
+
+
Private Procedure "commitPackageFiles"
+
+
+
Required argument "package"
+
+
Required argument "patchLevel"
+
+
Required argument "language"
+
+
Required argument "version"
+
+
Required argument "varName"
+
+
+This procedure attempts to commit the staged package files to the
+remote package file repository using Fossil. The varName argument
+is the name of a scalar variable in the context of the immediate
+caller that will receive the resulting Fossil check-in identifier.
+
+
+
Internal API Procedure "setupArgumentData"
+
+
+
Required argument "argv"
+
+
+This procedure initializes the array containing data derived from
+the command line arguments, if any. The argv argument should be
+the list of command line arguments.
+
+
+
Internal API Procedure "haveArgumentData"
+
+
+This procedure is used to determine if all the package submission
+data is available. There are no arguments. Non-zero is returned
+if all the package submission data is available. This procedure
+should not raise script errors.
+
+
+
Private Procedure "textBoxEventHandler"
+
+
+
Required argument "varName"
+
+
Required argument "sender"
+
+
Required argument "e"
+
+
+This procedure is an event handler. It handles the Changed event
+for a text box. It is not used when the user interface was built
+with Tk. The varName argument is the name of the scalar variable
+that must be updated with the contents of the text box. The sender
+and e arguments are provided by the framework and represent the
+control involved in the event and any extra data that may be
+necessary to process the event.
+
+
+
Private Procedure "listBoxEventHandler"
+
+
+
Required argument "varName"
+
+
Required argument "args"
+
+
+This procedure is an event handler. It handles double-clicking the
+list box in both Tk and Eagle. The varName argument is the name of
+the scalar variable that must be updated with the list of items from
+the list box -OR- the list of items from an interactive file picker
+dialog. The args argument, which is only used for Eagle, is a list
+containing two elements. The first element is the control involved
+in the event. The second element is any extra data that may be
+necessary to process the event.
+
+
+
Private Procedure "handleFormClosedEvent"
+
+
+
Required argument "args"
+
+
+This procedure is an event handler. It handles the Closed event for
+a WinForms form -OR- the WM_DELETE_WINDOW event on a Tk window. The
+args argument is not really used, it is a placeholder to make this
+procedure more portable between Tcl and Eagle. This procedure may
+raise script errors.
+
+
+
Internal API Procedure "submitEventHandler"
+
+
+
Required argument "args"
+
+
+This procedure is an event handler. It handles the submit button in
+both Tk and Eagle. It starts the package submission process. The
+args argument is not really used, it is a placeholder to make this
+procedure more portable between Tcl and Eagle. This procedure may
+raise script errors.
+
+
+
Private Procedure "clearEventHandler"
+
+
+
Required argument "args"
+
+
+This procedure is an event handler. It handles the clear button in
+Tk and Eagle. It is used to clear the package submission data. The
+args argument is not really used, it is a placeholder to make this
+procedure more portable between Tcl and Eagle. This procedure may
+raise script errors.
+
+
+
Internal API Procedure "setupWinFormsUserInterface"
+
+
+This procedure creates the user interface for this tool using Eagle
+and WinForms. The existing argument data, if any, will be used to
+populate it. There are no arguments.
+
+
+
Internal API Procedure "setupTkUserInterface"
+
+
+This procedure creates the user interface for this tool using Tcl
+and Tk. The existing argument data, if any, will be used to
+populate it. There are no arguments.
+
+