From 3159a45de9e691ad758dcbc933446f61b7ae1940 Mon Sep 17 00:00:00 2001
From: Li Jin <dragon-fly@qq.com>
Date: Thu, 14 Jul 2022 02:48:49 +0800
Subject: fix table matching issue and update doc.

---
 doc/docs/doc/README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 114 insertions(+), 5 deletions(-)

(limited to 'doc')

diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md
index 5d856bb..ef00c23 100755
--- a/doc/docs/doc/README.md
+++ b/doc/docs/doc/README.md
@@ -311,7 +311,7 @@ end
 
 ### Export Macro
 
-Macro functions can be exported from a module and get imported in another module. It is recommanded to export macro functions in a single file to speed up compilation.
+Macro functions can be exported from a module and get imported in another module. You have to put export macro functions in a single file to be used, and only macro definition, macro importing and macro expansion in place can be put into the macro exporting module.
 ```moonscript
 -- file: utils.yue
 export macro map = (items, action)-> "[#{action} for _ in *#{items}]"
@@ -345,6 +345,20 @@ import "utils" as {
 </pre>
 </YueDisplay>
 
+### Builtin Macro
+
+There are some builtin macros but you can override them by declaring macros with the same names.
+```moonscript
+print $FILE -- get string of current module name
+print $LINE -- get number 2
+```
+<YueDisplay>
+<pre>
+print $FILE -- get string of current module name
+print $LINE -- get number 2
+</pre>
+</YueDisplay>
+
 ## Operator
 
 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.
@@ -1237,10 +1251,6 @@ close _ = close#: -> print "Out of scope."
 </pre>
 </YueDisplay>
 
-::: warning NOTICE
-The rest of the document is describing mostly the same syntax taken from Moonscript. So you may as well refer to the [Moonscript Reference](http://moonscript.org/reference) to get the same explanation.
-:::
-
 ## Literals
 
 All of the primitive literals in Lua can be used. This applies to numbers, strings, booleans, and **nil**.
@@ -2295,6 +2305,60 @@ msg = switch math.random(1, 5)
 
 It is worth noting the order of the case comparison expression. The case’s expression is on the left hand side. This can be useful if the case’s expression wants to overwrite how the comparison is done by defining an eq metamethod.
 
+### Table Matching
+
+You can do table matching in a switch when clause, if the table can be destructured by a specific structure and get non-nil values.
+
+```moonscript
+items =
+  * x: 100
+    y: 200
+  * width: 300
+    height: 400
+
+for item in *items
+  switch item
+    when :x, :y
+      print "Vec2 #{x}, #{y}"
+    when :width, :height
+      print "size #{width}, #{height}"
+```
+<YueDisplay>
+<pre>
+items =
+  * x: 100
+    y: 200
+  * width: 300
+    height: 400
+
+for item in *items
+  switch item
+    when :x, :y
+      print "Vec2 #{x}, #{y}"
+    when :width, :height
+      print "size #{width}, #{height}"
+</pre>
+</YueDisplay>
+
+You can use default values to optionally destructure the table for some fields.
+
+```moonscript
+item = x: 100
+
+switch item
+  when {:x, :y = 200}
+    print "Vec2 #{x}, #{y}" -- table matching will pass
+```
+<YueDisplay>
+<pre>
+item = x: 100
+
+switch item
+  when {:x, :y = 200}
+    print "Vec2 #{x}, #{y}" -- table matching will pass
+</pre>
+</YueDisplay>
+
 ## Object Oriented Programming
 
 In these examples, the generated Lua code may appear overwhelming. It is best to focus on the meaning of the Yuescript code at first, then look into the Lua code if you wish to know the implementation details.
@@ -2718,6 +2782,51 @@ x = class
 </pre>
 </YueDisplay>
 
+### Class Mixing
+
+You can do mixing with keyword `using` to copy functions from either a plain table or a predefined class object into your new class. When doing mixing with a plain table, you can override the class indexing function (metamethod `__index`) to your customized implementation. When doing mixing with an existing class object, the class object's metamethods won't be copied.
+
+```moonscript
+MyIndex = __index: var: 1
+
+class X using MyIndex
+  func: =>
+    print 123
+
+x = X!
+print x.var
+
+class Y using X
+
+y = Y!
+y\func!
+
+assert y.__class.__parent ~= X -- X is not parent of Y
+```
+<YueDisplay>
+<pre>
+MyIndex = __index: var: 1
+
+class X using MyIndex
+  func: =>
+    print 123
+
+x = X!
+print x.var
+
+class Y using X
+
+y = Y!
+y\func!
+
+assert y.__class.__parent ~= X -- X is not parent of Y
+</pre>
+</YueDisplay>
+
+::: warning NOTICE
+The rest of the document is describing mostly the same syntax taken from Moonscript. So you may as well refer to the [Moonscript Reference](http://moonscript.org/reference) to get the same explanation.
+:::
+
 ## With Statement
 
 A common pattern involving the creation of an object is calling a series of functions and setting a series of properties immediately after creating it.
-- 
cgit v1.2.3-55-g6feb