diff options
Diffstat (limited to 'doc/docs/doc/README.md')
-rwxr-xr-x | doc/docs/doc/README.md | 88 |
1 files changed, 44 insertions, 44 deletions
diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md index 2835ffb..814593b 100755 --- a/doc/docs/doc/README.md +++ b/doc/docs/doc/README.md | |||
@@ -3,17 +3,17 @@ sidebar: auto | |||
3 | title: Reference | 3 | title: Reference |
4 | --- | 4 | --- |
5 | 5 | ||
6 | # Yuescript | 6 | # YueScript |
7 | 7 | ||
8 | <img src="/image/yuescript.svg" width="300px" height="300px" alt="logo"/> | 8 | <img src="/image/yuescript.svg" width="300px" height="300px" alt="logo"/> |
9 | 9 | ||
10 | ## Introduction | 10 | ## Introduction |
11 | 11 | ||
12 | Yuescript is a dynamic language that compiles to Lua. And it's a [Moonscript](https://github.com/leafo/moonscript) dialect. The codes written in Yuescript are expressive and extremely concise. And it is suitable for writing some changing application logic with more maintainable codes and runs in a Lua embeded environment such as games or website servers. | 12 | YueScript is a dynamic language that compiles to Lua. And it's a [MoonScript](https://github.com/leafo/moonscript) dialect. The codes written in YueScript are expressive and extremely concise. And it is suitable for writing some changing application logic with more maintainable codes and runs in a Lua embeded environment such as games or website servers. |
13 | 13 | ||
14 | Yue (月) is the name of moon in Chinese and it's pronounced as [jyɛ]. | 14 | Yue (月) is the name of moon in Chinese and it's pronounced as [jyɛ]. |
15 | 15 | ||
16 | ### An Overview of Yuescript | 16 | ### An Overview of YueScript |
17 | ```moonscript | 17 | ```moonscript |
18 | -- import syntax | 18 | -- import syntax |
19 | import "yue" as :p, :to_lua | 19 | import "yue" as :p, :to_lua |
@@ -104,12 +104,12 @@ export 🌛 = "月之脚本" | |||
104 | > make install | 104 | > make install |
105 | ``` | 105 | ``` |
106 | 106 | ||
107 |  Build Yuescript tool without macro feature: | 107 |  Build YueScript tool without macro feature: |
108 | ``` | 108 | ``` |
109 | > make install NO_MACRO=true | 109 | > make install NO_MACRO=true |
110 | ``` | 110 | ``` |
111 | 111 | ||
112 |  Build Yuescript tool without built-in Lua binary: | 112 |  Build YueScript tool without built-in Lua binary: |
113 | ``` | 113 | ``` |
114 | > make install NO_LUA=true | 114 | > make install NO_LUA=true |
115 | ``` | 115 | ``` |
@@ -118,17 +118,17 @@ export 🌛 = "月之脚本" | |||
118 | 118 | ||
119 | ### Lua Module | 119 | ### Lua Module |
120 | 120 | ||
121 |  Use Yuescript module in Lua: | 121 |  Use YueScript module in Lua: |
122 | 122 | ||
123 | * **Case 1** | 123 | * **Case 1** |
124 | Require "your_yuescript_entry.yue" in Lua. | 124 | Require "your_yuescript_entry.yue" in Lua. |
125 | ```Lua | 125 | ```Lua |
126 | require("yue")("your_yuescript_entry") | 126 | require("yue")("your_yuescript_entry") |
127 | ``` | 127 | ``` |
128 |  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. | 128 |  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. |
129 | 129 | ||
130 | * **Case 2** | 130 | * **Case 2** |
131 | Require Yuescript module and rewite message by hand. | 131 | Require YueScript module and rewite message by hand. |
132 | ```lua | 132 | ```lua |
133 | local yue = require("yue") | 133 | local yue = require("yue") |
134 | local success, result = xpcall(function() | 134 | local success, result = xpcall(function() |
@@ -139,7 +139,7 @@ end) | |||
139 | ``` | 139 | ``` |
140 | 140 | ||
141 | * **Case 3** | 141 | * **Case 3** |
142 | Use the Yuescript compiler function in Lua. | 142 | Use the YueScript compiler function in Lua. |
143 | ```lua | 143 | ```lua |
144 | local yue = require("yue") | 144 | local yue = require("yue") |
145 | local codes, err, globals = yue.to_lua([[ | 145 | local codes, err, globals = yue.to_lua([[ |
@@ -158,9 +158,9 @@ f! | |||
158 | }) | 158 | }) |
159 | ``` | 159 | ``` |
160 | 160 | ||
161 | ### Yuescript Tool | 161 | ### YueScript Tool |
162 | 162 | ||
163 |  Use Yuescript tool with: | 163 |  Use YueScript tool with: |
164 | ``` | 164 | ``` |
165 | > yue -h | 165 | > yue -h |
166 | Usage: yue [options|files|directories] ... | 166 | Usage: yue [options|files|directories] ... |
@@ -190,12 +190,12 @@ Usage: yue [options|files|directories] ... | |||
190 | in a single line to start/stop multi-line mode | 190 | in a single line to start/stop multi-line mode |
191 | ``` | 191 | ``` |
192 |   Use cases: | 192 |   Use cases: |
193 |   Recursively compile every Yuescript file with extension **.yue** under current path: **yue .** | 193 |   Recursively compile every YueScript file with extension **.yue** under current path: **yue .** |
194 |   Compile and save results to a target path: **yue -t /target/path/ .** | 194 |   Compile and save results to a target path: **yue -t /target/path/ .** |
195 |   Compile and reserve debug info: **yue -l .** | 195 |   Compile and reserve debug info: **yue -l .** |
196 |   Compile and generate minified codes: **yue -m .** | 196 |   Compile and generate minified codes: **yue -m .** |
197 |   Execute raw codes: **yue -e 'print 123'** | 197 |   Execute raw codes: **yue -e 'print 123'** |
198 |   Execute a Yuescript file: **yue -e main.yue** | 198 |   Execute a YueScript file: **yue -e main.yue** |
199 | 199 | ||
200 | ## Macro | 200 | ## Macro |
201 | 201 | ||
@@ -264,13 +264,13 @@ if $and f1!, f2!, f3! | |||
264 | 264 | ||
265 | ### Insert Raw Codes | 265 | ### Insert Raw Codes |
266 | 266 | ||
267 | A macro function can either return a Yuescript string or a config table containing Lua codes. | 267 | A macro function can either return a YueScript string or a config table containing Lua codes. |
268 | ```moonscript | 268 | ```moonscript |
269 | macro yueFunc = (var)-> "local #{var} = ->" | 269 | macro yueFunc = (var)-> "local #{var} = ->" |
270 | $yueFunc funcA | 270 | $yueFunc funcA |
271 | funcA = -> "assign the Yue defined variable" | 271 | funcA = -> "assign the Yue defined variable" |
272 | 272 | ||
273 | -- take care and let Yuescript know the | 273 | -- take care and let YueScript know the |
274 | -- local variables you declared in Lua code | 274 | -- local variables you declared in Lua code |
275 | macro luaFunc = (var)-> { | 275 | macro luaFunc = (var)-> { |
276 | code: "local function #{var}() end" | 276 | code: "local function #{var}() end" |
@@ -299,7 +299,7 @@ macro yueFunc = (var)-> "local #{var} = ->" | |||
299 | $yueFunc funcA | 299 | $yueFunc funcA |
300 | funcA = -> "assign the Yue defined variable" | 300 | funcA = -> "assign the Yue defined variable" |
301 | 301 | ||
302 | -- take care and let Yuescript know the | 302 | -- take care and let YueScript know the |
303 | -- local variables you declared in Lua codes | 303 | -- local variables you declared in Lua codes |
304 | macro luaFunc = (var)-> { | 304 | macro luaFunc = (var)-> { |
305 | code: "local function #{var}() end" | 305 | code: "local function #{var}() end" |
@@ -376,7 +376,7 @@ print $LINE -- get number 2 | |||
376 | 376 | ||
377 | ### Generating Macros with Macros | 377 | ### Generating Macros with Macros |
378 | 378 | ||
379 | In Yuescript, macro functions allow you to generate code at compile time. By nesting macro functions, you can create more complex generation patterns. This feature enables you to define a macro function that generates another macro function, allowing for more dynamic code generation. | 379 | In YueScript, macro functions allow you to generate code at compile time. By nesting macro functions, you can create more complex generation patterns. This feature enables you to define a macro function that generates another macro function, allowing for more dynamic code generation. |
380 | 380 | ||
381 | ```moonscript | 381 | ```moonscript |
382 | macro Enum = (...) -> | 382 | macro Enum = (...) -> |
@@ -1353,7 +1353,7 @@ print ok, count, first | |||
1353 | 1353 | ||
1354 | ## Whitespace | 1354 | ## Whitespace |
1355 | 1355 | ||
1356 | 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. | 1356 | 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. |
1357 | 1357 | ||
1358 | ### Multiline Chaining | 1358 | ### Multiline Chaining |
1359 | 1359 | ||
@@ -2778,7 +2778,7 @@ switch item | |||
2778 | 2778 | ||
2779 | ## Object Oriented Programming | 2779 | ## Object Oriented Programming |
2780 | 2780 | ||
2781 | 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. | 2781 | 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. |
2782 | 2782 | ||
2783 | A simple class: | 2783 | A simple class: |
2784 | 2784 | ||
@@ -3409,7 +3409,7 @@ print var -- nil here | |||
3409 | </pre> | 3409 | </pre> |
3410 | </YueDisplay> | 3410 | </YueDisplay> |
3411 | 3411 | ||
3412 | Yuescript’s **do** can also be used an expression . Allowing you to combine multiple lines into one. The result of the do expression is the last statement in its body. | 3412 | YueScript’s **do** can also be used an expression . Allowing you to combine multiple lines into one. The result of the do expression is the last statement in its body. |
3413 | 3413 | ||
3414 | ```moonscript | 3414 | ```moonscript |
3415 | counter = do | 3415 | counter = do |
@@ -3591,7 +3591,7 @@ print i, k -- these have been updated | |||
3591 | </pre> | 3591 | </pre> |
3592 | </YueDisplay> | 3592 | </YueDisplay> |
3593 | 3593 | ||
3594 | ## The Yuescript Library | 3594 | ## The YueScript Library |
3595 | 3595 | ||
3596 | Access it by `require("yue")`. | 3596 | Access it by `require("yue")`. |
3597 | 3597 | ||
@@ -3599,7 +3599,7 @@ Access it by `require("yue")`. | |||
3599 | 3599 | ||
3600 | **Description:** | 3600 | **Description:** |
3601 | 3601 | ||
3602 | The Yuescript language library. | 3602 | The YueScript language library. |
3603 | 3603 | ||
3604 | #### version | 3604 | #### version |
3605 | 3605 | ||
@@ -3607,7 +3607,7 @@ The Yuescript language library. | |||
3607 | 3607 | ||
3608 | **Description:** | 3608 | **Description:** |
3609 | 3609 | ||
3610 | The Yuescript version. | 3610 | The YueScript version. |
3611 | 3611 | ||
3612 | **Signature:** | 3612 | **Signature:** |
3613 | ```lua | 3613 | ```lua |
@@ -3646,7 +3646,7 @@ yue_compiled: {string: string} | |||
3646 | 3646 | ||
3647 | **Description:** | 3647 | **Description:** |
3648 | 3648 | ||
3649 | The Yuescript compiling function. It compiles the Yuescript code to Lua code. | 3649 | The YueScript compiling function. It compiles the YueScript code to Lua code. |
3650 | 3650 | ||
3651 | **Signature:** | 3651 | **Signature:** |
3652 | ```lua | 3652 | ```lua |
@@ -3660,7 +3660,7 @@ to_lua: function(code: string, config?: Config): | |||
3660 | 3660 | ||
3661 | | Parameter | Type | Description | | 3661 | | Parameter | Type | Description | |
3662 | | --- | --- | --- | | 3662 | | --- | --- | --- | |
3663 | | code | string | The Yuescript code. | | 3663 | | code | string | The YueScript code. | |
3664 | | config | Config | [Optional] The compiler options. | | 3664 | | config | Config | [Optional] The compiler options. | |
3665 | 3665 | ||
3666 | **Returns:** | 3666 | **Returns:** |
@@ -3727,7 +3727,7 @@ read_file: function(filename: string): string | |||
3727 | 3727 | ||
3728 | **Description:** | 3728 | **Description:** |
3729 | 3729 | ||
3730 | Insert the Yuescript loader to the package loaders (searchers). | 3730 | Insert the YueScript loader to the package loaders (searchers). |
3731 | 3731 | ||
3732 | **Signature:** | 3732 | **Signature:** |
3733 | ```lua | 3733 | ```lua |
@@ -3752,7 +3752,7 @@ insert_loader: function(pos?: integer): boolean | |||
3752 | 3752 | ||
3753 | **Description:** | 3753 | **Description:** |
3754 | 3754 | ||
3755 | Remove the Yuescript loader from the package loaders (searchers). | 3755 | Remove the YueScript loader from the package loaders (searchers). |
3756 | 3756 | ||
3757 | **Signature:** | 3757 | **Signature:** |
3758 | ```lua | 3758 | ```lua |
@@ -3771,7 +3771,7 @@ remove_loader: function(): boolean | |||
3771 | 3771 | ||
3772 | **Description:** | 3772 | **Description:** |
3773 | 3773 | ||
3774 | Loads Yuescript code from a string into a function. | 3774 | Loads YueScript code from a string into a function. |
3775 | 3775 | ||
3776 | **Signature:** | 3776 | **Signature:** |
3777 | ```lua | 3777 | ```lua |
@@ -3784,7 +3784,7 @@ loadstring: function(input: string, chunkname: string, env: table, config?: Conf | |||
3784 | 3784 | ||
3785 | | Parameter | Type | Description | | 3785 | | Parameter | Type | Description | |
3786 | | --- | --- | --- | | 3786 | | --- | --- | --- | |
3787 | | input | string | The Yuescript code. | | 3787 | | input | string | The YueScript code. | |
3788 | | chunkname | string | The name of the code chunk. | | 3788 | | chunkname | string | The name of the code chunk. | |
3789 | | env | table | The environment table. | | 3789 | | env | table | The environment table. | |
3790 | | config | Config | [Optional] The compiler options. | | 3790 | | config | Config | [Optional] The compiler options. | |
@@ -3802,7 +3802,7 @@ loadstring: function(input: string, chunkname: string, env: table, config?: Conf | |||
3802 | 3802 | ||
3803 | **Description:** | 3803 | **Description:** |
3804 | 3804 | ||
3805 | Loads Yuescript code from a string into a function. | 3805 | Loads YueScript code from a string into a function. |
3806 | 3806 | ||
3807 | **Signature:** | 3807 | **Signature:** |
3808 | ```lua | 3808 | ```lua |
@@ -3815,7 +3815,7 @@ loadstring: function(input: string, chunkname: string, config?: Config): | |||
3815 | 3815 | ||
3816 | | Parameter | Type | Description | | 3816 | | Parameter | Type | Description | |
3817 | | --- | --- | --- | | 3817 | | --- | --- | --- | |
3818 | | input | string | The Yuescript code. | | 3818 | | input | string | The YueScript code. | |
3819 | | chunkname | string | The name of the code chunk. | | 3819 | | chunkname | string | The name of the code chunk. | |
3820 | | config | Config | [Optional] The compiler options. | | 3820 | | config | Config | [Optional] The compiler options. | |
3821 | 3821 | ||
@@ -3832,7 +3832,7 @@ loadstring: function(input: string, chunkname: string, config?: Config): | |||
3832 | 3832 | ||
3833 | **Description:** | 3833 | **Description:** |
3834 | 3834 | ||
3835 | Loads Yuescript code from a string into a function. | 3835 | Loads YueScript code from a string into a function. |
3836 | 3836 | ||
3837 | **Signature:** | 3837 | **Signature:** |
3838 | ```lua | 3838 | ```lua |
@@ -3845,7 +3845,7 @@ loadstring: function(input: string, config?: Config): | |||
3845 | 3845 | ||
3846 | | Parameter | Type | Description | | 3846 | | Parameter | Type | Description | |
3847 | | --- | --- | --- | | 3847 | | --- | --- | --- | |
3848 | | input | string | The Yuescript code. | | 3848 | | input | string | The YueScript code. | |
3849 | | config | Config | [Optional] The compiler options. | | 3849 | | config | Config | [Optional] The compiler options. | |
3850 | 3850 | ||
3851 | **Returns:** | 3851 | **Returns:** |
@@ -3861,7 +3861,7 @@ loadstring: function(input: string, config?: Config): | |||
3861 | 3861 | ||
3862 | **Description:** | 3862 | **Description:** |
3863 | 3863 | ||
3864 | Loads Yuescript code from a file into a function. | 3864 | Loads YueScript code from a file into a function. |
3865 | 3865 | ||
3866 | **Signature:** | 3866 | **Signature:** |
3867 | ```lua | 3867 | ```lua |
@@ -3891,7 +3891,7 @@ loadfile: function(filename: string, env: table, config?: Config): | |||
3891 | 3891 | ||
3892 | **Description:** | 3892 | **Description:** |
3893 | 3893 | ||
3894 | Loads Yuescript code from a file into a function. | 3894 | Loads YueScript code from a file into a function. |
3895 | 3895 | ||
3896 | **Signature:** | 3896 | **Signature:** |
3897 | ```lua | 3897 | ```lua |
@@ -3920,7 +3920,7 @@ loadfile: function(filename: string, config?: Config): | |||
3920 | 3920 | ||
3921 | **Description:** | 3921 | **Description:** |
3922 | 3922 | ||
3923 | Loads Yuescript code from a file into a function and executes it. | 3923 | Loads YueScript code from a file into a function and executes it. |
3924 | 3924 | ||
3925 | **Signature:** | 3925 | **Signature:** |
3926 | ```lua | 3926 | ```lua |
@@ -3947,7 +3947,7 @@ dofile: function(filename: string, env: table, config?: Config): any... | |||
3947 | 3947 | ||
3948 | **Description:** | 3948 | **Description:** |
3949 | 3949 | ||
3950 | Loads Yuescript code from a file into a function and executes it. | 3950 | Loads YueScript code from a file into a function and executes it. |
3951 | 3951 | ||
3952 | **Signature:** | 3952 | **Signature:** |
3953 | ```lua | 3953 | ```lua |
@@ -3973,7 +3973,7 @@ dofile: function(filename: string, config?: Config): any... | |||
3973 | 3973 | ||
3974 | **Description:** | 3974 | **Description:** |
3975 | 3975 | ||
3976 | Resolves the Yuescript module name to the file path. | 3976 | Resolves the YueScript module name to the file path. |
3977 | 3977 | ||
3978 | **Signature:** | 3978 | **Signature:** |
3979 | ```lua | 3979 | ```lua |
@@ -4000,7 +4000,7 @@ find_modulepath: function(name: string): string | |||
4000 | 4000 | ||
4001 | Calls a function in protected mode. | 4001 | Calls a function in protected mode. |
4002 | Catches any errors and returns a status code and results or error object. | 4002 | Catches any errors and returns a status code and results or error object. |
4003 | Rewrites the error line number to the original line number in the Yuescript code when errors occur. | 4003 | Rewrites the error line number to the original line number in the YueScript code when errors occur. |
4004 | 4004 | ||
4005 | **Signature:** | 4005 | **Signature:** |
4006 | ```lua | 4006 | ```lua |
@@ -4026,8 +4026,8 @@ pcall: function(f: function, ...: any): boolean, any... | |||
4026 | 4026 | ||
4027 | **Description:** | 4027 | **Description:** |
4028 | 4028 | ||
4029 | Loads a given module. Can be either a Lua module or a Yuescript module. | 4029 | Loads a given module. Can be either a Lua module or a YueScript module. |
4030 | Rewrites the error line number to the original line number in the Yuescript code if the module is a Yuescript module and loading fails. | 4030 | Rewrites the error line number to the original line number in the YueScript code if the module is a YueScript module and loading fails. |
4031 | 4031 | ||
4032 | **Signature:** | 4032 | **Signature:** |
4033 | ```lua | 4033 | ```lua |
@@ -4084,7 +4084,7 @@ options: Config.Options | |||
4084 | 4084 | ||
4085 | **Description:** | 4085 | **Description:** |
4086 | 4086 | ||
4087 | The traceback function that rewrites the stack trace line numbers to the original line numbers in the Yuescript code. | 4087 | The traceback function that rewrites the stack trace line numbers to the original line numbers in the YueScript code. |
4088 | 4088 | ||
4089 | **Signature:** | 4089 | **Signature:** |
4090 | ```lua | 4090 | ```lua |
@@ -4178,8 +4178,8 @@ to_ast: function(code: string, flattenLevel?: number, astName?: string): | |||
4178 | 4178 | ||
4179 | **Description:** | 4179 | **Description:** |
4180 | 4180 | ||
4181 | Requires the Yuescript module. | 4181 | Requires the YueScript module. |
4182 | Rewrites the error line number to the original line number in the Yuescript code when loading fails. | 4182 | Rewrites the error line number to the original line number in the YueScript code when loading fails. |
4183 | 4183 | ||
4184 | **Signature:** | 4184 | **Signature:** |
4185 | ```lua | 4185 | ```lua |