2015-12-07 20:16:25 +00:00
|
|
|
********************************
|
|
|
|
Layout of a Solidity Source File
|
|
|
|
********************************
|
|
|
|
|
2016-08-19 17:57:21 +00:00
|
|
|
Source files can contain an arbitrary number of contract definitions, include directives
|
|
|
|
and pragma directives.
|
|
|
|
|
|
|
|
.. index:: ! pragma, version
|
|
|
|
|
2017-03-16 00:42:42 +00:00
|
|
|
.. _version_pragma:
|
|
|
|
|
2016-08-19 17:57:21 +00:00
|
|
|
Version Pragma
|
|
|
|
==============
|
|
|
|
|
|
|
|
Source files can (and should) be annotated with a so-called version pragma to reject
|
|
|
|
being compiled with future compiler versions that might introduce incompatible
|
2016-08-26 12:57:44 +00:00
|
|
|
changes. We try to keep such changes to an absolute minimum and especially
|
2016-08-19 17:57:21 +00:00
|
|
|
introduce changes in a way that changes in semantics will also require changes
|
|
|
|
in the syntax, but this is of course not always possible. Because of that, it is always
|
|
|
|
a good idea to read through the changelog at least for releases that contain
|
|
|
|
breaking changes, those releases will always have versions of the form
|
|
|
|
``0.x.0`` or ``x.0.0``.
|
|
|
|
|
|
|
|
The version pragma is used as follows::
|
|
|
|
|
|
|
|
pragma solidity ^0.4.0;
|
|
|
|
|
|
|
|
Such a source file will not compile with a compiler earlier than version 0.4.0
|
|
|
|
and it will also not work on a compiler starting form version 0.5.0 (this
|
|
|
|
second condition is added by using ``^``). The idea behind this is that
|
|
|
|
there will be no breaking changes until version ``0.5.0``, so we can always
|
|
|
|
be sure that our code will compile the way we intended it to. We do not fix
|
|
|
|
the exact version of the compiler, so that bugfix releases are still possible.
|
|
|
|
|
|
|
|
It is possible to specify much more complex rules for the compiler version,
|
|
|
|
the expression follows those used by npm.
|
2015-12-07 20:16:25 +00:00
|
|
|
|
|
|
|
.. index:: source file, ! import
|
|
|
|
|
2016-06-07 17:44:32 +00:00
|
|
|
.. _import:
|
|
|
|
|
2015-12-07 20:16:25 +00:00
|
|
|
Importing other Source Files
|
|
|
|
============================
|
|
|
|
|
2016-01-11 21:33:36 +00:00
|
|
|
Syntax and Semantics
|
|
|
|
--------------------
|
2015-12-07 20:16:25 +00:00
|
|
|
|
2016-01-11 21:33:36 +00:00
|
|
|
Solidity supports import statements that are very similar to those available in JavaScript
|
|
|
|
(from ES6 on), although Solidity does not know the concept of a "default export".
|
2015-12-07 20:16:25 +00:00
|
|
|
|
2016-01-11 21:33:36 +00:00
|
|
|
At a global level, you can use import statements of the following form:
|
2015-12-07 20:16:25 +00:00
|
|
|
|
2016-02-18 09:34:23 +00:00
|
|
|
::
|
2016-01-11 21:33:36 +00:00
|
|
|
|
2016-02-18 09:34:23 +00:00
|
|
|
import "filename";
|
2016-01-11 21:33:36 +00:00
|
|
|
|
2016-08-05 08:30:40 +00:00
|
|
|
This statement imports all global symbols from "filename" (and symbols imported there) into the
|
2016-02-18 09:34:23 +00:00
|
|
|
current global scope (different than in ES6 but backwards-compatible for Solidity).
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
import * as symbolName from "filename";
|
|
|
|
|
2016-05-24 17:57:36 +00:00
|
|
|
...creates a new global symbol ``symbolName`` whose members are all the global symbols from ``"filename"``.
|
2016-02-18 09:34:23 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
import {symbol1 as alias, symbol2} from "filename";
|
|
|
|
|
2016-05-24 17:57:36 +00:00
|
|
|
...creates new global symbols ``alias`` and ``symbol2`` which reference ``symbol1`` and ``symbol2`` from ``"filename"``, respectively.
|
2016-01-11 21:33:36 +00:00
|
|
|
|
|
|
|
Another syntax is not part of ES6, but probably convenient:
|
|
|
|
|
2016-02-18 09:34:23 +00:00
|
|
|
::
|
|
|
|
|
|
|
|
import "filename" as symbolName;
|
|
|
|
|
2016-08-05 08:45:52 +00:00
|
|
|
which is equivalent to ``import * as symbolName from "filename";``.
|
2016-01-11 21:33:36 +00:00
|
|
|
|
|
|
|
Paths
|
|
|
|
-----
|
|
|
|
|
2016-05-24 17:57:36 +00:00
|
|
|
In the above, ``filename`` is always treated as a path with ``/`` as directory separator,
|
2017-01-02 15:13:57 +00:00
|
|
|
``.`` 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.
|
|
|
|
All path names are treated as absolute paths unless they start with the current ``.`` or the parent directory ``..``.
|
2016-01-11 21:33:36 +00:00
|
|
|
|
2016-05-24 17:57:36 +00:00
|
|
|
To import a file ``x`` from the same directory as the current file, use ``import "./x" as x;``.
|
|
|
|
If you use ``import "x" as x;`` instead, a different file could be referenced
|
2016-01-11 21:33:36 +00:00
|
|
|
(in a global "include directory").
|
|
|
|
|
|
|
|
It depends on the compiler (see below) how to actually resolve the paths.
|
|
|
|
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.
|
|
|
|
|
2016-08-11 20:50:53 +00:00
|
|
|
Use in Actual Compilers
|
2016-01-11 21:33:36 +00:00
|
|
|
-----------------------
|
|
|
|
|
|
|
|
When the compiler is invoked, it is not only possible to specify how to
|
|
|
|
discover the first element of a path, but it is possible to specify path prefix
|
2016-05-24 17:57:36 +00:00
|
|
|
remappings so that e.g. ``github.com/ethereum/dapp-bin/library`` is remapped to
|
2017-01-02 15:55:29 +00:00
|
|
|
``/usr/local/dapp-bin/library`` and the compiler will read the files from there.
|
|
|
|
If multiple remappings can be applied, the one with the longest key is tried first. This
|
2016-05-24 17:57:36 +00:00
|
|
|
allows for a "fallback-remapping" with e.g. ``""`` maps to
|
2016-06-07 17:44:32 +00:00
|
|
|
``"/usr/local/include/solidity"``. Furthermore, these remappings can
|
|
|
|
depend on the context, which allows you to configure packages to
|
|
|
|
import e.g. different versions of a library of the same name.
|
2016-01-11 21:33:36 +00:00
|
|
|
|
2016-01-13 16:34:59 +00:00
|
|
|
**solc**:
|
|
|
|
|
2016-06-07 17:44:32 +00:00
|
|
|
For solc (the commandline compiler), these remappings are provided as
|
|
|
|
``context:prefix=target`` arguments, where both the ``context:`` and the
|
|
|
|
``=target`` parts are optional (where target defaults to prefix in that
|
2016-01-11 21:33:36 +00:00
|
|
|
case). All remapping values that are regular files are compiled (including
|
|
|
|
their dependencies). This mechanism is completely backwards-compatible (as long
|
2016-06-07 17:44:32 +00:00
|
|
|
as no filename contains = or :) and thus not a breaking change. All imports
|
|
|
|
in files in or below the directory ``context`` that import a file that
|
|
|
|
starts with ``prefix`` are redirected by replacing ``prefix`` by ``target``.
|
2015-12-07 20:16:25 +00:00
|
|
|
|
2016-01-13 16:34:59 +00:00
|
|
|
So as an example, if you clone
|
2016-05-24 17:57:36 +00:00
|
|
|
``github.com/ethereum/dapp-bin/`` locally to ``/usr/local/dapp-bin``, you can use
|
2016-01-13 16:34:59 +00:00
|
|
|
the following in your source file:
|
|
|
|
|
2016-02-18 10:00:33 +00:00
|
|
|
::
|
|
|
|
|
|
|
|
import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;
|
2016-01-13 16:34:59 +00:00
|
|
|
|
|
|
|
and then run the compiler as
|
|
|
|
|
2016-05-18 19:37:38 +00:00
|
|
|
.. code-block:: bash
|
2016-02-18 10:00:33 +00:00
|
|
|
|
|
|
|
solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol
|
2016-01-13 16:34:59 +00:00
|
|
|
|
2016-06-07 17:44:32 +00:00
|
|
|
As a more complex example, suppose you rely on some module that uses a
|
|
|
|
very old version of dapp-bin. That old version of dapp-bin is checked
|
2016-07-11 15:23:17 +00:00
|
|
|
out at ``/usr/local/dapp-bin_old``, then you can use
|
2016-06-07 17:44:32 +00:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
solc module1:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ \
|
|
|
|
module2:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin_old/ \
|
|
|
|
source.sol
|
|
|
|
|
|
|
|
so that all imports in ``module2`` point to the old version but imports
|
|
|
|
in ``module1`` get the new version.
|
|
|
|
|
2016-01-29 22:17:43 +00:00
|
|
|
Note that solc only allows you to include files from certain directories:
|
|
|
|
They have to be in the directory (or subdirectory) of one of the explicitly
|
|
|
|
specified source files or in the directory (or subdirectory) of a remapping
|
|
|
|
target. If you want to allow direct absolute includes, just add the
|
2016-05-24 17:57:36 +00:00
|
|
|
remapping ``=/``.
|
2016-01-29 22:17:43 +00:00
|
|
|
|
|
|
|
If there are multiple remappings that lead to a valid file, the remapping
|
|
|
|
with the longest common prefix is chosen.
|
|
|
|
|
2017-03-15 22:58:14 +00:00
|
|
|
**Remix**:
|
2016-01-13 16:34:59 +00:00
|
|
|
|
2017-03-15 22:58:14 +00:00
|
|
|
`Remix <https://remix.ethereum.org/>`_
|
2016-01-13 16:34:59 +00:00
|
|
|
provides an automatic remapping for github and will also automatically retrieve
|
|
|
|
the file over the network:
|
2016-01-11 21:33:36 +00:00
|
|
|
You can import the iterable mapping by e.g.
|
2016-05-24 17:57:36 +00:00
|
|
|
``import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;``.
|
2016-01-13 16:34:59 +00:00
|
|
|
|
|
|
|
Other source code providers may be added in the future.
|
2015-12-07 20:16:25 +00:00
|
|
|
|
|
|
|
|
|
|
|
.. index:: ! comment, natspec
|
|
|
|
|
|
|
|
Comments
|
|
|
|
========
|
|
|
|
|
2016-05-24 17:57:36 +00:00
|
|
|
Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible.
|
2015-12-07 20:16:25 +00:00
|
|
|
|
2016-02-18 10:08:20 +00:00
|
|
|
::
|
|
|
|
|
|
|
|
// This is a single-line comment.
|
2016-05-18 15:35:00 +00:00
|
|
|
|
2016-02-18 10:08:20 +00:00
|
|
|
/*
|
2016-05-18 15:35:00 +00:00
|
|
|
This is a
|
2016-02-18 10:08:20 +00:00
|
|
|
multi-line comment.
|
|
|
|
*/
|
2016-05-18 15:35:00 +00:00
|
|
|
|
2016-02-18 10:08:20 +00:00
|
|
|
|
2016-04-20 11:53:36 +00:00
|
|
|
Additionally, there is another type of comment called a natspec comment,
|
|
|
|
for which the documentation is not yet written. They are written with a
|
2016-05-24 17:57:36 +00:00
|
|
|
triple slash (``///``) or a double asterisk block(``/** ... */``) and
|
2016-05-18 15:35:00 +00:00
|
|
|
they should be used directly above function declarations or statements.
|
2016-04-20 11:53:36 +00:00
|
|
|
You can use Doxygen-style tags inside these comments to document
|
2016-05-18 15:35:00 +00:00
|
|
|
functions, annotate conditions for formal verification, and provide a
|
2016-04-20 11:53:36 +00:00
|
|
|
**confirmation text** which is shown to users when they attempt to invoke a
|
|
|
|
function.
|
2016-08-05 11:16:14 +00:00
|
|
|
|
|
|
|
In the following example we document the title of the contract, the explanation
|
|
|
|
for the two input parameters and two returned values.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2016-09-05 11:54:54 +00:00
|
|
|
pragma solidity ^0.4.0;
|
|
|
|
|
2016-08-05 11:16:14 +00:00
|
|
|
/** @title Shape calculator.*/
|
|
|
|
contract shapeCalculator{
|
|
|
|
/**@dev Calculates a rectangle's surface and perimeter.
|
|
|
|
* @param w Width of the rectangle.
|
|
|
|
* @param h Height of the rectangle.
|
|
|
|
* @return s The calculated surface.
|
|
|
|
* @return p The calculated perimeter.
|
|
|
|
*/
|
2016-08-11 20:53:07 +00:00
|
|
|
function rectangle(uint w, uint h) returns (uint s, uint p) {
|
|
|
|
s = w * h;
|
|
|
|
p = 2 * (w + h);
|
2016-08-05 11:16:14 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|