import (macro)
Package: CURL.LANGUAGE.COMPILER

Signature

{import [access] [explicit-names from] PACKAGE-NAME
[, using-name=LOCAL-NAME ]
[, override?:bool = false ]
[, location= {url "path"} ]
[, id="ComponentID-string" ]
[, transitive-id="ComponentID-string" ]
[, version=version ]
[, name = value ] ...
}

Makes the names in another Package available in the current package.

access: must be one of public or package, where package is the default if not specified. This controls the access level of imported names. If set to public, then all imported symbols will be re-exported to packages that import the current package.
explicit-names: specifies names to be imported from the package directly into the namespace. Otherwise, the only way to refer to imported names is by qualifying them with the package name (or LOCAL-NAME if specified). This must take one of the forms:

PACKAGE-NAME: is the name of the package to import. The package name must match the name used in the package declaration for the imported package. Unless overridden by the using-name keyword, this is the name that will be bound locally in the importing code.
using-name: specifies an alternate local name for the package that will be used in place of the actual PACKAGE-NAME.
override?: if true, causes names imported implicitly using {import * from ...} to override those from previous implicit imports without causing ambiguous name errors. Use of this option should be limited since it can often lead to surprising results.
location: specifies a possible location for an instance of the package and may be used multiple times within a single import statement.

The argument is either a url statement, a string containing an absolute URL, or a path relative to the URL of the importing source code, just like that accepted by the url statement. Location arguments are not required when importing standard Curl API packages.

If any locations are specified, then the package is guaranteed to have been loaded from one of those locations, although it may have been previously cached. Specifically, this means that one of the location arguments will match either the source-url-name or one of the origin-url-names of the meta-data of the imported package. [Note: previous versions of the Curl API do not make this guarantee!]

Note that Windows native paths (e.g. "C:\mystuff\mypackage.scurl") are treated as relative paths, not as absolute URLs, and therefore will not behave as you might expect; you must prefix such paths with "file:///" to turn them into absolute URLs.

If no locations are specified, then the default component manifest (see get-default-manifest) will be consulted to obtain location information for the package based on the package name and other attributes specified in this import statement.
id: specifies the id of the package to import.
transitive-id: specifies the transitive-id of the package to import.
version: specifies the version of the package to import. This is best specified as a string of the form:

"n.n...n" or "n.n...n+"

The version number will match version numbers in target packages whose components are identical up to the last of this version's components. If a "+" is appended to the version, it will match versions in target packages where the last component may be larger than what was specified.

For example:

Description

After a successful import, the imported package will be bound to its PACKAGE-NAME, with the following exceptions:

  1. If using-name specifies an alternate LOCAL-NAME, that name will be used instead of the PACKAGE-NAME.
  2. If an explicit list of names is specified in a from clause, and a using-name specifier is not provided, the package will not be bound to any local name.


This name may be used to access public members of the package, as shown in the examples below. The name may also be cast to a Package object, in order to obtain access to its meta-data (also below).

You can only use import in top-level code; that is, you cannot use import within code blocks. You may import the same package more than once within the same file.

For more information on packages and importing, see Packages in the Developer's Guide.

Programming Notes

Use public access when you want the symbols you import to also be accessible by any packages that import the current package. In other words, there is no reason to use public import in applets, since they cannot be imported. Typically, public import is used when creating "superpackages", which are packages whose primary purpose is to combine the APIs of several other packages. For instance, the standard Curl API package CURL.GUI.STANDARD uses this technique to re-export the contents of a variety of other more specific packages.

You may import different packages with the same name as long as they differ in some attribute other than the name, such as the version, id, or transitive id. In this case, you may need to use the using-name directive to avoid clashes between the names bound to the packages.

Use of override? should be limited because it can sometimes cause you to use code from the override package in place of an earlier version, when that was not the intent. It is best used when importing packages that provide text formats and other graphical objects that are intended to take the place of the standard versions provided by the Curl GUI API.

If you don't know what package you need to import until runtime or otherwise want to defer loading of a package for performance reasons, you should use the import-package function instead.

Unlike import-package, this syntax does not allow an alternate component manifest to be specified using the manifest keyword.

Example


Example: Importing symbols using import
|| This only imports the name 'e' from the 
|| specified package:
{import e from CURL.LANGUAGE.MATH-CONSTANT}
e == {value e}

|| This imports 'nan' from the package, but giving it
|| local name 'not-a-number':
{import nan as not-a-number from CURL.LANGUAGE.MATH-CONSTANT}
not-a-number == {value not-a-number}

|| This imports the name of the package itself:
{import CURL.LANGUAGE.MATH-CONSTANT}
pi == {value CURL.LANGUAGE.MATH-CONSTANT.pi}

|| This implicitly imports all public members 
|| of the package,  and binds the package to 
|| an alternate name:
{import * from CURL.LANGUAGE.MATH-CONSTANT, 
    using-name = CONSTANTS
}
ln 2 == {value ln-of-2}
ln of 10 = {value CONSTANTS.ln-of-10}



Example: Access imported packages' meta-data
{import CURL.LANGUAGE.MATH-CONSTANT, 
    using-name = CONSTANTS
}
package name == {value (CONSTANTS asa Package).name}

{let package:Package = CONSTANTS}
package version == {value package.meta-data.version}



Example: Use of override? and location keywords of import
|| Import personalized text formats, overriding 
|| the standard  ones.  Note that location specifiers 
|| referring to non-existent files will be ignored.
{import * from MY-TEXT-FORMATS,
    override? = true,
    version = "1.0",
    vendor = "Foobar Corporation",
    location = {url "file:///does-not-exist.scurl"},
    location = {url "file:///also-does-not-exist.scurl"},
    || There is really no reason to ever import a 
    || package from a string URL like this.  We 
    || only use it here so that the example is 
    || entirely self-contained.
    location = {url
        |"curl://string/
         {curl 6.0 package}
         {package MY-TEXT-FORMATS,
            version = "1.0",
            vendor = "Foobar Corporation"
         }
         {import CURL.GUI.TEXT-FORMATS}

         || Override the standard meaning of 'bold'
         {define-text-format public bold as
            CURL.GUI.TEXT-FORMATS.bold with color = "red"
         }
        "|}
}
{bold This is bold}