Deukhoofd
/
Angelscript
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Angelscript/docs/manual/doc_adv_custom_options.html

192 lines
20 KiB
HTML
Raw Permalink Normal View History

initial commit
2021-04-12 18:25:02 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.18"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Custom options</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">AngelScript
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.18 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('doc_adv_custom_options.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Custom options </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Most applications have different needs and AngelScript is meant to be as flexible as possible to suit everybody. For this reason there are several options for customizing the script engine for the best fit.</p>
<h1><a class="anchor" id="doc_adv_custom_options_reg_types"></a>
Registerable types</h1>
<p>Even types that one might normally expect to be built-in to a script language, e.g. string, array, and other container classes, are <a class="el" href="doc_register_type.html">registered by the application</a>. This is to allow the application to provide the exact implementation desired.</p>
<p>Of course, should the application developer want to use a premade implementation the <a class="el" href="doc_addon_script.html">add-ons provide just that</a>.</p>
<h1><a class="anchor" id="doc_adv_custom_options_lang_mod"></a>
Language modifications</h1>
<p>The engine method <a class="el" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a> permits making runtime choices about several different behaviours in the engine.</p>
<p>The following modify the script language in one way or the other:</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fabed7d49670612ec27227210021926692">asEP_DISALLOW_EMPTY_LIST_ELEMENTS</a></p>
<p>By turning on this option the compiler will no longer accept empty list elements in initialization lists. The following will for example not be supported:</p>
<pre>
array&lt;int&gt; arr = {1,2,,4,5,};
</pre><p>When not turned on, the compiler will leave the empty list elements with the uninitialized value, just as an uninitialized variable of the same type.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa563bec877e91b0646c47197b2ae7ac0c">asEP_DISALLOW_VALUE_ASSIGN_FOR_REF_TYPE</a></p>
<p>By turning on this the compiler will no longer allow the use of value assignment operators on reference types. While it may seem drastic, it can help reduce risk for bugs in the scripts, as the script writer will no longer be able to do a value assignment by mistake when he meant to a handle assignment. Reference types should usually <br />
not be copied, so the imposed restriction will likely not cause problems anyway.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa8facaf887921a6b26e5a1f06e01ec37a">asEP_ALLOW_UNSAFE_REFERENCES</a></p>
<p>By turning on unsafe references you allow in-out references to be used for primitives and value types too. Normally this will work fine, just as it does in ordinary languages such as C++, but know that it is quite possible to write scripts that will cause memory invasions or crashes if the references are not properly guarded. With this option turned on you cannot consider the scripts to be sand-boxed any longer.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6dc1c33f9227c66f18fc0f95a0c798b2">asEP_USE_CHARACTER_LITERALS</a>, <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa218fdf7e181bf9ee0498112f5a87c415">asEP_ALLOW_MULTILINE_STRINGS</a>, <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa02405d96a12b81aa816986b22bf752c2">asEP_SCRIPT_SCANNER</a>, <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fab6daa2ae0c712da7f6f16d698305fba1">asEP_STRING_ENCODING</a></p>
<p>These options are used to determine how strings are treated by the compiler. The details are described in <a class="el" href="doc_strings.html">Custom string type</a>.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa9658b61d2368cc84fe816c817444e0ba">asEP_HEREDOC_TRIM_MODE</a></p>
<p>With this option the compiler can be set to always trim <a class="el" href="doc_datatypes_strings.html">heredoc strings</a>, only trim if it is multiple lines, or never trim them.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa77c3747503489ca122aa61276dae3c1f">asEP_ALLOW_IMPLICIT_HANDLE_TYPES</a></p>
<p>This option is experimental. By turning it on script classes can be declared to always be treated as handles by declaring the class with @ before the name of the class. When this is done all variables of that type will be handles, and the assignment operator will always perform a handle assignment.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa90adb1e54ce0217235545941daa2dccd">asEP_REQUIRE_ENUM_SCOPE</a></p>
<p>With this option all enum values must be prefixed with the enum type using the scope operator to qualify.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0facc694c9d52274a113262ebf5984f20ad">asEP_PROPERTY_ACCESSOR_MODE</a></p>
<p>By default <a class="el" href="doc_script_class_prop.html">virtual property accessors</a> when declared as individual functions need to be marked as such with the keyword 'property', or else the compiler won't consider the functions as virtual properties. This behaviour was introduced in version 2.33.1.</p>
<p>Before this version, the compiler would automatically identify functions with the pre-fix 'get_' or 'set_' as virtual property accessors if the function signature was appropriate. This led to undesired behaviour when developers would declare such functions without the intention of them being used as virtual properties and yet the compiler used them as such.</p>
<p>For backwards compatibility it is still possible to configure the engine to use this behaviour by setting the engine property asEP_PROPERTY_ACCESSOR_MODE to 2.</p>
<p>If it also possible to disable virtual property accessors all together by setting the engine property to 0. Setting the option to 1 only allows virtual property accessors for registered functions, but still without requiring the keyword 'property'.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fab81c81f4fdeb616dd6487da48a0c3456">asEP_DISALLOW_GLOBAL_VARS</a></p>
<p>The application can disable the ability to declare global variables in scripts completely. This can be useful in such cases when the application wish to have full control of what can and cannot be stored by a script. <br />
</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6d80b60995ad046918b2376d7d79f2af">asEP_ALWAYS_IMPL_DEFAULT_CONSTRUCT</a></p>
<p>If this flag is set to true, the compiler will always provide a default constructor for classes even if it hasn't been implemented by the script. Normally this option is not recommended, because if a script class provides a non-default constructor but not the default constructor it is most likely because it is desired that the class should always be initialized with the non-default constructor.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa9c876445c7d138ad096705fc18f311d1">asEP_ALTER_SYNTAX_NAMED_ARGS</a></p>
<p>If this flag is set to 1 or 2 the compiler will accept the '=' instead of ':' for <a class="el" href="doc_expressions.html#function">naming arguments in function calls</a>. When option 1 is used the compiler will warn about it, so the script writer can update the script to the correct ':' token. When option 2 is used both '=' and ':' are accepted silently.</p>
<p>Observe that the use of the '=' token for naming arguments may cause a bit of a confusion. Especially if there is a variable with the same name as the function argument as the script writer may think he's updating the value of the variable, but is just naming the function argument.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fae6af9c6963372e11c6da873868f594cd">asEP_DISABLE_INTEGER_DIVISION</a></p>
<p>This option changes the default behaviour of the / and /= operators. When true, this option replaces integer division with floating-point division, e.g. 1/2 == 0.5 instead of 1/2 == 0</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0faa6f88a81f5706542acb94f3c470ac3f3">asEP_PRIVATE_PROP_AS_PROTECTED</a></p>
<p>When this option is set to true the compiler will not prevent the access to private properties inherited from the parent class. It will only write a warning.</p>
<p>This option is provided to give backwards compatibility for scripts written between versions 2.19.1, when support for private properties was added, albeit working more like protected properties, and version 2.30.0 when the behaviour was changed so that private properties work like in other languages, i.e. they can't be accessed by derived classes.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa651f1843c922a61ccee5c81fac58e4d1">asEP_ALLOW_UNICODE_IDENTIFIERS</a></p>
<p>When this option is set to true the compiler will accept identifiers that contain characters with byte value higher than 127. This permits the use of international characters in the identifiers as the script can be encoded in UTF-8 format and compiler normally.</p>
<h1><a class="anchor" id="doc_adv_custom_options_engine"></a>
Engine behaviours</h1>
<p>There are also several options in <a class="el" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a> for modifying the way the engine behaves.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fab441e1bdd7488bbe8f6dfa9c6b80e4fc">asEP_MAX_NESTED_CALLS</a></p>
<p>This property defines how many recursive nested calls the engine should accept. In this context a nested call is when a script calls into an application registered function that in turn calls another script function. The second call is then said to be a nested call.</p>
<p>By default the engine will accept 100 nested calls.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6159294272e4d20dd4b35359a25f3ac6">asEP_OPTIMIZE_BYTECODE</a></p>
<p>Normally this option is only used for testing the library, but should you find that the compilation time takes too long, then it may be of interest to turn off the bytecode optimization pass by setting this option to false.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fabf1577418b716c92f0a85be3e2617243">asEP_COPY_SCRIPT_SECTIONS</a></p>
<p>If you want to spare some dynamic memory and the script sections passed to the engine is already stored somewhere in memory then you can turn off this options. If you do you'll need to be careful not to modify or deallocate the script sections until module has been built.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa1ab4c8f8734f0d90bee4005afd810f83">asEP_MAX_STACK_SIZE</a>, <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6d74b8325be718ace661484f1e8e7fb1">asEP_INIT_STACK_SIZE</a>, <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa4d8ec81a881162a1f0689b56ba864346">asEP_MAX_CALL_STACK_SIZE</a>, <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0faabb0261a40d98af8a0f6d38c2150a4e8">asEP_INIT_CALL_STACK_SIZE</a></p>
<p>The script context's data stack grows dynamically as needed during executions. By default there is no limit to how large it may grow, but if you wish to set this limit you can do with the asEP_MAX_STACK_SIZE option. The limit is given in bytes, but it is only an approximate limit. Setting the limit to 1MB doesn't mean the stack will grow exactly to 1MB, but you can be certain that it will not grow much beyond that.</p>
<p>Whenever a context attempts to grow the stack more than it is allowed, it will abort the execution and return a 'stack overflow' script exception.</p>
<p>Similarly the call stack also grows dynamically as needed during executions. The default here is also no limit, with the ability to limit maximum size by setting the asEP_MAX_CALL_STACK_SIZE. This limit is set in number of function calls.</p>
<p>In some cases it may be useful to set the initial stack size too, e.g. if you know beforehand that a large stack is needed, or if you wish to avoid any runtime memory allocations during an execution. In this case you can use the asEP_INIT_STACK_SIZE for the data stack, and asEP_INIT_CALL_STACK_SIZE for the call stack.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa73b396e4ea6376f0962d19add962bd91">asEP_BUILD_WITHOUT_LINE_CUES</a></p>
<p>This option can be used to speed up the execution of scripts a bit. It is best described in <a class="el" href="doc_finetuning.html#doc_finetuning_3">Compile scripts without line cues</a>.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0facac241d97facce4eaf9e5b0ca40dfcf1">asEP_INIT_GLOBAL_VARS_AFTER_BUILD</a></p>
<p>By default the global variables in the script modules are initialized immediately after building the scripts, but sometimes this is not desired. For example, if you debug the initialization of the variables, or if you're building an offline compiler, or even if you want to add extra validation of the variables to make sure the script doesn't declare any variables you don't want it to.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_adv_precompile.html">Pre-compiled byte code</a></dd></dl>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa7ff74f4afa490b55839daaf217cf898c">asEP_INCLUDE_JIT_INSTRUCTIONS</a></p>
<p>In order for JIT compilation to work properly it needs to have some hints in the bytecode so it can know where a switch from bytecode execution to JIT compiled execution shall be done. By default this option is turned off as it would just add an overhead to the bytecode, but when using JIT compilation this overhead will be compensated by the faster execution with direct machine code.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_adv_jit.html">How to build a JIT compiler</a></dd></dl>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa530e8d9576f94a258446c5fb9b7bd7a5">asEP_EXPAND_DEF_ARRAY_TO_TMPL</a></p>
<p>This option is to determine how the <a class="el" href="classas_i_script_engine.html#ac9451feece1297eba8d1649036039e82">default array type</a> is displayed in compiler messages and function declarations, e.g. int[] or array&lt;int&gt;.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa9b5d1d8ff5143a6a77dfd18143d87c7d">asEP_AUTO_GARBAGE_COLLECT</a></p>
<p>By default AngelScript's incremental garbage collector is executed as scripts are invoked by the application. This does add a slight overhead to the execution, which is normally tolerable but in some applications the CPU cycles may be needed for other things. In this case the automatic execution of the garbage collector can be turned off to hold off on the execution until the CPU can be spared.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_gc.html">Garbage collection</a></dd></dl>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fadd96da828860b5de2352de07c2456633">asEP_COMPILER_WARNINGS</a></p>
<p>Compiler warnings can be turned off or treated as errors by setting this engine property.</p>
<p><a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa58fa0f29330923b24ab795e7c6ada52e">asEP_GENERIC_CALL_MODE</a></p>
<p>By default the <a class="el" href="doc_generic.html">generic calling convention</a> treats the ref counts in the handles the same way that the native calling convention, i.e. releases any handles passed to a function if they have been marked as auto handles, and increments the returned handle if it has been marked as auto handle.</p>
<p>If the behaviour used before 2.33.0 is desired for backwards compatibility, then set this property to 0. In this case the generic calling convention will always release references for handles received in arguments, and never increment references for returned handles. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Sat Dec 5 2020 23:20:24 for AngelScript by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.18 </li>
</ul>
</div>
</body>
</html>