mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
Merge pull request #6153 from ethereum/docs-imports
[DOCS] Improve imports documentation
This commit is contained in:
commit
ee4beafd48
@ -96,7 +96,7 @@ The component does not yet support all features of the Solidity language
|
|||||||
and likely outputs many warnings. In case it reports unsupported
|
and likely outputs many warnings. In case it reports unsupported
|
||||||
features, the analysis may not be fully sound.
|
features, the analysis may not be fully sound.
|
||||||
|
|
||||||
.. index:: source file, ! import
|
.. index:: source file, ! import, module
|
||||||
|
|
||||||
.. _import:
|
.. _import:
|
||||||
|
|
||||||
@ -106,8 +106,8 @@ Importing other Source Files
|
|||||||
Syntax and Semantics
|
Syntax and Semantics
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
Solidity supports import statements that are very similar to those available in JavaScript
|
Solidity supports import statements to help modularise your code that are similar to those available in JavaScript
|
||||||
(from ES6 on), although Solidity does not know the concept of a "default export".
|
(from ES6 on). However, Solidity does not support the concept of a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#Description>`_.
|
||||||
|
|
||||||
At a global level, you can use import statements of the following form:
|
At a global level, you can use import statements of the following form:
|
||||||
|
|
||||||
@ -117,29 +117,21 @@ At a global level, you can use import statements of the following form:
|
|||||||
|
|
||||||
This statement imports all global symbols from "filename" (and symbols imported there) into the
|
This statement imports all global symbols from "filename" (and symbols imported there) into the
|
||||||
current global scope (different than in ES6 but backwards-compatible for Solidity).
|
current global scope (different than in ES6 but backwards-compatible for Solidity).
|
||||||
This simple form is not recommended for use, because it pollutes the namespace in an
|
This form is not recommended for use, because it unpredictably pollutes the namespace.
|
||||||
unpredictable way: If you add new top-level items inside "filename", they will automatically
|
If you add new top-level items inside "filename", they automatically
|
||||||
appear in all files that import like this from "filename". It is better to import specific
|
appear in all files that import like this from "filename". It is better to import specific
|
||||||
symbols explicitly.
|
symbols explicitly.
|
||||||
|
|
||||||
The following example creates a new global symbol ``symbolName`` whose members are all
|
The following example creates a new global symbol ``symbolName`` whose members are all
|
||||||
the global symbols from ``"filename"``.
|
the global symbols from ``"filename"``:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
import * as symbolName from "filename";
|
import * as symbolName from "filename";
|
||||||
|
|
||||||
If there is a naming collision, you can also rename symbols while importing.
|
which results in all global symbols being available in the format ``symbolName.symbol``.
|
||||||
This code
|
|
||||||
creates new global symbols ``alias`` and ``symbol2`` which reference ``symbol1`` and ``symbol2`` from inside ``"filename"``, respectively.
|
|
||||||
|
|
||||||
::
|
A variant of this syntax that is not part of ES6, but possibly useful is:
|
||||||
|
|
||||||
import {symbol1 as alias, symbol2} from "filename";
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Another syntax is not part of ES6, but probably convenient:
|
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
@ -147,31 +139,37 @@ Another syntax is not part of ES6, but probably convenient:
|
|||||||
|
|
||||||
which is equivalent to ``import * as symbolName from "filename";``.
|
which is equivalent to ``import * as symbolName from "filename";``.
|
||||||
|
|
||||||
.. note::
|
If there is a naming collision, you can rename symbols while importing. For example,
|
||||||
If you use `import "filename.sol" as moduleName;`, you access a contract called `C`
|
the code below creates new global symbols ``alias`` and ``symbol2`` which reference
|
||||||
from inside `"filename.sol"` as `moduleName.C` and not by using `C` directly.
|
``symbol1`` and ``symbol2`` from inside ``"filename"``, respectively.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
import {symbol1 as alias, symbol2} from "filename";
|
||||||
|
|
||||||
Paths
|
Paths
|
||||||
-----
|
-----
|
||||||
|
|
||||||
In the above, ``filename`` is always treated as a path with ``/`` as directory separator,
|
In the above, ``filename`` is always treated as a path with ``/`` as directory separator,
|
||||||
``.`` as the current and ``..`` as the parent directory. When ``.`` or ``..`` is followed by a character except ``/``,
|
and ``.`` as the current and ``..`` as the parent directory. When ``.`` or ``..`` is followed by a character except ``/``,
|
||||||
it is not considered as the current or the parent directory.
|
it is not considered as the current or the parent directory.
|
||||||
All path names are treated as absolute paths unless they start with the current ``.`` or the parent directory ``..``.
|
All path names are treated as absolute paths unless they start with the current ``.`` or the parent directory ``..``.
|
||||||
|
|
||||||
To import a file ``x`` from the same directory as the current file, use ``import "./x" as x;``.
|
To import a file ``filename`` from the same directory as the current file, use ``import "./filename" as symbolName;``.
|
||||||
If you use ``import "x" as x;`` instead, a different file could be referenced
|
If you use ``import "filename" as symbolName;`` instead, a different file could be referenced
|
||||||
(in a global "include directory").
|
(in a global "include directory").
|
||||||
|
|
||||||
It depends on the compiler (see below) how to actually resolve the paths.
|
It depends on the compiler (see :ref:`import-compiler`) how to actually resolve the paths.
|
||||||
In general, the directory hierarchy does not need to strictly map onto your local
|
In general, the directory hierarchy does not need to strictly map onto your local
|
||||||
filesystem, it can also map to resources discovered via e.g. ipfs, http or git.
|
filesystem, and the path can also map to resources such as ipfs, http or git.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
Always use relative imports like ``import "./filename.sol";`` and avoid
|
Always use relative imports like ``import "./filename.sol";`` and avoid
|
||||||
using ``..`` in path specifiers. In the latter case, it is probably better to use
|
using ``..`` in path specifiers. In the latter case, it is probably better to use
|
||||||
global paths and set up remappings as explained below.
|
global paths and set up remappings as explained below.
|
||||||
|
|
||||||
|
.. _import-compiler:
|
||||||
|
|
||||||
Use in Actual Compilers
|
Use in Actual Compilers
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user