Solidity 深入

原文链接
date:20170616

这一章节将会告诉你所有你需要知道的有关solidity的信息。如果需要补充，请在gitter中联系我们，或者在Github中提交请求。

Solidity代码结构分析

原文链接
solidity代码文件可以包含任意多的合约定义，包括指令和编译指令（pragma directives）。

版本pragma

源文件需要用版本pragma来指示编译器将该源码编译成特定版本，以免造成不兼容问题。我们尽量保持小更改，并且在版本语义上做相应的改变，但是这通常是不可能的。所以也至少需要查看下新的发行版的更改日志，这些版本的版本号通常是从0.X.0变更为x.0.0。
版本pragma如下所示：

pragma solidity ^0.4.0;

这个源码不支持0.4.0之前的编译器，也不支持0.5.0的编译器（这个条件是因为有^符号）。这个理念是版本0.5.0之前不会发生不兼容的问题，这保证了代码的正确运行。我们也不指定一个特定的版本，所以bug修复版本依旧可以编译通过。
我们也可以给编译器版本指定更加复杂的条件，规则和npm的规则一样。

导入其他源码

语法和语义

Solidity支持import声明，非常像ES6的语法，尽管Solidity并不知道"默认导入"的概念。
在全局范围内，你可以用如下的形式引入源文件：

import "filename";

这个声明导入了“filename”源码中所有的全局变量（以及在filename中导入的其他文件的变量）。与ES6不同的是这是后向兼容的。

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";

路径

以上的例子，filename是用/作为目录分割符，.作为当前目录，..作为父目录的路径。当.或者..后面不是跟随/的时候，并不会当作是当前目录或父目录。所有的路径都当作绝对路径，除非是.或者..开头的。
如果要导入当前目录下的x文件，使用import "./x" as x.如果你使用import "x" as x,一个不同的文件将会被引入进来（在全局包含了整个文件夹）。
如何解决路径问题取决于编译器。一般情况下，目录不要求严格的于本地目录相一致，它也可以通过ipfs，http或者git映射。

使用编译器

当编译器被调用的时候，不仅可以指定如何解释路径，也可以指定路径前缀的映射。例如github.com/etherum/dapp-bin/library可以映射为/usr/local/dapp-bin/library，编译器会从指定路径获取文件。如果指定了多个映射，最长的那个映射将会先尝试。同样也支持”反向映射“，例如“”映射为“／usr/local/include/solidity”。另外，这些映射可以通过上下文来确定，这允许我们可以配置导入不同的版本的库。

solc:

对于solc(命令行编译器)，这些映射配置通过参数context:prefix=traget提供，其中context与=target都是可选的（这种情况下，target默认为前缀）。所有映射对应的常规文件都会被编译（包括它们的依赖）。这种机制如果没有不兼容的更新，完全是后向兼容的（只要文件名称不包含=或者：）。所有导入进来的文件或者是context路径下的文件，以prefix文件开头的会重新映射为target开头。
来，举个例子，如果你clone了github.com/ethereum/deapp-bin/到本地的/usr/lcoal/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

来个更加复杂些的例子，假设你依赖了一些使用了很久版本的模块。旧版本的代码在/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

所以moudle2的导入指向了原来的版本，在moudle1中导入的新的版本。
注意solc只允许你从特定的目录导入：这些模块的路径（或者子路径）必须在一个特定的源码路径下或者在映射的路径下。如果你想用绝对路径，那只需添加映射=/。
如果多个映射都指向了一个合法的文件，编译器会选择具有最长的前缀的文件（ps：也就是说是最先解析到的文件）。

Remix：

Remix提供了自动映射到github的服务，也可以自动的通过网络获取文件。例如你可以导入遍历映射库：

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

其他源码服务将会在未来添加进来。

注释

单行注释（//）以及多行注释(/* */)都是允许的。

// 这是一个单行注释

/*
这是一个
奇迹：P(多行注释).
*/

另外，还有一种注释，称为natspec注释，它的文档，尚未写出来。它们由三个斜杠///开始，或者通过块注释符/** */包裹。它们应该在函数定义或者函数声明的时候，添加在它们上方。在注释中你可以使用Doxygen标记，通过注释条件来实现验证（annotate conditions for formal verification），并且可以在用户调用函数的时候，提供一个确认文本。
在下面的例子中，我们给合约声明了标题，两个输入参数的解释和两个返回值。

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);
    }
}