# yue

**Description:**

  The YueScript language library.

## version

**Type:** Field.

**Description:**

  The YueScript version.

**Signature:**
```tl
version: string
```

## dirsep

**Type:** Field.

**Description:**

  The file separator for the current platform.

**Signature:**
```tl
dirsep: string
```

## yue_compiled

**Type:** Field.

**Description:**

  The compiled module code cache.

**Signature:**
```tl
yue_compiled: {string: string}
```

## to_lua

**Type:** Function.

**Description:**

  The YueScript compiling function. It compiles the YueScript code to Lua code.

**Signature:**
```tl
to_lua: function(code: string, config?: Config):
		--[[codes]] string | nil,
		--[[error]] string | nil,
		--[[globals]] {{string, integer, integer}} | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| code | string | The YueScript code. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| string \| nil | The compiled Lua code, or nil if the compilation failed. |
| string \| nil | The error message, or nil if the compilation succeeded. |
| \{\{string, integer, integer}} \| nil | The global variables appearing in the code (with name, row and column), or nil if the compiler option `lint_global` is false. |

## file_exist

**Type:** Function.

**Description:**

  The source file existence checking function. Can be overridden to customize the behavior.

**Signature:**
```tl
file_exist: function(filename: string): boolean
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| filename | string | The file name. |

**Returns:**

| Return Type | Description |
| --- | --- |
| boolean | Whether the file exists. |

## read_file

**Type:** Function.

**Description:**

  The source file reading function. Can be overridden to customize the behavior.

**Signature:**
```tl
read_file: function(filename: string): string
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| filename | string | The file name. |

**Returns:**

| Return Type | Description |
| --- | --- |
| string | The file content. |

## insert_loader

**Type:** Function.

**Description:**

  Insert the YueScript loader to the package loaders (searchers).

**Signature:**
```tl
insert_loader: function(pos?: integer): boolean
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| pos | integer | [Optional] The position to insert the loader. Default is 3. |

**Returns:**

| Return Type | Description |
| --- | --- |
| boolean | Whether the loader is inserted successfully. It will fail if the loader is already inserted. |

## remove_loader

**Type:** Function.

**Description:**

  Remove the YueScript loader from the package loaders (searchers).

**Signature:**
```tl
remove_loader: function(): boolean
```

**Returns:**

| Return Type | Description |
| --- | --- |
| boolean | Whether the loader is removed successfully. It will fail if the loader is not inserted. |

## loadstring

**Type:** Function.

**Description:**

  Loads YueScript code from a string into a function.

**Signature:**
```tl
loadstring: function(input: string, chunkname: string, env: table, config?: Config):
		--[[loaded function]] nil | function(...: any): (any...),
		--[[error]] string | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| input | string | The YueScript code. |
| chunkname | string | The name of the code chunk. |
| env | table | The environment table. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| function \| nil | The loaded function, or nil if the loading failed. |
| string \| nil | The error message, or nil if the loading succeeded. |

## loadstring

**Type:** Function.

**Description:**

  Loads YueScript code from a string into a function.

**Signature:**
```tl
loadstring: function(input: string, chunkname: string, config?: Config):
		--[[loaded function]] nil | function(...: any): (any...),
		--[[error]] string | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| input | string | The YueScript code. |
| chunkname | string | The name of the code chunk. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| function \| nil | The loaded function, or nil if the loading failed. |
| string \| nil | The error message, or nil if the loading succeeded. |

## loadstring

**Type:** Function.

**Description:**

  Loads YueScript code from a string into a function.

**Signature:**
```tl
loadstring: function(input: string, config?: Config):
		--[[loaded function]] nil | function(...: any): (any...),
		--[[error]] string | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| input | string | The YueScript code. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| function \| nil | The loaded function, or nil if the loading failed. |
| string \| nil | The error message, or nil if the loading succeeded. |

## loadfile

**Type:** Function.

**Description:**

  Loads YueScript code from a file into a function.

**Signature:**
```tl
loadfile: function(filename: string, env: table, config?: Config):
		nil | function(...: any): (any...),
		string | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| filename | string | The file name. |
| env | table | The environment table. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| function \| nil | The loaded function, or nil if the loading failed. |
| string \| nil | The error message, or nil if the loading succeeded. |

## loadfile

**Type:** Function.

**Description:**

  Loads YueScript code from a file into a function.

**Signature:**
```tl
loadfile: function(filename: string, config?: Config):
		nil | function(...: any): (any...),
		string | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| filename | string | The file name. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| function \| nil | The loaded function, or nil if the loading failed. |
| string \| nil | The error message, or nil if the loading succeeded. |

## dofile

**Type:** Function.

**Description:**

  Loads YueScript code from a file into a function and executes it.

**Signature:**
```tl
dofile: function(filename: string, env: table, config?: Config): any...
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| filename | string | The file name. |
| env | table | The environment table. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| any... | The return values of the loaded function. |

## dofile

**Type:** Function.

**Description:**

  Loads YueScript code from a file into a function and executes it.

**Signature:**
```tl
dofile: function(filename: string, config?: Config): any...
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| filename | string | The file name. |
| config | Config | [Optional] The compiler options. |

**Returns:**

| Return Type | Description |
| --- | --- |
| any... | The return values of the loaded function. |

## find_modulepath

**Type:** Function.

**Description:**

  Resolves the YueScript module name to the file path.

**Signature:**
```tl
find_modulepath: function(name: string): string
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| name | string | The module name. |

**Returns:**

| Return Type | Description |
| --- | --- |
| string | The file path. |

## pcall

**Type:** Function.

**Description:**

  Calls a function in protected mode.
Catches any errors and returns a status code and results or error object.
Rewrites the error line number to the original line number in the YueScript code when errors occur.

**Signature:**
```tl
pcall: function(f: function, ...: any): boolean, any...
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| f | function | The function to call. |
| ... | any | Arguments to pass to the function. |

**Returns:**

| Return Type | Description |
| --- | --- |
| boolean, ... | Status code and function results or error object. |

## require

**Type:** Function.

**Description:**

  Loads a given module. Can be either a Lua module or a YueScript module.
Rewrites the error line number to the original line number in the YueScript code if the module is a YueScript module and loading fails.

**Signature:**
```tl
require: function(name: string): any...
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| modname | string | The name of the module to load. |

**Returns:**

| Return Type | Description |
| --- | --- |
| any | The value stored at package.loaded[modname] if the module is already loaded.<br/>Otherwise, tries to find a loader and returns the final value of package.loaded[modname] and a loader data as a second result. |

## p

**Type:** Function.

**Description:**

&emsp;&emsp;Inspects the structures of the passed values and prints string representations.

**Signature:**
```tl
p: function(...: any)
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| ... | any | The values to inspect. |

## options

**Type:** Field.

**Description:**

&emsp;&emsp;The current compiler options.

**Signature:**
```tl
options: Config.Options
```

## traceback

**Type:** Function.

**Description:**

&emsp;&emsp;The traceback function that rewrites the stack trace line numbers to the original line numbers in the YueScript code.

**Signature:**
```tl
traceback: function(message: string): string
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| message | string | The traceback message. |

**Returns:**

| Return Type | Description |
| --- | --- |
| string | The rewritten traceback message. |

## compile

**Type:** Function.

**Description:**

&emsp;&emsp;Compiles the YueScript code to Lua code in a thread.

**Signature:**
```tl
compile: function(
		sourceFile: string,
		targetFile: string,
		searchPath: string,
		compileCodesHandler: CompileCodeHandler,
		callback: function(result: boolean)
	)
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| sourceFile | string | The source file name. |
| targetFile | string | The target file name. |
| searchPath | string | The extra module search path. |
| compileCodesHandler | CompileCodeHandler | The callback function to handle the compiled codes. |
| callback | function | The callback function to handle the result. |

## is_ast

**Type:** Function.

**Description:**

&emsp;&emsp;Checks whether the code matches the specified AST.

**Signature:**
```tl
is_ast: function(astName: string, code: string): boolean
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| astName | string | The AST name. |
| code | string | The code. |

**Returns:**

| Return Type | Description |
| --- | --- |
| boolean | Whether the code matches the AST. |

## AST

**Type:** Type Definition.

**Description:**

&emsp;&emsp;The AST type definition with name, row, column and sub nodes.

**Signature:**
```tl
type AST = {string, integer, integer, any}
```

## to_ast

**Type:** Function.

**Description:**

&emsp;&emsp;Converts the code to the AST.

**Signature:**
```tl
to_ast: function(code: string, flattenLevel?: number, astName?: string):
		--[[AST]] AST | nil,
		--[[error]] nil | string
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| code | string | The code. |
| flattenLevel | integer | [Optional] The flatten level. Higher level means more flattening. Default is 0. Maximum is 2. |
| astName | string | [Optional] The AST name. Default is "File". |

**Returns:**

| Return Type | Description |
| --- | --- |
| AST \| nil | The AST, or nil if the conversion failed. |
| string \| nil | The error message, or nil if the conversion succeeded. |

## checkAsync

**Type:** Function.

**Description:**

&emsp;&emsp;Checks for the problems in the YueScript code asynchronously.
Should be called in a coroutine thread.

**Signature:**
```tl
checkAsync: function(yueCodes: string, searchPath: string, lax: boolean):
		--[[info]] {{
			--[[type]] string,
			--[[msg]] string,
			--[[line]] integer,
			--[[col]] integer
		}},
		--[[luaCodes]] string | nil
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| yueCodes | string | The YueScript code. |
| searchPath | string | The extra module search path. |
| lax | boolean | Using lax mode. |

**Returns:**

| Return Type | Description |
| --- | --- |
| \{info} | The problem information with type, message, line and column as an array. |
| string \| nil | The Lua codes when no problem found, or nil if the checking failed. |

## clear

**Type:** Function.

**Description:**

&emsp;&emsp;Clears the compiled macro functions in cache.

**Signature:**
```tl
clear: function()
```

## __call

**Type:** Metamethod.

**Description:**

&emsp;&emsp;Requires the YueScript module.
Rewrites the error line number to the original line number in the YueScript code when loading fails.

**Signature:**
```tl
metamethod __call: function(self: yue, module: string): any...
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| module | string | The module name. |

**Returns:**

| Return Type | Description |
| --- | --- |
| any | The module value. |