<Solidity学习系列二>深入理解Solidity之二---Solidity源代码文件结构

Solidity源代码文件结构

源文件可以包含任意数量的合约定义，包括指令和编译指示。

版本Pragma
源文件可以（也应该）用所谓的版本注释来注释，以拒绝被编译为未来可能引入不兼容更改的编译器版本。 我们试图将这种变化保持在绝对最低限度，特别是引入变化的方式是语义的变化也需要语法的变化，但这当然不总是可能的。 因此，至少对于包含重大更改的版本，通读更新日志总是一个好主意，这些版本始终具有0.x.0或x.0.0格式的版本。

版本附注使用如下：

pragma solidity ^0.4.0;

这样的源代码文件不会使用早于版本0.4.0的编译器进行编译，并且它也不适用于从版本0.5.0开始的编译器（第二个条件是使用^添加的）。 这背后的想法是，在版本0.5.0之前不会有任何重大更改，所以我们始终可以确定我们的代码将按照我们打算的方式进行编译。 我们不修复编译器的确切版本，因此bug修复版本仍然有可能。
可以为编译器版本指定更复杂的规则，表达式遵循npm使用的规则。

导入其他源文件
语法和语义

Solidity支持非常类似于JavaScript中可用的导入语句（来自ES6），尽管Solidity不知道“默认导出”的概念。

在全局范围内，您可以使用以下格式的导入语句：

import "filename";

该语句从“文件名”（及其导入的符号）中导入所有全局符号到当前全局作用域（与ES6不同，但向后兼容Solidity）。

import * as symbolName from "filename";

...创建一个新的全局符号symbolName，其成员全部来自“filename”的全局符号。

import {symbol1 as alias, symbol2} from "filename";

...分别创建新的全局符号alias和symbol2，它们分别从“filename”引用symbol1和symbol2。

另一种语法不是ES6的一部分，但可能很方便：

import "filename" as symbolName;

这相当于从import * as symbolName from "filename";。

Paths

在上面，filename总是被视为一个路径，其中/作为目录分隔符。.作为当前和..作为父目录。 什么时候 . 或..后跟一个除/以外的字符，它不被视为当前或父目录。 所有路径名都被视为绝对路径，除非它们以当前的.或父目录开头..。

要从与当前文件相同的目录中导入文件x，请使用import "./x" as x;. 如果使用import "x" as x; 则可以引用不同的文件（在全局“包含目录”中）。

它取决于编译器（见下文）如何实际解析路径。 通常，目录层次不需要严格映射到你的本地文件系统，它也可以映射到通过例如发现的资源。 ipfs，http或者git。

在实际编译器中使用

调用编译器时，不仅可以指定如何发现路径的第一个元素，但可以指定路径前缀重新映射，以便例如 github.com/ethereum/dapp-bin/library被重新映射到/usr/local/dapp-bin/library，编译器将从那里读取文件。 如果可以应用多重重映射，则首先尝试使用最长密钥的那个。 这允许用例如fallback-remapping ""映射到/usr/local/include/solidity

（原文：This allows for a "fallback-remapping" with e.g. "" maps to
> "/usr/local/include/solidity"） 翻译的不太通顺。

。 此外，这些重新映射可能取决于上下文，从而允许您配置要导入的包。 不同版本的同名图书馆。

solc:
对于solc（命令行编译器），这些重新映射是作为context：prefix = target参数提供的，其中context：和= target部分都是可选的（在这种情况下目标缺省为前缀）。 所有重映射值都是常规文件（包括它们的依赖关系）。 这种机制是完全向后兼容的（只要没有文件名包含=或:)，因此不是一个突破性的改变。 在导入以prefix开头的文件的context目录下的文件中的所有导入都将通过将prefix替换为target进行重定向。
例如，如果您将github.com/ethereum/dapp-bin/本地克隆到/usr/local/dapp-bin，则可以在源文件中使用以下内容：

import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;

然后运行编译器

solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol

作为一个更复杂的例子，假设你依赖于一些使用非常旧版本的dapp-bin的模块。 dapp-bin的旧版本在/usr/local/dapp-bin_old处检出，然后您可以使用：

solc module1:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ \
     module2:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin_old/ \
     source.sol
     

以便module2中的所有导入都指向旧版本，但module1中的导入将获得新版本。

请注意，solc仅允许您包含来自特定目录的文件：它们必须位于某个明确指定的源文件的目录（或子目录）中，或位于重新映射目标的目录（或子目录）中。 如果你想允许直接绝对包含，只需添加重新映射=/。

如果存在多个导致有效文件的重映射，则选择具有最长公共前缀的重映射。

Remix:

Remix为github提供了一个自动重新映射，并且还会自动通过网络检索文件：您可以通过导入可迭代映射例如：

import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;

未来可能会添加其他源代码提供者。

Comments
单行注释（//）和多行注释（/*...*/）是可用的。

// This is a single-line comment.

/*
This is a
multi-line comment.
*/

此外，还有另一种类型的注释称为natspec注释，对此文档尚未编写。 它们用三斜杠（///）或双星号块（/ ** ... * /）编写，它们应该直接用在函数声明或语句之上。 您可以在这些注释中使用Doxygen风格的标签来记录函数，为形式验证注释条件，并提供确认文本，当用户尝试调用函数时向用户显示。

在下面的例子中，我们记录了合同的标题，两个输入参数和两个返回值的解释。

    pragma solidity ^0.4.0;

/** @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.
      */
    function rectangle(uint w, uint h) returns (uint s, uint p) {
        s = w * h;
        p = 2 * (w + h);
    }
}