diff options
author | Li Jin <dragon-fly@qq.com> | 2022-02-25 16:57:51 +0800 |
---|---|---|
committer | Li Jin <dragon-fly@qq.com> | 2022-02-25 16:57:51 +0800 |
commit | 6c78271c841baf43365cc7924c0ca2da867f9e79 (patch) | |
tree | 5ba55c74fdeb31f0b7e20ae5a7372b7b208cb9b2 /doc/docs | |
parent | 65f4358a156ace74119c0c029bf24cd03ecc5e75 (diff) | |
download | yuescript-6c78271c841baf43365cc7924c0ca2da867f9e79.tar.gz yuescript-6c78271c841baf43365cc7924c0ca2da867f9e79.tar.bz2 yuescript-6c78271c841baf43365cc7924c0ca2da867f9e79.zip |
update doc.
Diffstat (limited to 'doc/docs')
-rwxr-xr-x | doc/docs/doc/README.md | 98 |
1 files changed, 83 insertions, 15 deletions
diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md index 98a121b..be83be3 100755 --- a/doc/docs/doc/README.md +++ b/doc/docs/doc/README.md | |||
@@ -81,45 +81,64 @@ export yuescript = "ζδΉθζ¬" | |||
81 | 81 | ||
82 | * **Lua Module** | 82 | * **Lua Module** |
83 | 83 | ||
84 |   Install [luarocks](https://luarocks.org), a package manager for Lua modules. Then install it as a Lua module and executable with: | 84 |  Install [luarocks](https://luarocks.org), a package manager for Lua modules. Then install it as a Lua module and executable with: |
85 | 85 | ||
86 | ``` | 86 | ``` |
87 | > luarocks install yuescript | 87 | > luarocks install yuescript |
88 | ``` | 88 | ``` |
89 | 89 | ||
90 |   Or you can build `yue.so` file with: | 90 |  Or you can build `yue.so` file with: |
91 | 91 | ||
92 | ``` | 92 | ``` |
93 | > make shared LUAI=/usr/local/include/lua LUAL=/usr/local/lib/lua | 93 | > make shared LUAI=/usr/local/include/lua LUAL=/usr/local/lib/lua |
94 | ``` | 94 | ``` |
95 | 95 | ||
96 |   Then get the binary file from path **bin/shared/yue.so**. | 96 |  Then get the binary file from path **bin/shared/yue.so**. |
97 | 97 | ||
98 | * **Binary Tool** | 98 | * **Binary Tool** |
99 | 99 | ||
100 |   Clone this repo, then build and install executable with: | 100 |  Clone this repo, then build and install executable with: |
101 | ``` | 101 | ``` |
102 | > make install | 102 | > make install |
103 | ``` | 103 | ``` |
104 | 104 | ||
105 |   Build Yuescript tool without macro feature: | 105 |  Build Yuescript tool without macro feature: |
106 | ``` | 106 | ``` |
107 | > make install NO_MACRO=true | 107 | > make install NO_MACRO=true |
108 | ``` | 108 | ``` |
109 | 109 | ||
110 |   Build Yuescript tool without built-in Lua binary: | 110 |  Build Yuescript tool without built-in Lua binary: |
111 | ``` | 111 | ``` |
112 | > make install NO_LUA=true | 112 | > make install NO_LUA=true |
113 | ``` | 113 | ``` |
114 | 114 | ||
115 | ## Usage | 115 | ## Usage |
116 | 116 | ||
117 |   Require the Yuescript module in Lua: | 117 | ### Lua Module |
118 | |||
119 |  Use Yuescript module in Lua: | ||
120 | |||
121 | * **Case 1** | ||
122 | Require "your_yuescript_entry.yue" in Lua. | ||
118 | ```Lua | 123 | ```Lua |
119 | -- require `main.yue` in Lua | 124 | require("yue")("your_yuescript_entry") |
120 | require("yue")("main") | 125 | ``` |
126 |  And this code still works when you compile "your_yuescript_entry.yue" to "your_yuescript_entry.lua" in the same path. In the rest Yuescript files just use the normal **require** or **import**. The code line numbers in error messages will also be handled correctly. | ||
121 | 127 | ||
122 | -- use the Yuescript compiler in Lua | 128 | * **Case 2** |
129 | Require Yuescript module and rewite message by hand. | ||
130 | ```lua | ||
131 | local yue = require("yue") | ||
132 | local success, result = xpcall(function() | ||
133 | yue.require("yuescript_module_name") | ||
134 | end, function(err) | ||
135 | return yue.traceback(err) | ||
136 | end) | ||
137 | ``` | ||
138 | |||
139 | * **Case 3** | ||
140 | Use the Yuescript compiler function in Lua. | ||
141 | ```lua | ||
123 | local yue = require("yue") | 142 | local yue = require("yue") |
124 | local codes, err, globals = yue.to_lua([[ | 143 | local codes, err, globals = yue.to_lua([[ |
125 | f = -> | 144 | f = -> |
@@ -131,7 +150,10 @@ f! | |||
131 | lint_global = true | 150 | lint_global = true |
132 | }) | 151 | }) |
133 | ``` | 152 | ``` |
134 |   Use Yuescript tool with: | 153 | |
154 | ### Yuescript Tool | ||
155 | |||
156 |  Use Yuescript tool with: | ||
135 | ``` | 157 | ``` |
136 | > yue -h | 158 | > yue -h |
137 | Usage: yue [options|files|directories] ... | 159 | Usage: yue [options|files|directories] ... |
@@ -160,7 +182,6 @@ Usage: yue [options|files|directories] ... | |||
160 |   Execute raw codes: **yue -e 'print 123'** | 182 |   Execute raw codes: **yue -e 'print 123'** |
161 |   Execute a Yuescript file: **yue -e main.yue** | 183 |   Execute a Yuescript file: **yue -e main.yue** |
162 | 184 | ||
163 | |||
164 | ## Macro | 185 | ## Macro |
165 | 186 | ||
166 | ### Common Usage | 187 | ### Common Usage |
@@ -226,7 +247,7 @@ if $and f1!, f2!, f3! | |||
226 | </pre> | 247 | </pre> |
227 | </YueDisplay> | 248 | </YueDisplay> |
228 | 249 | ||
229 | ### Insert Raw Codes | 250 | ### Insert Raw Codes |
230 | 251 | ||
231 | A macro function can either return a Yuescript string or a config table containing Lua codes. | 252 | A macro function can either return a Yuescript string or a config table containing Lua codes. |
232 | ```moonscript | 253 | ```moonscript |
@@ -324,7 +345,6 @@ import "utils" as { | |||
324 | </pre> | 345 | </pre> |
325 | </YueDisplay> | 346 | </YueDisplay> |
326 | 347 | ||
327 | |||
328 | ## Operator | 348 | ## Operator |
329 | 349 | ||
330 | 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. | 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. |
@@ -572,7 +592,6 @@ tb = | |||
572 | </pre> | 592 | </pre> |
573 | </YueDisplay> | 593 | </YueDisplay> |
574 | 594 | ||
575 | |||
576 | ## Module | 595 | ## Module |
577 | 596 | ||
578 | ### Import | 597 | ### Import |
@@ -706,6 +725,54 @@ export default -> | |||
706 | </pre> | 725 | </pre> |
707 | </YueDisplay> | 726 | </YueDisplay> |
708 | 727 | ||
728 | ## Try | ||
729 | |||
730 | The syntax for Lua error handling in a common form. | ||
731 | |||
732 | ```moonscript | ||
733 | try | ||
734 | func 1, 2, 3 | ||
735 | catch err | ||
736 | print yue.traceback err | ||
737 | |||
738 | success, result = try | ||
739 | func 1, 2, 3 | ||
740 | catch err | ||
741 | yue.traceback err | ||
742 | |||
743 | try func 1, 2, 3 | ||
744 | catch err | ||
745 | print yue.traceback err | ||
746 | |||
747 | success, result = try func 1, 2, 3 | ||
748 | |||
749 | try | ||
750 | print "trying" | ||
751 | func 1, 2, 3 | ||
752 | ``` | ||
753 | <YueDisplay> | ||
754 | <pre> | ||
755 | try | ||
756 | func 1, 2, 3 | ||
757 | catch err | ||
758 | print yue.traceback err | ||
759 | |||
760 | success, result = try | ||
761 | func 1, 2, 3 | ||
762 | catch err | ||
763 | yue.traceback err | ||
764 | |||
765 | try func 1, 2, 3 | ||
766 | catch err | ||
767 | print yue.traceback err | ||
768 | |||
769 | success, result = try func 1, 2, 3 | ||
770 | |||
771 | try | ||
772 | print "trying" | ||
773 | func 1, 2, 3 | ||
774 | </pre> | ||
775 | </YueDisplay> | ||
709 | 776 | ||
710 | ## Whitespace | 777 | ## Whitespace |
711 | 778 | ||
@@ -836,6 +903,7 @@ do | |||
836 | </YueDisplay> | 903 | </YueDisplay> |
837 | 904 | ||
838 | ## Comment | 905 | ## Comment |
906 | |||
839 | ```moonscript | 907 | ```moonscript |
840 | -- I am a comment | 908 | -- I am a comment |
841 | 909 | ||