序言
本文是 Solidity 文檔（以太坊官方 Solidity 開發(fā)手冊）中文版連載的第四部分。這個連載的前三部分是智能合約概述、安裝 Solidity 編譯器和結(jié)合實例學習 Solidity。
這份文檔的英文原文可以在以太坊官網(wǎng)的最下方 Solidity 鏈接中找到。官方的英文版本文檔中有中譯版鏈接，即是本連載內(nèi)容的出處。這個連載將按照英文文檔的先后順序進行。
Solidity 是以太坊官方的智能合約開發(fā)高級語言。這份中文譯本是由 Hiblock 社區(qū)組織貢獻的，官方 Github：https://github.com/etherchina/solidity-doc-cn。
我本人于 3 月初加入本項目，目前作為管理員、貢獻者和校訂人利用業(yè)余時間參與日常工作；截至到 4 月底，翻譯工作已完成大半。有興趣的朋友請直接在以太坊官網(wǎng)的鏈接中查看最新中文版本狀態(tài)，或者關(guān)注上述中文譯本的 Github repository。
出于單獨閱讀的需要，我在連載中會刪除原文里的 rst 控制標簽、文內(nèi)鏈接和部分外部鏈接。
本文是在具體介紹 Solidity 語法、語言特性之前的鋪墊，介紹了 Solidity 源文件中除具體合約代碼以外的其他要素。

Solidity 源文件結(jié)構(gòu)

源文件中可以包含任意多個合約定義、導(dǎo)入指令和雜注指令。

版本雜注

為了避免未來被可能引入不兼容變更的編譯器所編譯，源文件可以（也應(yīng)該）被所謂的版本雜注所注解。
我們力圖把這類變更做到盡可能小，特別是，我們需要以一種當修改語義時必須同步修改語法的方式引入變更，當然這有時候也難以做到。
因此，至少對含重大變更的版本，通讀變更日志永遠是好辦法。
這些版本的版本號始終是 0.x.0 或者 x.0.0 的形式。

版本雜注使用如下

pragma solidity ^0.4.0;

這樣，源文件將既不允許低于 0.4.0 版本的編譯器編譯，
也不允許高于（包含）0.5.0 版本的編譯器編譯（第二個條件因使用 ^ 被添加）。
這種做法的考慮是，編譯器在 0.5.0 版本之前不會有重大變更，所以可確保源代碼始終按預(yù)期被編譯。
上面例子中不固定編譯器的具體版本號，因此編譯器的補丁版也可以使用。

可以使用更復(fù)雜的規(guī)則來指定編譯器的版本，表達式遵循 npm 版本語義。

Pragma 是 pragmatic information 的簡稱，微軟 Visual C++ 文檔 中譯為雜注。
Solidity 中沿用 C ，C++ 等中的編譯指令概念，用于告知編譯器 如何 編譯。
——譯者注

導(dǎo)入其他源文件

語法與語義

雖然 Solidity 不知道“default export”為何物，
但是 Solidity 所支持的導(dǎo)入語句，其語法同 JavaScript（從 ES6 起）非常類似。

ES6 即 ECMAScript 6.0，ES6是 JavaScript 語言的下一代標準，已經(jīng)在 2015 年 6 月正式發(fā)布。
——譯者注

在全局層面上，可使用如下格式的導(dǎo)入語句：

import "filename";

此語句將從“filename”中導(dǎo)入所有的全局符號到當前全局作用域中（不同于 ES6，Solidity 是向后兼容的）。

import * as symbolName from "filename";

...創(chuàng)建一個新的全局符號 symbolName，其成員均來自 "filename" 中全局符號。

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

...創(chuàng)建新的全局符號 alias 和 symbol2，分別從 "filename" 引用 symbol1 和 symbol2 。

另一種語法不屬于 ES6，但或許更簡便：

import "filename" as symbolName;

這條語句等同于 import * as symbolName from "filename";。

路徑

上文中的 filename 總是會按路徑來處理，以 / 作為目錄分割符、以 . 標示當前目錄、以 .. 表示父目錄。
當 . 或 .. 后面跟隨的字符是 / 時，它們才能被當做當前目錄或父目錄。
只有路徑以當前目錄 . 或父目錄 .. 開頭時，才能被視為相對路徑。

用 import "./x" as x; 語句導(dǎo)入當前源文件同目錄下的文件 x 。
如果用 import "x" as x; 代替，可能會引入不同的文件（在全局 include directory 中）。

最終導(dǎo)入哪個文件取決于編譯器（見下文）到底是怎樣解析路徑的。
通常，目錄層次不必嚴格映射到本地文件系統(tǒng)，
它也可以映射到能通過諸如 ipfs，http 或者 git 發(fā)現(xiàn)的資源。

在實際的編譯器中使用

當運行編譯器時，它不僅能指定如何發(fā)現(xiàn)路徑的第一個元素，還可指定路徑前綴重映射。
例如，github.com/ethereum/dapp-bin/library 會被重映射到 /usr/local/dapp-bin/library，
此時編譯器將從重映射位置讀取文件。如果重映射到多個路徑，優(yōu)先嘗試重映射路徑最長的一個。
這允許將比如 "" 被映射到 "/usr/local/include/solidity" 來進行“回退重映射”。
同時，這些重映射可取決于上下文，允許你配置要導(dǎo)入的包，比如同一個庫的不同版本。

solc:

對于 solc（命令行編譯器），這些重映射以 context:prefix=target 形式的參數(shù)提供。
其中，context: 和 =target 部分是可選的（此時 target 默認為 prefix ）。
所有重映射的值都是被編譯過的常規(guī)文件（包括他們的依賴），這個機制完全是向后兼容的（只要文件名不包含 = 或 : ），
因此這不是一個破壞性修改。
在 content 目錄或其子目錄中的源碼文件中，所有導(dǎo)入語句里以 prefix 開頭的導(dǎo)入文件都將被用 target 替換 prefix 來重定向。

舉個例子，如果你已克隆 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

舉個更復(fù)雜的例子，假設(shè)你依賴了一些使用了非常舊版本的 dapp-bin 的模塊。
舊版本的 dapp-bin 已經(jīng)被 checkout 到 /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 中的所有導(dǎo)入都指向舊版本，而 module1 中的導(dǎo)入則獲取新版本。

注意， solc 只允許包含來自特定目錄的文件：它們必須位于顯式地指定的源文件目錄（或子目錄）中，或者重映射的目標目錄（或子目錄）中。
如果你想直接用絕對路徑來包含文件，只需添加重映射 =/。

如果有多個重映射指向一個有效文件，那么具有最長公共前綴的重映射會被選用。

Remix:

Remix 提供一個為 github 源代碼平臺的自動重映射，它將通過網(wǎng)絡(luò)自動獲取文件：
比如，你可以使用 import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping; 導(dǎo)入一個 map 迭代器。

未來，Remix 可能支持其他源代碼平臺。

注釋

可以使用單行注釋（//）和多行注釋（/*...*/）

// 這是一個單行注釋。

/*
這是一個
多行注釋。
*/

此外，有另一種注釋稱為 natspec 注釋，其文檔還尚未編寫。
它們是用三個反斜杠（///）或雙星號開頭的塊（/** ... */）書寫，它們應(yīng)該直接在函數(shù)聲明或語句上使用。
可在注釋中使用 Doxygen 樣式的標簽來文檔化函數(shù)、
標注形式校驗通過的條件，和提供一個當用戶試圖調(diào)用一個函數(shù)時顯示給用戶的 確認文本。

在下面的例子中，我們記錄了合約的標題、兩個入?yún)⒑蛢蓚€返回值的說明：

pragma solidity ^0.4.0;

/** @title 形狀計算器。 */
contract shapeCalculator {
    /** @dev 求矩形表明面積與周長。
      * @param w 矩形寬度。
      * @param h 矩形高度。
      * @return s 求得表面積。
      * @return p 求得周長。
      */
    function rectangle(uint w, uint h) returns (uint s, uint p) {
        s = w * h;
        p = 2 * (w + h);
    }
}