fix table matching issue and update doc.

author: Li Jin <dragon-fly@qq.com> 2022-07-14 02:48:49 +0800
committer: Li Jin <dragon-fly@qq.com> 2022-07-14 02:48:49 +0800
commit: 3159a45de9e691ad758dcbc933446f61b7ae1940 (patch)
tree: b695f8356986accc84c82ece09eb427a2b1db230 /doc/docs
parent: a1d341085eed96d567329a30f2cf57c95fe6f071 (diff)
download: yuescript-3159a45de9e691ad758dcbc933446f61b7ae1940.tar.gz
yuescript-3159a45de9e691ad758dcbc933446f61b7ae1940.tar.bz2
yuescript-3159a45de9e691ad758dcbc933446f61b7ae1940.zip
1 files changed, 114 insertions, 5 deletions
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.
author	Li Jin <dragon-fly@qq.com>	2022-07-14 02:48:49 +0800
committer	Li Jin <dragon-fly@qq.com>	2022-07-14 02:48:49 +0800
commit	3159a45de9e691ad758dcbc933446f61b7ae1940 (patch)
tree	b695f8356986accc84c82ece09eb427a2b1db230 /doc/docs
parent	a1d341085eed96d567329a30f2cf57c95fe6f071 (diff)
download	yuescript-3159a45de9e691ad758dcbc933446f61b7ae1940.tar.gz yuescript-3159a45de9e691ad758dcbc933446f61b7ae1940.tar.bz2 yuescript-3159a45de9e691ad758dcbc933446f61b7ae1940.zip

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
311		311
312	### Export Macro	312	### Export Macro
313		313
314	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.	314	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.
315	```moonscript	315	```moonscript
316	-- file: utils.yue	316	-- file: utils.yue
317	export macro map = (items, action)-> "[#{action} for _ in *#{items}]"	317	export macro map = (items, action)-> "[#{action} for _ in *#{items}]"
@@ -345,6 +345,20 @@ import "utils" as {
345	</pre>	345	</pre>
346	</YueDisplay>	346	</YueDisplay>
347		347
		348	### Builtin Macro
		349
		350	There are some builtin macros but you can override them by declaring macros with the same names.
		351	```moonscript
		352	print $FILE -- get string of current module name
		353	print $LINE -- get number 2
		354	```
		355	<YueDisplay>
		356	<pre>
		357	print $FILE -- get string of current module name
		358	print $LINE -- get number 2
		359	</pre>
		360	</YueDisplay>
		361
348	## Operator	362	## Operator
349		363
350	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.	364	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."
1237	</pre>	1251	</pre>
1238	</YueDisplay>	1252	</YueDisplay>
1239		1253
1240	::: warning NOTICE
1241	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.
1242	:::
1243
1244	## Literals	1254	## Literals
1245		1255
1246	All of the primitive literals in Lua can be used. This applies to numbers, strings, booleans, and nil.	1256	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)
2295		2305
2296	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.	2306	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.
2297		2307
		2308	### Table Matching
		2309
		2310	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.
		2311
		2312	```moonscript
		2313	items =
		2314	* x: 100
		2315	y: 200
		2316	* width: 300
		2317	height: 400
		2318
		2319	for item in *items
		2320	switch item
		2321	when :x, :y
		2322	print "Vec2 #{x}, #{y}"
		2323	when :width, :height
		2324	print "size #{width}, #{height}"
		2325	```
		2326	<YueDisplay>
		2327	<pre>
		2328	items =
		2329	* x: 100
		2330	y: 200
		2331	* width: 300
		2332	height: 400
		2333
		2334	for item in *items
		2335	switch item
		2336	when :x, :y
		2337	print "Vec2 #{x}, #{y}"
		2338	when :width, :height
		2339	print "size #{width}, #{height}"
		2340	</pre>
		2341	</YueDisplay>
		2342
		2343	You can use default values to optionally destructure the table for some fields.
		2344
		2345	```moonscript
		2346	item = x: 100
		2347
		2348	switch item
		2349	when {:x, :y = 200}
		2350	print "Vec2 #{x}, #{y}" -- table matching will pass
		2351	```
		2352	<YueDisplay>
		2353	<pre>
		2354	item = x: 100
		2355
		2356	switch item
		2357	when {:x, :y = 200}
		2358	print "Vec2 #{x}, #{y}" -- table matching will pass
		2359	</pre>
		2360	</YueDisplay>
		2361
2298	## Object Oriented Programming	2362	## Object Oriented Programming
2299		2363
2300	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.	2364	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
2718	</pre>	2782	</pre>
2719	</YueDisplay>	2783	</YueDisplay>
2720		2784
		2785	### Class Mixing
		2786
		2787	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.
		2788
		2789	```moonscript
		2790	MyIndex = __index: var: 1
		2791
		2792	class X using MyIndex
		2793	func: =>
		2794	print 123
		2795
		2796	x = X!
		2797	print x.var
		2798
		2799	class Y using X
		2800
		2801	y = Y!
		2802	y\func!
		2803
		2804	assert y.__class.__parent ~= X -- X is not parent of Y
		2805	```
		2806	<YueDisplay>
		2807	<pre>
		2808	MyIndex = __index: var: 1
		2809
		2810	class X using MyIndex
		2811	func: =>
		2812	print 123
		2813
		2814	x = X!
		2815	print x.var
		2816
		2817	class Y using X
		2818
		2819	y = Y!
		2820	y\func!
		2821
		2822	assert y.__class.__parent ~= X -- X is not parent of Y
		2823	</pre>
		2824	</YueDisplay>
		2825
		2826	::: warning NOTICE
		2827	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.
		2828	:::
		2829
2721	## With Statement	2830	## With Statement
2722		2831
2723	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.	2832	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.