c20 progress

Author: straightdave

19-sigils.md

@@ -11,17 +11,20 @@ Sigil原意是“魔符，图章，印记”，
 本章（或者本文）所有的*sigil*都会翻译成“魔法印”或是采用英文原文。
 
 我们已经学习了Elixir提供的字符串（双引号包裹）和字符列表（单引号包裹）。
-但是对于Elixir中所有的*文本描述型数据类型*来说，这些只是冰山一角。其它的，例如*原子*也是一种文本描述型数据类型。
+但是对于Elixir中所有的*文本描述型数据类型*来说，这些只是冰山一角。其它的，
+例如*原子*也是一种文本描述型数据类型。
 
 Elixir的一个特点就是高可扩展性：开发者能够为特定的领域来扩展语言。
 计算机科学的领域已是如此广阔。几乎无法设计一门语言来涵盖所有范围。
-我们的打算是，与其创造出一种万能的语言，不如创造一种可扩展的语言，让开发者可以根据所从事的领域来对语言进行扩展。
+我们的打算是，与其创造出一种万能的语言，不如创造一种可扩展的语言，
+让开发者可以根据所从事的领域来对语言进行扩展。
 
 本章将讲述“魔法印（sigils）”，它是Elixir提供的处理文本描述型数据的一种机制。
 
 ## 19.1-正则表达式
-魔法印以波浪号（~）起头，后面跟着一个字母，然后是分隔符。
-最常用的魔法印是~r，代表[正则表达式](https://en.wikipedia.org/wiki/Regular_Expressions)：
+魔法印以波浪号（~）起头，后面跟着一个字母，然后是分隔符。最常用的魔法印是~r，
+代表[正则表达式](https://en.wikipedia.org/wiki/Regular_Expressions)：
+
 ```elixir
 # A regular expression that returns true if the text has foo or bar
 iex> regex = ~r/foo|bar/
@@ -35,6 +38,7 @@ false
 Elixir提供了Perl兼容的正则表达式（regex），由[PCRE库](http://www.pcre.org/)实现。
 
 正则表达式支持修饰符（modifiers），例如```i```修饰符使该正则表达式无视大小写：
+
 ```elixir
 iex> "HELLO" =~ ~r/hello/
 false
@@ -45,6 +49,7 @@ true
 阅读[Regex模块](http://elixir-lang.org/docs/stable/elixir/Regex.html)获取关于其它修饰符的及其所支持的操作的更多信息。
 
 目前为止，所有的例子都用了```/```界定正则表达式。事实上魔法印支持8种不同的分隔符：
+
 ```elixir
 ~r/hello/
 ~r|hello|
@@ -64,33 +69,38 @@ true
 除了正则表达式，Elixir还提供了三种魔法印。
 
 魔法印```~s``` 用来生成字符串，类似双引号的作用：
+
 ```elixir
 iex> ~s(this is a string with "quotes")
 "this is a string with \"quotes\""
 ```
 通过这个例子可以看出，如果文本中有双引号，又不想逐个转义，可以用这种魔法印来包裹字符串。
 
 魔法印```~c``` 用来生成字符列表：
+
 ```elixir
 iex> ~c(this is a string with "quotes")
 'this is a string with "quotes"'
 ```
 
 魔法印```~w``` 用来生成单词，以空格分隔开：
+
 ```elixir
 iex> ~w(foo bar bat)
 ["foo", "bar", "bat"]
 ```
 
 魔法印```~w``` 还接受```c```，```s```和```a```修饰符（分别代表字符列表，字符串和原子）
 来选择结果的类型：
+
 ```elixir
 iex> ~w(foo bar bat)a
 [:foo, :bar, :bat]
 ```
 
 除了小写的魔法印，Elixir还支持大写的魔法印。如，```~s```和```~S```都返回字符串，
 前者会解释转义字符而后者不会：
+
 ```elixir
 iex> ~s(String with escape codes \x26 interpolation)
 "String with escape codes & interpolation"
@@ -118,6 +128,7 @@ iex> ~S(String without escape codes and without #{interpolation})
 
 
 魔法印还支持多行文本（heredocs），使用的是三个双引号或单引号：
+
 ```elixir
 iex> ~s"""
 ...> this is
@@ -127,6 +138,7 @@ iex> ~s"""
 
 最常见的有多行文本的魔法印就是写注释文档了。
 例如，如果你要在注释里写一些转义字符，这有可能会报错。
+
 ```elixir
 @doc """
 Converts double-quotes to single-quotes.
@@ -141,6 +153,7 @@ def convert(...)
 ```
 
 使用```~S```，我们就可以避免问题：
+
 ```elixir
 @doc ~S"""
 Converts double-quotes to single-quotes.
@@ -157,18 +170,22 @@ def convert(...)
 ### 19.3-自定义魔法印
 本章开头提到过，魔法印是可扩展的。事实上，魔法印```~r/foo/i```等于是
 用两个参数调用了函数```sigil_r```：
+
 ```elixir
 iex> sigil_r(<<"foo">>, 'i')
 ~r"foo"i
 ```
+
 就是说，我们可以通过该函数阅读魔法印```~r```的文档：
+
 ```elixir
 iex> h sigil_r
 ...
 ```
 
 我们也可以通过实现相应的函数来提供我们自己的魔法印。例如，我们来实现一个```~i(N)```魔法印，
 返回整数：
+
 ```elixir
 iex> defmodule MySigils do
 ...>   def sigil_i(string, []), do: String.to_integer(string)

20-typespecs-behaviors.md

@@ -13,7 +13,7 @@ Elixir是一门动态类型语言，Elixir中所有数据类型都是在运行
 
 默认地，Elixir提供了一些基础数据类型，比如 `integer` 或者 `pid`。还有其它一些复杂的：
 如函数`round/1`，它对一个float类型的数值四舍五入。
-它以一个`number`（一个`integer`或`float`）作为参数，返回一个`integer`。 
+它以一个`number`（一个`integer`或`float`）作为参数，返回一个`integer`。
 
 [round函数的文档](http://elixir-lang.org/docs/stable/elixir/Kernel.html#round/1)
 里面描述`round/1`的函数签名为：
@@ -53,11 +53,13 @@ defmodule LousyCalculator do
 end
 ```
 
-从例子中可以看出，元祖是复合类型。每个元祖都定义了其具体元素类型。
+从例子中可以看出，元组是复合类型。每个元组都定义了其具体元素类型。
 至于为何是`String.t`而不是`string`，可以参考
 [这篇文章](http://elixir-lang.org/docs/stable/elixir/typespecs.html#Notes)。
 
-Defining function specs this way works, but it quickly becomes annoying since we're repeating the type `{number, String.t}` over and over. We can use the `@type` directive in order to declare our own custom type.
+像这样定义函数规格说明是没问题，但是一次次重复写这种复合类型的
+样式名称`{number, String.t}`，很快会厌烦。
+我们可以使用`@type`指令来声明我们自定义的类型：
 
 ```elixir
 defmodule LousyCalculator do
@@ -74,9 +76,9 @@ defmodule LousyCalculator do
 end
 ```
 
-The `@typedoc` directive, similarly to the `@doc` and `@moduledoc` directives, is used to document custom types.
+指令`@typedoc`，和`@doc`或`@moduledoc`指令类似，被用来记录自定义类型。
 
-Custom types defined through `@type` are exported and available outside the module they're defined in:
+自定义类型通过`@type`定义，可以从其定义的模块导出并被外界访问：
 
 ```elixir
 defmodule QuietCalculator do
@@ -88,11 +90,15 @@ defmodule QuietCalculator do
 end
 ```
 
-If you want to keep a custom type private, you can use the `@typep` directive instead of `@type`.
+如果想要将某个自定义类型保持私有，可以使用 `@typep` 指令代替 `@type` 。
 
-### Static code analysis
+### 静态代码分析
 
-Typespecs are not only useful to developers and as additional documentation. The Erlang tool [Dialyzer](http://www.erlang.org/doc/man/dialyzer.html), for example, uses typespecs in order to perform static analysis of code. That's why, in the `QuietCalculator` example, we wrote a spec for the `make_quiet/1` function even if it was defined as a private function.
+Typespecs的作用不仅仅是被用来作为程序文档说明。举个例子，
+Erlang工具[Dialyzer][Dialyzer](http://www.erlang.org/doc/man/dialyzer.html)
+使用typespecs来进行代码静态分析。
+这就是为什么我们在 `QuiteCalculator` 例子中，
+即使 `make_quite/1` 是个私有函数，也写了函数规格说明。
 
 ## Behaviours