From a8e5aaf64969792741f3a094fe0070ddb5e3bc7d Mon Sep 17 00:00:00 2001
From: Li Jin <dragon-fly@qq.com>
Date: Tue, 2 Nov 2021 16:12:03 +0800
Subject: update docs.

---
 CHANGELOG.md           | 34 ++++++++++++++++++++-
 README.md              |  2 +-
 doc/docs/doc/README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 109 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b60bf8a..1c87ff7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 The implementation for the original Moonscript language 0.5.0 can be found in the `0.5.0` branch of Yuescript. The Moonscript with fixes and new features is in the main branch of Yuescript. Here are the changelogs for each Yuescript version.
 
-## v0.8.2
+## v0.8.5
 
 ### Fixed Issues
 
@@ -11,6 +11,38 @@ The implementation for the original Moonscript language 0.5.0 can be found in th
 
 ### Added Features
 
+* Nil coalescing operator.
+```moonscript
+local a, b, c, d
+a = b ?? c ?? d
+func a ?? {}
+
+a ??= false
+```
+Compiles to:
+```lua
+local a, b, c, d
+if b ~= nil then
+  a = b
+else
+  if c ~= nil then
+    a = c
+  else
+    a = d
+  end
+end
+func((function()
+  if a ~= nil then
+    return a
+  else
+    return { }
+  end
+end)())
+if a == nil then
+  a = false
+end
+```
+
 * New metatable syntax.
   ```moonscript
   #: mt = tb
diff --git a/README.md b/README.md
index 479c232..0eaa557 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ Yue (月) is the name of moon in Chinese and it's pronounced as [jyɛ].
 * Support most of the features from Moonscript language. Generate Lua codes in the same way like the original compiler.
 * Reserve line numbers from source file in the compiled Lua codes to help debugging.
 * More features like macro, existential operator, pipe operator, Javascript-like export syntax and etc.
-* See other details in the [changelog](./CHANGELOG.md). Find document from [here](http://yuescript.org).
+* See other details in the [changelog](./CHANGELOG.md). Find document [here](http://yuescript.org).
 
 
 
diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md
index 138d035..b4ae85f 100755
--- a/doc/docs/doc/README.md
+++ b/doc/docs/doc/README.md
@@ -38,7 +38,7 @@ inventory =
 apple =
   size: 15
   index#: {color: 0x00ffff}
-p apple.color, apple.#?, apple.index#
+p apple.color, apple.index# if apple.#?
 
 -- js-like export syntax
 export yuescript = "月之脚本"
@@ -70,7 +70,7 @@ inventory =
 apple =
   size: 15
   index#: {color: 0x00ffff}
-p apple.color, apple.#?, apple.index#
+p apple.color, apple.index# if apple.#?
 
 -- js-like export syntax
 export yuescript = "月之脚本"
@@ -160,9 +160,11 @@ Usage: yue [options|files|directories] ...
 &emsp;&emsp;Execute raw codes:  **yue -e 'print 123'**  
 &emsp;&emsp;Execute a Yuescript file:  **yue -e main.yue**
 
+
 ## Macro
 
 ### Common Usage
+
 Macro function is used for evaluating a string in the compile time and insert the generated codes into final compilation.
 
 ```moonscript
@@ -298,7 +300,6 @@ export macro map = (items, action)-> "[#{action} for _ in *#{items}]"
 export macro filter = (items, action)-> "[_ for _ in *#{items} when #{action}]"
 export macro foreach = (items, action)-> "for _ in *#{items}
   #{action}"
-
 -- file main.yue
 -- import function is not available in browser, try it in a real environment
 --[[
@@ -311,9 +312,21 @@ import "utils" as {
 </pre>
 </YueDisplay>
 
+
 ## Operator
 
-All of Lua’s binary and unary operators are available. Additionally **!=** is as an alias for **~=**. And Yuescipt offers some special operator to write more expressive codes.
+All of Lua's binary and unary operators are available. Additionally **!=** is as an alias for **~=**, and either **\\** or **::** can be used to write a chaining function call like `tb\func!` or `tb::func!`. And Yuescipt offers some other special operators to write more expressive codes.
+
+```moonscript
+tb\func! if tb ~= nil
+tb::func! if tb != nil
+```
+<YueDisplay>
+<pre>
+tb\func! if tb ~= nil
+tb::func! if tb != nil
+</pre>
+</YueDisplay>
 
 ### Metatable
 
@@ -373,7 +386,6 @@ print tb.item
 tb = ["value"]#: 123
 tb.index# = tb.#
 print tb.value
-
 tb.# = __index: {item: "hello"}
 print tb.item
 </pre>
@@ -460,6 +472,27 @@ readFile "example.txt"
 </pre>
 </YueDisplay>
 
+### Nil Coalescing
+
+The nil-coalescing operator **??** returns the value of its left-hand operand if it isn't **nil**; otherwise, it evaluates the right-hand operand and returns its result. The **??** operator doesn't evaluate its right-hand operand if the left-hand operand evaluates to non-nil.
+```moonscript
+local a, b, c, d
+a = b ?? c ?? d
+func a ?? {}
+
+a ??= false
+```
+<YueDisplay>
+<pre>
+local a, b, c, d
+a = b ?? c ?? d
+func a ?? {}
+
+a ??= false
+</pre>
+</YueDisplay>
+
+
 ## Module
 
 ### Import
@@ -593,10 +626,33 @@ export default ->
 </pre>
 </YueDisplay>
 
+
 ## Whitespace
 
 Yuescript is a whitespace significant language. You have to write some code block in the same indent with space **' '** or tab **'\t'** like function body, value list and some control blocks. And expressions containing different whitespaces might mean different things. Tab is treated like 4 space, but it's better not mix the use of spaces and tabs.
 
+### Multiline Chaining
+
+You can write multi-line chaining function calls with a same indent.
+```moonscript
+Rx.Observable
+  .fromRange 1, 8
+  \filter (x)-> x % 2 == 0
+  \concat Rx.Observable.of 'who do we appreciate'
+  \map (value)-> value .. '!'
+  \subscribe print
+```
+<YueDisplay>
+<pre>
+Rx.Observable
+  .fromRange 1, 8
+  \filter (x)-> x % 2 == 0
+  \concat Rx.Observable.of 'who do we appreciate'
+  \map (value)-> value .. '!'
+  \subscribe print
+</pre>
+</YueDisplay>
+
 ## Assignment
 
 The variable is dynamic typed and is defined as local by default. But you can change the scope of declaration by **local** and **global** statement.
@@ -617,6 +673,7 @@ s ..= "world"
 arg or= "default value"
 ```
 <YueDisplay>
+
 <pre>
 hello = "world"
 a, b, c = 1, 2, 3
@@ -649,6 +706,7 @@ do
   B = 2
 ```
 <YueDisplay>
+
 <pre>
 do
   local *
@@ -2458,6 +2516,18 @@ This is effectively the same as import, but we can rename fields we want to extr
 </pre>
 </YueDisplay>
 
+You can write default values while doing destructuring like:
+
+```moonscript
+{:name = "nameless", :job = "jobless"} = person
+```
+<YueDisplay>
+<pre>
+{:name = "nameless", :job = "jobless"} = person
+</pre>
+</YueDisplay>
+
+
 ### Destructuring In Other Places
 
 Destructuring can also show up in places where an assignment implicitly takes place. An example of this is a for loop:
-- 
cgit v1.2.3-55-g6feb