code:
/**

\page doc_register_type Registering an object type

The are two principal paths to take when registering a new type, either the
type is a reference type that is located in dynamic memory, or the type is a
value type that is located on the stack or locally as members of other objects.
A reference type support object handles (unless restricted by application) but
cannot be passed by value to application registered functions, a value type
doesn't support handles and can be passed by value or reference to application
registered functions.

There is no given rule when to use one or the other, but in general you'll use
reference types when the type must be able to outlive the scope in which it is
created, and value types when the type is normally used to perform quick
calculations after which the object can be discarded. If the type is large or
complex, then it is likely it should be a reference type.

 - \subpage doc_reg_basicref
 - \subpage doc_register_val_type
 - \subpage doc_reg_opbeh
 - \subpage doc_reg_objmeth
 - \subpage doc_reg_objprop

\page doc_reg_basicref Registering a reference type

The basic reference type should be registered with the following behaviours:
\ref asBEHAVE_FACTORY, \ref asBEHAVE_ADDREF, and \ref asBEHAVE_RELEASE.

\code
// Registering the reference type
r = engine->RegisterObjectType("ref", 0, asOBJ_REF); assert( r >= 0 );
\endcode

\see The \ref doc_addon_any "any" add-on for an example of a reference type.

\see \ref doc_gc_object, \ref doc_adv_class_hierarchy, \ref doc_adv_scoped_type, and \ref doc_adv_single_ref_type for more advanced types.

\section doc_reg_basicref_1 Factory function

The factory function is the one that AngelScript will use to instantiate
objects of this type when a variable is declared. It is responsible for
allocating and initializing the object memory.

The default factory function doesn't take any parameters and should return
an object handle for the new object. Make sure the object's reference counter
is accounting for the reference being returned by the factory function, so
that the object is properly released when all references to it are removed.

\code
CRef::CRef()
{
    // Let the constructor initialize the reference counter to 1
    refCount = 1;
}

CRef *Ref_Factory()
{
    // The class constructor is initializing the reference counter to 1
    return new CRef();
}

// Registering the factory behaviour
r = engine->RegisterObjectBehaviour("ref", asBEHAVE_FACTORY, "ref@ f()", asFUNCTION(Ref_Factory), asCALL_CDECL); assert( r >= 0 );
\endcode

You may also register factory functions that take parameters, which may
then be used when initializing the object.

The factory function must be registered as a global function, but can be
implemented as a static class method, common global function, or a global
function following the generic calling convention.

Even though a factory function returns an object handle, it must not return a null handle
unless it also sets an exception to signal that the instantiation of the object failed.

The behaviour is undefined if a factory function returns null without setting an exception.

\subsection doc_reg_basicref_1_1 Factory function with auxiliary object

Also factory functions are supposed to be global functions it is possible to use an auxiliary object,
e.g. a factory singleton, to aid in the construction of the objects. To do this the application must
use the calling convention asCALL_CDECL_OBJFIRST or asCALL_CDECL_OBJLAST and inform the address of the
auxiliary object when registering the factory function.

The factory function will then receive the address of the auxiliary object as the first or last parameter
depending on the calling convention informed.

\code
// A helper object used by factory functions
class HelperObject {...} aux;

// The factory function receives the address of the helper object as the last argument
CRef *Ref_Factory(int arg, HelperObject *aux) {...}

// Registering the factory behaviour with auxiliary object. The helper object is not part of the function signature
r = engine->RegisterObjectBehaviour("ref", asBEHAVE_FACTORY, "ref@ f(int)", asFUNCTION(Ref_Factory), asCALL_CDECL_OBJLAST, &aux); assert( r >= 0 );
\endcode

\subsection doc_reg_basicref_4 List factory function

The list factory function is a special \ref doc_reg_basicref_1 "factory function" that
can be registered to allow a type to be created from an initialization list. The list factory
function takes only a single pointer as argument. AngelScript will pass a pointer to the
initialization list buffer in that argument. The buffer will contain all the values necessary
to create and initialize the object.

In order for the script engine to know what information must be placed in the buffer the
application must provide the list pattern when registering the list factory. The list pattern
is declared with a special syntax involving datatypes and the following tokens: {, }, ?, repeat, and repeat_same.

The tokens { } are used to declare that the list pattern expects a list of values or a sublist of values.
The repeat token is used to signal that the next type or sub list can be repeated 0 or more times.
The repeat_same token is similar to repeat except that it also tells the compiler that every time the same
list is repeated it should have the same length. Any data type can be used in the list pattern, as long
as it can be passed by value. When a variable type is desired the token ? can be used.

Here's a couple of examples for registering list factories with list patterns:

\code
// The array type can be initialized for example with: intarray a = {1,2,3};
engine->RegisterObjectBehaviour("intarray", asBEHAVE_LIST_FACTORY,
  "intarray@ f(int &in) {repeat int}", ...);

// The dictionary type can be initialized with: dictionary d = {{'a',1}, {'b',2}, {'c',3}};
engine->RegisterObjectBehaviour("dictionary", asBEHAVE_LIST_FACTORY,
  "dictionary @f(int &in) {repeat {string, ?}}", ...);

// The grid type can be initialized with: grid a = {{1,2},{3,4}};
engine->RgisterObjectBehaviour("grid", asBEHAVE_LIST_FACTORY,
  "grid @f(int &in) {repeat {repeat_same int}}", ...);
\endcode

The list buffer passed to the factory function will be populated using the following rules:

- Whenever the pattern expects a repeat, the buffer will contain a 32bit integer with the
  number of repeated values that will come afterwards
- Whenever the pattern expects a ?, then the buffer will contain a 32bit integer representing
  the typeId of the value that comes after.
- Whenever the pattern expects a reference type, the buffer will contain a pointer to the object
- Whenever the pattern expects a value type, the buffer will contain the object itself
- All values in the buffer will be aligned to a 32bit boundary, unless the size of the value placed
  in the buffer is smaller than 32bits.

\see \ref doc_addon_array and \ref doc_addon_dict for example implementations of list factories.

\section doc_reg_basicref_2 Addref and release behaviours

\code
void CRef::Addref()
{
    // Increase the reference counter
    refCount++;
}

void CRef::Release()
{
    // Decrease ref count and delete if it reaches 0
    if( --refCount == 0 )
        delete this;
}

// Registering the addref/release behaviours
r = engine->RegisterObjectBehaviour("ref", asBEHAVE_ADDREF, "void f()", asMETHOD(CRef,AddRef), asCALL_THISCALL); assert( r >= 0 );
r = engine->RegisterObjectBehaviour("ref", asBEHAVE_RELEASE, "void f()", asMETHOD(CRef,Release), asCALL_THISCALL); assert( r >= 0 );
\endcode

If the instances of this object will be shared between multiple threads, remember
to guarantee that the reference counter is thread safe by making the increments
and decrements with atomic instructions.

\see \ref doc_adv_multithread

\section doc_reg_nocount Reference types without reference counting

If the application provides its own memory management that isn't based on reference counting,
then it is possible to register the type without the addref and release behaviours if the flag,
asOBJ_NOCOUNT is informed in the call to RegisterObjectType, i.e.

\code
// Registering the reference type
r = engine->RegisterObjectType("ref", 0, asOBJ_REF | asOBJ_NOCOUNT); assert( r >= 0 );
\endcode

Without the addref and release behaviours the application must be careful to not destroy any
objects that may potentially still be referenced by the script engine, e.g. in a global variable,
or other location.

Unless the objects are guaranteed to stay alive as long as the script engine is instantiated, you
may want to consider disabling global variables with engine property \ref asEP_DISALLOW_GLOBAL_VARS.
This will make it much easier for the application to know where references to the objects are kept.
An alternative to disabling all global variables, is to selectively disallow only the global variables,
that can eventually store a reference to the object type. This can be done by
\ref asIScriptModule::GetGlobalVarCount "enumerating the compiled global variables" after script has
been built and giving an error to the user in case he includes a variable he shouldn't.

\section doc_reg_noinst Registering an uninstantiable reference type

Sometimes it may be useful to register types that cannot be instantiated by
the scripts, yet can be interacted with. You can do this by registering the
type as a normal reference type, but omit the registration of the factory
behaviour. You can later register global properties, or functions that allow the
scripts to access objects created by the application via object handles.

This would be used when the application has a limited number of objects
available and doesn't want to create new ones. For example singletons, or
pooled objects.

\page doc_register_val_type Registering a value type

When registering a value type, the size of the type must be given so that AngelScript knows how much space is needed for it.
If the type doesn't require any special treatment, i.e. doesn't contain any pointers or other resource references that must be
maintained, then the type can be registered with the flag \ref asOBJ_POD. In this case AngelScript doesn't require the default
constructor, assignment behaviour, or destructor as it will be able to automatically handle these cases the same way it handles
built-in primitives.

If you plan on passing or returning the type by value to registered functions that uses native calling convention, you also
need to inform \ref doc_reg_val_2 "how the type is implemented in the application", but if you only plan on using generic
calling conventions, or don't pass these types by value then you don't need to worry about that.

\code
// Register a primitive type, that doesn't need any special management of the content
r = engine->RegisterObjectType("pod", sizeof(pod), asOBJ_VALUE | asOBJ_POD); assert( r >= 0 );

// Register a class that must be properly initialized and uninitialized
r = engine->RegisterObjectType("val", sizeof(val), asOBJ_VALUE); assert( r >= 0 );
\endcode

\see The \ref doc_addon_std_string or the \ref doc_addon_math "complex type in the math add-on" for examples of value types
\see \ref doc_adv_generic_handle for a more specific example of a value type
\see \ref doc_gc_object for when the type may form circular references when being a member of another type

\section doc_reg_val_1 Constructor and destructor

If a constructor or destructor is needed they shall be registered the following way:

\code
void Constructor(void *memory)
{
  // Initialize the pre-allocated memory by calling the
  // object constructor with the placement-new operator
  new(memory) Object();
}

void Destructor(void *memory)
{
  // Uninitialize the memory by calling the object destructor
  ((Object*)memory)->~Object();
}

// Register the behaviours
r = engine->RegisterObjectBehaviour("val", asBEHAVE_CONSTRUCT, "void f()", asFUNCTION(Constructor), asCALL_CDECL_OBJLAST); assert( r >= 0 );
r = engine->RegisterObjectBehaviour("val", asBEHAVE_DESTRUCT, "void f()", asFUNCTION(Destructor), asCALL_CDECL_OBJLAST); assert( r >= 0 );
\endcode

Remember to use unique names or namespaces for the wrapper functions, even if you create templated
implementations. Otherwise the linker may end up taking the address of the wrong function when registering
the wrapper with AngelScript, which is sure to result in unexpected behaviours.

Note that you may need to include the <new> header to declare the placement new operator that is used
to initialize a preallocated memory block.

\subsection doc_reg_val_3 List constructor

The list constructor is similar to \ref doc_reg_basicref_4 "the list factory function" for reference types.
The constructor will receive a pointer to the initialization list buffer in the exact same way, and the
expected list pattern should be registered in the same way. The difference is that the list constructor
should be registered like a method, just as done for other \ref doc_reg_val_1 "constructors".

Example registration of a list constructor:

\code
engine->RegisterObjectBehaviour("vector3", asBEHAVE_LIST_CONSTRUCT, "void f(int &in) {float, float, float}", ...);
\endcode

\see \ref doc_addon_math "The complex math add-on" for an example value type with a list constructor.

\section doc_reg_val_2 Value types and native calling conventions

If the type will be passed to or from the application by value using native calling conventions it is important to inform
AngelScript of its real type in C++, otherwise AngelScript won't be able to determine exactly how C++ is treating the type in
a parameter or return value.

If the flags that inform about the actual type are not informed and AngelScript needs them on the platform, you'll get an error message like
"Don't support passing/returning type 'MyType' by value to application in native calling convention on this platform".

To inform AngelScript of the actual type in C++ the template function \ref asGetTypeTraits should preferably be used as it
will automatically determine most of the flags to pass to \ref asIScriptEngine::RegisterObjectType "RegisterObjectType"
together with the asOBJ_VALUE flag.

\code
// With C++11 the type can be registered with GetTypeTraits
r = engine->RegisterObjectType("complex", sizeof(complex), asOBJ_VALUE | asGetTypeTraits<complex>()); assert( r >= 0 );
\endcode

The following flags are covered by asGetTypeTraits:

\ref asOBJ_APP_CLASS                    	The C++ type is a class, struct, or union

\ref asOBJ_APP_CLASS_CONSTRUCTOR        	The C++ type has a default constructor

\ref asOBJ_APP_CLASS_DESTRUCTOR         	The C++ type has a destructor

\ref asOBJ_APP_CLASS_ASSIGNMENT         	The C++ type has a copy assignment operator

\ref asOBJ_APP_CLASS_COPY_CONSTRUCTOR   	The C++ type has a copy constructor

\ref asOBJ_APP_PRIMITIVE                	The C++ type is a C++ primitive, but not a float or double

\ref asOBJ_APP_FLOAT                    	The C++ type is a float or double

\ref asOBJ_APP_ARRAY                    	The C++ type is an array

\todo explain how to interpret when the constructor, copy constructor or operator= has been defaulted with '= default'

On some platforms the native calling convention may require further knowledge about the class and its members that \ref asGetTypeTraits
cannot determine in order to work properly. Whether or not the flags are needed depends on the compiler and target platform, but if the flags
are not needed AngelScript will simply ignore them so there is no harm in informing them.

Be careful to inform the correct flags, because if the wrong flags are used you may get unexpected behaviour when calling registered
functions that passes or returns these types by value. Common problems are stack corruptions or invalid memory accesses. In some cases
you may face more silent errors that may be difficult to detect, e.g. the function is not returning the expected values.

AngelScript lets the application give information that cover the most common variants, e.g. the class should be treated as
if all members are integers (or non-float primitives), or it should be treated as if all members are floats. It is also possible to inform if the class
has more constructors than the traditional default and copy constructors. This last one normally only has importance if the default and copy constructors
are defaulted.

\ref asOBJ_APP_CLASS_MORE_CONSTRUCTORS   	The C++ class has additional constructors beyond the default and copy constructors

\ref asOBJ_APP_CLASS_ALLINTS             	The C++ class members can be treated as if all integers

\ref asOBJ_APP_CLASS_ALLFLOATS           	The C++ class members can be treated as if all floats or doubles

\ref asOBJ_APP_CLASS_ALIGN8              	The C++ class contains members that may require 8byte alignment, e.g. a double.

\ref asOBJ_APP_CLASS_UNION               	The C++ class contains unions as members.

Here's some examples to better illustrate the use of the flags:

\code
// The presence of the constructor with parameters indicates that the flag asOBJ_APP_CLASS_MORE_CONSTRUCTORS should be used
struct A
{
	A() = default;
	A(const A& o) = default;
	A(float x, float y) { this->x = x; this->y = y; }
};

// The structure only contains non-float primitives so asOBJ_APP_CLASS_ALLINTS should be used
struct B
{
	int a;
	void *b;
};

// The structure only contains floats so asOBJ_APP_CLASS_ALLFLOATS should be used
struct C
{
	float x,y,z;
};

// The structure only contains doubles so the flags asOBJ_APP_CLASS_ALLFLOATS and asOBJ_APP_CLASS_ALIGN8 should be used
struct D
{
	double x,y;
};

// The structure contains union of floats so the flags asOBJ_APP_CLASS_ALLFLOATS and asOBJ_APP_CLASS_UNION should be used
struct E
{
	union {
		float x, s;
	};
	union {
		float y, t;
	};
};
\endcode

It is difficult to explain exactly when one or the other should be used as it requires in-depth knowledge of the ABI for the
respective system, so if you find that you really need to use these flags, make sure you perform adequate testing
to guarantee that your functions are called correctly by the script engine. If neither of these flags work, and you're
not able to change the class to work without them, then the only other option is to use the generic calling convention,
preferably with the \ref doc_addon_autowrap "auto wrappers".

\subsection doc_reg_val_2_nocpp11 For compilers that don't support C++11 and asGetTypeTraits

If your compiler doesn't support C++11 features the \ref asGetTypeTraits function will not be available. In this case you
have no option but to inform the correct flags manually.

Note that the flags don't represent how the type will behave in the script language, only what the real type is in the host
application. So if you want to register a C++ class that you want to behave as a primitive type in the script language
you should still use the flag \ref asOBJ_APP_CLASS. The same thing for the flags to identify that the class has a constructor,
destructor, assignment operator, or copy constructor. These flags tell AngelScript that the class has the respective function,
but not that the type in the script language should have these behaviours.

Observe that the C++ compiler may provide some functions automatically if one of the members of the class is of a type that
requires it. So even if the type you want to register doesn't have a declared default constructor it may still be necessary to
register the type with the flag asOBJ_APP_CLASS_CONSTRUCTOR. The same for the other functions.

For class types there is also a shorter form of the flags for each combination of the 5 flags. They are of the form \ref asOBJ_APP_CLASS_CDAK,
where the existence of the last letters determine if the constructor, destructor, and/or assignment behaviour are available. For example
\ref asOBJ_APP_CLASS_CDAK is defined as \ref asOBJ_APP_CLASS | \ref asOBJ_APP_CLASS_CONSTRUCTOR | \ref asOBJ_APP_CLASS_DESTRUCTOR | \ref asOBJ_APP_CLASS_ASSIGNMENT | \ref asOBJ_APP_CLASS_COPY_CONSTRUCTOR.

\code
// Register a complex type that will be passed by value to the application
r = engine->RegisterObjectType("complex", sizeof(complex), asOBJ_VALUE | asOBJ_APP_CLASS_CDAK); assert( r >= 0 );
\endcode

\page doc_reg_opbeh Registering operator behaviours

In order for AngelScript to know how to work with the application registered types, it is
necessary to register some behaviours, for example for memory management.

The memory management behaviours are described with the registration of
\ref doc_reg_basicref "reference types" and \ref doc_register_val_type "value types".

Other advanced behaviours are described with the \ref doc_advanced_api "advanced types".

Most behaviours are implemented as ordinary class methods, except with specific names that the
compiler can understand.

\section doc_reg_opbeh_1 Operator overloads

In AngelScript all operator overloads are implemented as \ref doc_script_class_ops "class methods with predefined names",
which is different from C++ where both class methods and global functions may be used. Especially the dual operators, i.e.
those that take two operands, usually has one implemented as a class method, and a global function for the reverse order.

To register C++ operator overloads you'll use the methods described in \ref doc_register_func_1.

Example on how to register operator overloads

\code
class MyClass
{
  ...

  // The operator 'MyClass - int' has been implemented as a method
  MyClass operator-(int) const;

  // The operator 'int - MyClass' has been implemented as a global function
  static MyClass operator-(int, const MyClass &);
}

void RegisterMyClass(asIScriptEngine *engine)
{
  // Registering the operator 'MyClass - int'
  engine->RegisterObjectMethod("MyClass", "MyClass opSub(int) const", asMETHODPR(MyClass, operator-, (int) const, MyClass), asCALL_THISCALL);

  // Registering the operator 'int - MyClass'
  engine->RegisterObjectMethod("MyClass", "MyClass opSub_r(int) const", asFUNCTIONPR(operator-, (int, const MyClass &), MyClass), asCALL_CDECL_OBJLAST);
}
\endcode

\page doc_reg_objmeth Registering object methods

Class methods are registered with the RegisterObjectMethod call. Both non-virtual and virtual methods are registered the same way.

Static class methods are in reality global functions so those should be \ref doc_register_func "registered as global functions" and not as object methods.

\code
// Register a class method
void MyClass::ClassMethod()
{
  // Do something
}

r = engine->RegisterObjectMethod("mytype", "void ClassMethod()", asMETHOD(MyClass,ClassMethod), asCALL_THISCALL); assert( r >= 0 );
\endcode

It is also possible to register a global function that takes a pointer to
the object as a class method. This can be used to extend the functionality of
a class when accessed via AngelScript, without actually changing the C++
implementation of the class.

\code
// Register a global function as an object method
void MyClass_MethodWrapper(MyClass *obj)
{
  // Access the object
  obj->DoSomething();
}

r = engine->RegisterObjectMethod("mytype", "void MethodWrapper()", asFUNCTION(MyClass_MethodWrapper), asCALL_CDECL_OBJLAST); assert( r >= 0 );
\endcode

\see \ref doc_register_func for more details on how the macros work.

\section doc_reg_objmeth_composite Composite members

If the application class that is being registered uses composition, then it is possible to register the methods
of the composite members like this:

\code
struct Component
{
  int DoSomething();
};

struct Object
{
  Component *comp;
};

r = engine->RegisterObjectMethod("object", "int DoSomething()", asMETHOD(Component, DoSomething), asCALL_THISCALL, 0, asOFFSET(Object, comp), true); assert( r >= 0 );
\endcode

The last parameter indicates that to reach the composite member it is necessary to dereference
the pointer. If the composite member is inlined, then the parameter should be set to false.

\page doc_reg_objprop Registering object properties

Class member variables can be registered so that they can be directly
accessed by the script without the need for any method calls.

\code
struct MyStruct
{
  int a;
};

r = engine->RegisterObjectProperty("mytype", "int a", asOFFSET(MyStruct,a)); assert( r >= 0 );
\endcode

If a class member is indirect, i.e. the class holds a pointer to the member that is
allocated on the heap, then it is possible to registered the property using & to tell
the script engine that an dereference is needed to access the member.

\code
struct MyStruct
{
  OtherStruct *a;
};

r = engine->RegisterObjectProperty("mytype", "othertype &a", asOFFSET(MyStruct,a)); assert( r >= 0 );
\endcode

Of course, the application must make sure the pointer is valid during the whole time
that it may be accessed from the script.

\todo describe limitation with asOFFSET and members declared as references. suggest manually calculate offset relative to adjacent member, but alert on byte alignment

\section doc_reg_objprop_composite Composite members

If the application class that is being registered uses composition, then it is possible to register the properties
of the composite members like this:

\code
struct Component
{
  int a;
};

struct Object
{
  Component *comp;
};

r = engine->RegisterObjectProperty("object", "comp_a", asOFFSET(Component, a), asOFFSET(Object, comp), true); assert( r >= 0 );
\endcode

The last parameter indicates that to reach the property of the composite member it is necessary to dereference
the pointer. If the composite member is inlined, then the parameter should be set to false.

\section doc_reg_objprop_accessor Property accessors

It is also possible to expose properties through \ref doc_script_class_prop "property accessors",
which are a pair of class methods with prefixes 'get_' and 'set_' and the function decorator 'property' for
getting and setting the property value. These methods should be registered with \ref doc_register_func "RegisterObjectMethod".
This is especially useful when the offset of the property cannot be determined, or if the type of the property is
not registered in the script and some translation must occur, i.e. from <tt>char*</tt> to <tt>string</tt>.

If the application class contains a C++ array as a member, it may be advantageous to expose the array
through \ref doc_script_class_prop "indexed property accessors" rather than attempting to matching the
C++ array type to a registered type in AngelScript. To do this you can create a couple of simple proxy functions
that will translate to the array access.

\note The behaviour of virtual properties can be customized with the engine property \ref doc_adv_custom_options_lang_mod "asEP_PROPERTY_ACCESSOR_MODE".

\code
struct MyStruct
{
  int array[16];
};

// Write a couple of proxy
int MyStruct_get_array(unsigned int idx, MyStruct *o)
{
  if( idx >= 16 ) return 0;
  return o->array[idx];
}

void MyStruct_set_array(unsigned int idx, int value, MyStruct *o)
{
  if( idx >= 16 ) return;
  o->array[idx] = value;
}

// Register the proxy functions as member methods
r = engine->RegisterObjectMethod("mytype", "int get_array(uint) property", asFUNCTION(MyStruct_get_array), asCALL_CDECL_OBJLAST); assert( r >= 0 );
r = engine->RegisterObjectMethod("mytype", "void set_array(uint, int) property", asFUNCTION(MyStruct_set_array), asCALL_CDECL_OBJLAST); assert( r >= 0 );
\endcode

*/


code:
/**

\page doc_samples Samples

This page gives a brief description of the samples that you'll find in the /sdk/samples/ folder.

 - \subpage doc_samples_tutorial
 - \subpage doc_samples_concurrent
 - \subpage doc_samples_console
 - \subpage doc_samples_corout
 - \subpage doc_samples_events
 - \subpage doc_samples_incl
 - \subpage doc_samples_asbuild
 - \subpage doc_samples_game
 - \subpage doc_samples_asrun

\page doc_samples_tutorial Tutorial

Path: /sdk/samples/tutorial/

This sample was written with the intention of explaining the basics of
AngelScript, that is, how to configure the engine, load and compile a script,
and finally execute a script function with parameters and return value.

 - \ref asIScriptEngine::SetMessageCallback
 - LineCallback() function which aborts execution when the time is up
 - Strings
 - Registered global functions
 - Script function parameters and return value
 - Retrieving information about script exceptions
 - asIScriptGeneric for when the library doesn't support native calling convention

\page doc_samples_concurrent Concurrent scripts

Path: /sdk/samples/concurrent/

This sample shows how to execute two or more long running scripts
\ref doc_adv_concurrent "concurrently". The scripts voluntarily hand over the control to the next script in
the queue by calling the function sleep().

 - \ref doc_addon_ctxmgr
 - Multiple scripts running in parallel
 - sleep()
 - Strings
 - Registered global functions

\page doc_samples_console Console

Path: /sdk/samples/console/

This sample implements a simple interactive console, which lets the user type in
commands and also evaluate simple script statements to manipulate the application.

The user is also able to define new variables and functions from the command line.
These functions can then be executed to perform automated tasks.

 - \ref doc_addon_helpers "ExecuteString"
 - \ref asIScriptModule::CompileFunction "CompileFunction", \ref asIScriptModule::CompileGlobalVar "CompileGlobalVar", \ref asIScriptModule::RemoveFunction "RemoveFunction", \ref asIScriptModule::RemoveGlobalVar "RemoveGlobalVar"
 - Enumerate global functions and variables
 - \ref doc_addon_std_string "Strings"
 - Registered global functions and properties
 - Special function _grab() with overloads to receive and print resulting value from script statements

\page doc_samples_corout Co-routines

Path: /sdk/samples/coroutine/

This sample shows how \ref doc_adv_coroutine "co-routines" can be implemented with AngelScript. Co-routines are
threads that can be created from the scripts, and that work together by voluntarily passing control
to each other by calling yield().

 - \ref doc_addon_ctxmgr
 - Co-routines created from the scripts with variable parameter structure.
 - \ref doc_addon_std_string
 - Registered global functions
 - Handling the variable argument type
 - Passing arguments to script functions
 - \ref doc_addon_dict

\page doc_samples_events Events

Path: /sdk/samples/events/

This sample has the script engine execute a long running script. The script execution is regularly
interrupted by the application so that keyboard events can be processed, which execute another short
script before resuming the execution of the main script. The event handling scripts change the state
of the long running script.

 - LineCallback() function which suspends execution when the time is up
 - \ref doc_addon_std_string
 - Registered global functions
 - Scripted event handlers

\page doc_samples_incl Include directive

Path: /sdk/samples/include/

This sample shows how to implement a very simple preprocessor to add support for the \#include
directive, which allow the script writer to reuse common script code. The preprocessor simply adds
the included scripts as multiple script sections, which is ok as AngelScript is able to resolve global
declarations independently of their order. The preprocessor also makes sure that a script file is only
included once, so the script writer doesn't have to take extra care to avoid multiple includes or even
complicated circular includes.

 - \ref doc_addon_build
 - LineCallback() functions which aborts execution when the time is up
 - Processing the \#include directive
 - Circular \#includes are resolved automatically

\page doc_samples_asbuild Generic compiler

Path: /sdk/samples/asbuild/

This sample shows how a generic bytecode compiler can be built to provide offline compilation of scripts.
It takes as input a configuration file that defines the application interface, registers it using dummy
functions and properties, then it compiles the script and saves the bytecode to a file on disk.

The configuration file should preferably be created automatically by calling the \ref doc_addon_helpers "WriteConfigToFile"
helper function. This function should be called from the application that will execute the bytecode, after
the application interface has been fully registered.

 - \ref doc_adv_precompile
 - \ref doc_addon_build
 - \ref asIScriptEngine::SetMessageCallback
 - \ref asEP_INIT_GLOBAL_VARS_AFTER_BUILD
 - \ref asIScriptEngine::ParseToken
 - \ref asIScriptModule::SaveByteCode
 - \ref asIBinaryStream

\page doc_samples_asrun Command line runner

Path: /sdk/samples/asrun/

This samples gives a very basic command line runner for AngelScripts.

It also implements a fully functional command line debugger, with support for setting
breakpoints, stepping through the code, examining variables, etc.

 - \ref doc_debug
 - \ref doc_addon_debugger
 - \ref doc_addon_std_string
 - \ref doc_addon_array
 - \ref doc_addon_dict
 - \ref doc_addon_file
 - \ref doc_addon_filesystem
 - \ref doc_addon_datetime
 - \ref doc_addon_ctxmgr
 - \ref doc_addon_build
 - \ref doc_addon_helpers_try
 - \ref asIScriptEngine::SetContextCallbacks
 - \ref doc_script_stdlib_system
 - Implementing a \#pragma callback

\todo add socket

\see \subpage doc_samples_asrun_manual

\page doc_samples_asrun_manual asrun manual

asrun is a simple command-line tool that supports executing AngelScript files directly in order
to perform simple batch tasks. The API provided by the tool allow the script to interact with
the system to read and write files, and execute other system commands.

On Windows it can be associated, for example with the file extension .as, to allow scripts to be
executed directly from the file browser with a double click. This makes it a handy tool even without
a terminal for command-line input. On Linux and UNIX based systems the shebang interpreter directive
can be added as the first line on the script to make the script files executable.

\section doc_samples_asrun_usage Usage

asrun [-d] \

repo_name: Antidote/openrpgeditor

license: mit


code:
/**

\page doc_script_bnf Script language grammar

This is language grammar in Extended Backus-Naur Form (EBNF).

\note The Railroad Diagram Generator can be used to generate an online navigational railroad diagram.

SCRIPT        ::= (IMPORT | ENUM | TYPEDEF | CLASS | MIXIN | INTERFACE | FUNCDEF | VIRTPROP | VAR | FUNC | NAMESPACE | USING | ';')*
IMPORT        ::= 'import' TYPE '&'? IDENTIFIER PARAMLIST FUNCATTR 'from' STRING ';'
USING         ::= 'using' 'namespace' IDENTIFIER ('::' IDENTIFIER)* ';'
NAMESPACE     ::= 'namespace' IDENTIFIER ('::' IDENTIFIER)* '{' SCRIPT '}'
ENUM          ::= ('shared' | 'external')* 'enum' IDENTIFIER (';' | ('{' IDENTIFIER ('=' EXPR)? (',' IDENTIFIER ('=' EXPR)?)* '}'))
FUNCDEF       ::= ('external' | 'shared')* 'funcdef' TYPE '&'? IDENTIFIER PARAMLIST ';'
FUNC          ::= ('shared' | 'external')* ('private' | 'protected')? (((TYPE '&'?) | '~'))? IDENTIFIER PARAMLIST 'const'? FUNCATTR (';' | STATBLOCK)
VIRTPROP      ::= ('private' | 'protected')? TYPE '&'? IDENTIFIER '{' (('get' | 'set') 'const'? FUNCATTR (STATBLOCK | ';'))* '}'
INTERFACE     ::= ('external' | 'shared')* 'interface' IDENTIFIER (';' | ((':' IDENTIFIER (',' IDENTIFIER)*)? '{' (VIRTPROP | INTFMTHD)* '}'))
MIXIN         ::= 'mixin' CLASS
CLASS         ::= ('shared' | 'abstract' | 'final' | 'external')* 'class' IDENTIFIER (';' | ((':' IDENTIFIER (',' IDENTIFIER)*)? '{' (VIRTPROP | FUNC | VAR | FUNCDEF)* '}'))
VAR           ::= ('private'|'protected')? TYPE IDENTIFIER (( '=' (INITLIST | EXPR)) | ARGLIST)? (',' IDENTIFIER (( '=' (INITLIST | EXPR)) | ARGLIST)?)* ';'
TYPEDEF       ::= 'typedef' PRIMTYPE IDENTIFIER ';'
INTFMTHD      ::= TYPE '&'? IDENTIFIER PARAMLIST 'const'? ';'
STATBLOCK     ::= '{' (VAR | STATEMENT | USING)* '}'
PARAMLIST     ::= '(' ('void' | (TYPE TYPEMOD ('...' | IDENTIFIER? ('=' EXPR)?) (',' TYPE TYPEMOD ('...' | IDENTIFIER? ('=' EXPR)?))*))? ')'
TYPEMOD       ::= ('&' ('in' | 'out' | 'inout')?)?
TYPE          ::= 'const'? SCOPE DATATYPE TEMPLTYPELIST? ( ('[' ']') | ('@' 'const'?) )*
TEMPLTYPELIST ::= '<' TYPE (',' TYPE)* '>'
INITLIST      ::= '{' (ASSIGN | INITLIST)? (',' (ASSIGN | INITLIST)?)* '}'
SCOPE         ::= '::'? (IDENTIFIER '::')* (IDENTIFIER TEMPLTYPELIST? '::')?
DATATYPE      ::= (IDENTIFIER | PRIMTYPE | '?' | 'auto')
PRIMTYPE      ::= 'void' | 'int' | 'int8' | 'int16' | 'int32' | 'int64' | 'uint' | 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'float' | 'double' | 'bool'
FUNCATTR      ::= ('override' | 'final' | 'explicit' | 'property' | 'delete')*
STATEMENT     ::= (IF | FOR | FOREACH | WHILE | RETURN | STATBLOCK | BREAK | CONTINUE | DOWHILE | SWITCH | EXPRSTAT | TRY)
EXPRSTAT      ::= ASSIGN? ';'
SWITCH        ::= 'switch' '(' ASSIGN ')' '{' CASE* '}'
IF            ::= 'if' '(' ASSIGN ')' STATEMENT ('else' STATEMENT)?
TRY           ::= 'try' STATBLOCK 'catch' STATBLOCK
FOR           ::= 'for' '(' (VAR | EXPRSTAT) EXPRSTAT (ASSIGN (',' ASSIGN)*)? ')' STATEMENT
FOREACH       ::= 'foreach' '(' TYPE IDENTIFIER (',' TYPE INDENTIFIER)* ':' ASSIGN ')' STATEMENT
WHILE         ::= 'while' '(' ASSIGN ')' STATEMENT
DOWHILE       ::= 'do' STATEMENT 'while' '(' ASSIGN ')' ';'
RETURN        ::= 'return' ASSIGN? ';'
BREAK         ::= 'break' ';'
CONTINUE      ::= 'continue' ';'
EXPR          ::= EXPRTERM (EXPROP EXPRTERM)*
CASE          ::= (('case' EXPR) | 'default') ':' STATEMENT*
EXPRTERM      ::= ((TYPE '=')? INITLIST) | (EXPRPREOP* EXPRVALUE EXPRPOSTOP*)
EXPRVALUE     ::= 'void' | CONSTRUCTCALL | FUNCCALL | VARACCESS | CAST | LITERAL | '(' ASSIGN ')' | LAMBDA
CONSTRUCTCALL ::= TYPE ARGLIST
EXPRPREOP     ::= '-' | '+' | '!' | '++' | '--' | '~' | '@'
EXPRPOSTOP    ::= ('.' (FUNCCALL | IDENTIFIER)) | ('[' (IDENTIFIER ':')? ASSIGN (',' (IDENTIFIER ':')? ASSIGN)* ']') | ARGLIST | '++' | '--'
CAST          ::= 'cast' '<' TYPE '>' '(' ASSIGN ')'
LITERAL       ::= NUMBER | STRING | BITS | 'true' | 'false' | 'null'
LAMBDA        ::= 'function' '(' ((TYPE TYPEMOD)? IDENTIFIER? (',' (TYPE TYPEMOD)? IDENTIFIER?)*)? ')' STATBLOCK
FUNCCALL      ::= SCOPE IDENTIFIER TEMPLTYPELIST? ARGLIST
VARACCESS     ::= SCOPE IDENTIFIER
ARGLIST       ::= '(' (IDENTIFIER ':')? ASSIGN (',' (IDENTIFIER ':')? ASSIGN)* ')'
ASSIGN        ::= CONDITION ( ASSIGNOP ASSIGN )?
CONDITION     ::= EXPR ('?' ASSIGN ':' ASSIGN)?
EXPROP        ::= MATHOP | COMPOP | LOGICOP | BITOP
MATHOP        ::= '+' | '-' | '*' | '/' | '\%' | '**'
COMPOP        ::= '==' | '!=' | '<' | '<=' | '>' | '>=' | 'is' | '!is'
LOGICOP       ::= '&&' | '||' | '^^' | 'and' | 'or' | 'xor'
BITOP         ::= '&' | '|' | '^' | '<<' | '>>' | '>>>'
ASSIGNOP      ::= '=' | '+=' | '-=' | '*=' | '/=' | '|=' | '&=' | '^=' | '%=' | '**=' | '<<=' | '>>=' | '>>>='
IDENTIFIER    ::= [A-Za-z_][A-Za-z0-9_]*            // single token:  starts with letter or _, can include any letter and digit, same as in C++
NUMBER        ::= [0-9]+("."[0-9]+)?                // single token:  includes integers and real numbers, same as C++
STRING        ::= '"' ("\". | [^"#x0D#x0A\\])* '"'   // single token:  single quoted ', double quoted ", or heredoc multi-line string """
BITS          ::= '0'[bBoOdDxX][0-9A-Fa-f]+         // single token:  binary 0b or 0B, octal 0o or 0O, decimal 0d or 0D, hexadecimal 0x or 0X
COMMENT       ::= ('//'[^#x0A]*) | ('/*'[^*]*'*/')  // single token:  starts with // and ends with new line or starts with /* and ends with */
WHITESPACE    ::= [ #x09#x0A#x0D]+                  // single token:  spaces, tab, carriage return, line feed, and UTF8 byte-order-mark

*/


code:
/**

\page doc_script_class_desc Script class overview

With classes the script writer can declare new data types that hold groups
of properties and \ref doc_script_class_methods "methods" to manipulate them.

Script classes are reference types, which means that multiple references
or \ref doc_script_handle "handles" can be held for the same object instance.
The classes uses automatic memory management so the object instances are only
destroyed when the last reference to the instance is cleared.

  // The class declaration
  class MyClass
  {
    // A class method
    void DoSomething() {}

    // Class properties
    int a;
    int b;
  }

A class can implement specific methods to \ref doc_script_class_ops "overload operators".
This can simplify how the object instances are used in expressions, so that it is not
necessary to explicitly name each function, e.g. the opAdd method translates to the + operator.

Another useful feature is the ability to implement \ref doc_script_class_prop "property accessors",
which can be used either to provide virtual properties, i.e. that look like properties but really
aren't, or to implement specific routines that must be executed everytime a property is accessed.

A script class can also \ref doc_script_class_inheritance "inherit" from other classes, and
implement \ref doc_global_interface "interfaces".

\page doc_script_class_construct Class constructors

Class constructors are specific methods that will be used to create new instances
of the class. It is not required for a class to declare constructors, but doing
so may make it easier to use the class as it will not be necessary to first instantiate
the class and then manually set the properties.

The constructors are declared without a return type, and must have the same name as
the class itself. Multiple constructors with different parameter lists can be
implemented for different forms of initializations.

  class MyClass
  {
    // Implement a default constructor
    MyClass()
    {
    }

    // Implement the copy constructor
    MyClass(const MyClass &inout other)
    {
      // Copy the value of the other instance
    }

    // Implement other constructors with different parameter lists
    MyClass(int a, string b) {}
    MyClass(float x, float y, float z) {}

    // Implement conversion constructors
    // The second can only be used explicitly
    MyClass(int a) {}
    MyClass(string a) explicit {}
  }

The copy constructor is a specific constructor that the compiler can use to build
more performatic code when copies of an object must be made. Without the copy
constructor the compiler will be forced to first instantiate the copy using the
default constructor, and then copy the attributes with the
\ref doc_script_class_prop "opAssign" method.

A constructor that takes a single argument can be used in \ref conversion "type conversions".
By default the compiler can use these to perform the conversion implicitly when necessary.
If that is not desired, then it is possible to prohibit this by adding the <tt>explicit</tt>
decorator after the constructor.

One constructor cannot call another constructor. If you wish to share
implementations in the constructors you should use a specific method for that.

How the members shall be initialized can also be defined directly in the declaration of the
members. When this is done the initialization expression will automatically be compiled in the
constructor without the need to write the initialization again.

\see \ref doc_script_class_memberinit, \ref doc_script_class_conv

\section doc_script_class_construct_auto Auto-generated constructors

The compiler will automatically generate a default constructor and copy constructor in some cases.

The default constructor will be generated automatically if no other constructor is explicitly declared.
This constructor will simply call the default constructor for all object members and set all handles to null,
unless \ref doc_script_class_memberinit "members have explicit initializations" in which case those are executed.
Any compilation error in the member initialization will be reported as usual.

The copy constructor will be generated automatically if no copy constructor is explicitly declared. This
constructor will attempt to do a copy construct for each member, or if no copy constructor is available it
will first do a default construct followed by an assignment. If any compilation error is encountered, e.g. if a
member cannot be copied, then the copy constructor will not be generated and the error message surpressed.

If the auto generated constructors are not desired, then they can be explicitly excluded by flagging them as deleted.

  class MyClass
  {
	MyClass() delete;
	MyClass(const MyClass &inout) delete;
  }

\page doc_script_class_destruct Class destructor

It is normally not necessary to implement the class destructor as AngelScript
will by default free up any resources the objects holds when it is destroyed.
However, there may be situations where a more explicit cleanup routine must be
done as part of the destruction of the object.

The destructor is declared similarly to the constructor, except that it must be
prefixed with the ~ symbol (also known as the bitwise not operator).

  class MyClass
  {
    // Implement the destructor if explicit cleanup is needed
    ~MyClass()
    {
      // Perform explicit cleanup here
    }
  }

Observe that AngelScript uses automatic memory management with garbage collection
so it may not always be easy to predict when the destructor is executed. AngelScript will also
call the destructor only once, even if the object is resurrected by adding a
reference to it while executing the destructor.

It is not possible to directly invoke the destructor. If you need to be able to
directly invoke the cleanup, then you should implement a public method for that.

\page doc_script_class_methods Class methods

The class methods are implemented the same way as \ref doc_script_func "global functions",
with the addition that the class method can access the class instance properties either
directly or through the 'this' keyword in the case a local variable has the same name.

  // The class declaration
  class MyClass
  {
    // A class method
    void DoSomething()
    {
      // The class properties can be accessed directly
      a *= 2;

      // The declaration of a local variable may hide class properties
      int b = 42;

      // In this case the class property have to be accessed explicitly
      this.b = b;
    }

    // Class properties
    int a;
    int b;
  }

\section doc_script_class_const Const methods

Classes add a new type of \ref doc_script_func_overload "function overload", i.e. const overload.
When a class method is accessed through a read-only reference or handle, only methods that have
been marked as constant can be invoked. When the reference or handle is writable, then both types can be
invoked, with the preference being the non-const version in case both matches.

  class CMyClass
  {
    int method()       { a++; return a; }
    int method() const {      return a; }
    int a;
  }
  void Function()
  {
     CMyClass o;
     const CMyClass \@h = o;

     o.method(); // invokes the non-const version that increments the member a
     h.method(); // invokes the const version that doesn't increment the member a
  }

\page doc_script_class_inheritance Inheritance and polymorphism

AngelScript supports single inheritance, where a derived class inherits the
properties and methods of its base class. Multiple inheritance is not supported,
but polymorphism is supported by implementing \ref doc_global_interface "interfaces",
and code reuse is provided by including \ref doc_script_mixin "mixin classes".

All the class methods are virtual, so it is not necessary to specify this manually.
When a derived class overrides an implementation, it can extend
the original implementation by specifically calling the base class' method using the
scope resolution operator. When implementing the constructor for a derived class
the constructor for the base class is called using the super keyword.
If none of the base class' constructors is manually called, the compiler will
automatically insert a call to the default constructor in the beginning. The base class'
destructor will always be called after the derived class' destructor, so there is no
need to manually do this.

  // A derived class
  class MyDerived : MyBase
  {
    // The default constructor
    MyDerived()
    {
      // Calling the non-default constructor of the base class
      super(10);

      b = 0;
    }

    // Overloading a virtual method
    void DoSomething()
    {
      // Call the base class' implementation
      MyBase::DoSomething();

      // Do something more
      b = a;
    }

    int b;
  }

A class that is derived from another can be implicitly cast to the base class. The same works for
interfaces that are implemented by a class. The other direction requires an \ref conversion "explicit cast", as it
is not known at compile time if the cast is valid.

  class A {}
  class B : A {}
  void Foo()
  {
    A \@handle_to_A;
    B \@handle_to_B;

    \@handle_to_A = A(); // OK
    \@handle_to_A = B(); // OK. The reference will be implicitly cast to A@

    \@handle_to_B = A(); // Not OK. This will give a compilation error
    \@handle_to_B = B(); // OK

    \@handle_to_A = handle_to_B; // OK. The reference will be implicitly cast to A@
    \@handle_to_B = handle_to_A; // Not OK. This will give a compilation error

    \@handle_to_B = cast(handle_to_A); // OK. Though, the explicit cast will return null
                                         // if the object in handle_to_a is not really an
                                         // instance of B
  }

\section doc_script_class_inheritance_2 Extra control with final, abstract, and override

A class can be marked as 'final' to prevent the inheritance of it. This is an optional feature and
mostly used in larger projects where there are many classes and it may be difficult to manually
control the correct use of all classes. It is also possible to mark individual class methods of a
class as 'final', in which case it is still possible to inherit from the class, but the finalled
method cannot be overridden.

Another keyword that can be used to mark a class is 'abstract'. Abstract classes cannot be
instantiated, but they can be derived from. Abstract classes are most frequently used when you
want to create a family of classes by deriving from a common base class, but do not want the
base class to be instantiated by itself. It is currently not possible to mark methods as abstract
so all methods must have an implementation even for abstract classes.

  // A final class that cannot be inherited from
  final class MyFinal
  {
    MyFinal() {}
    void Method() {}
  }

  // A class with individual methods finalled
  class MyPartiallyFinal
  {
    // A final method that cannot be overridden
    void Method1() final {}

    // Normal method that can still be overridden by derived class
    void Method2() {}
  }

  // An abstract class
  abstract class MyAbstractBase {}

When deriving a class it is possible to tell the compiler that a method is meant to override a method in the
inherited base class. When this is done and there is no matching method in the base class the compiler will
emit an error, as it knows that something wasn't implemented quite the way it was meant. This is especially
useful to catch errors in large projects where a base class might be modified, but the derived classes was
forgotten.

  class MyBase
  {
    void Method() {}
    void Method(int) {}
  }

  class MyDerived : MyBase
  {
    void Method() override {}      // OK. The method is overriding a method in the base class
    void Method(float) override {} // Not OK. The method isn't overriding a method in base class
  }

\page doc_script_class_private Protected and private class members

Class members can be declared as protected or private to control where they can be
accessed from. Protected members cannot be accessed from outside the class. Private
members additionally cannot be accessed by derived classes.

This can be useful in large programs where you wish to avoid programmer errors where
properties or methods are inappropriately used.

  // A class with private members
  class MyBase
  {
    // The following are public members
    void PublicFunc()
    {
      // The class can access its own protected and private members
      ProtectedProp = 0; // OK
      ProtectedFunc();   // OK
      PrivateProp = 0;   // OK
      PrivateFunc();     // OK
    }

    int PublicProp;

    // The following are protected members
    protected void ProtectedFunc() {}
    protected int ProtectedProp;

    // The following are private members
    private void PrivateFunc() {}
    private int PrivateProp;
  }

  class MyDerived : MyBase
  {
    void Func()
    {
      // The derived class can access the protected members
      // of the base class but not the private members
      ProtectedProp = 1; // OK
      ProtectedFunc();   // OK
      PrivateProp = 1;   // Error
      PrivateFunc();     // Error
    }
  }

  void GlobalFunc()
  {
    MyBase obj;

    // Public members can be accessed normally
    obj.PublicProp = 0;  // OK
    obj.PublicFunc();    // OK

    // Accessing protected and private members will give a compiler error
    obj.ProtectedProp = 0; // Error
    obj.ProtectedFunc();   // Error
    obj.PrivateProp = 0;   // Error
    obj.PrivateFunc();     // Error
  }

\page doc_script_class_memberinit Initialization of class members

The order in which the class members are initialized during the construction of an object becomes
important when using inheritance, or when defining the initialization of the members directly in
the declaration. If a member is accessed before it has been initialized the script may cause a null
handle access exception, which will abort the execution of the script.

For a simple class, the order in which the members are initialized is the same as the order in which
they were declared. When explicit initializations are given in the declaration of the members, these
members will be initialized last.

  // The order of this class will be: a, c, b, d
  class Foo
  {
    string a;
    string b = a;
    string c;
    string d = b;
  }

When \ref doc_script_class_inheritance "inheritance" is used, the derived class' members without
explicit initialization will be initialized before the base class' members, and the members with
explicit initialization will be initialized after the base class' members.

  // The order of this class will be: a, b
  class Bar
  {
    string a;
    string b = a;
  }

  // The order of this class will be: d, a, b, c
  class Foo : Bar
  {
    string c = a;
    string d;
  }

This order of initialization has been chosen to avoid most problems with accessing members before they
have been initialized.

All members are initialized immediately in the beginning of the defined constructor, so the rest of the
code in the constructor can access members without worry. The exception is when the constructor explicitly
initializes a base class by calling super(), in this case the members with explicit initialization will
remain uninitialized until after the base class has been fully constructed.

\todo The above is no longer true. If constructor is explicitly assigning a value to a member it will be considered an initialization and will override the default initialization. explain order of initialization. including initialization of base type

  class Bar
  {
    Bar(string val) { a = val; }
    string a;
  }

  class Foo : Bar
  {
    Foo()
    {
      // b is already initialized here

      super(b); // a will be initialized in this call

      // c is initialized right after super() returns
    }

    string b;
    string c = a;
  }

Be wary about cases where a constructor or member initialization calls class methods. As class methods can
be overridden by derived classes it is possible for a base class to unwittingly access a member of the derived
class before it has been initialized.

  class Bar
  {
    Bar()
    {
      DoSomething();
    }

    void DoSomething() {}
  }

  // This class will cause a null handle exception, because the Bar's constructor calls
  // the DoSomething() method that accesses the member msg before it has been initialized.
  class Foo : Bar
  {
    string msg = 'hello';
    void DoSomething()
    {
      print(msg);
    }
  }

*/


code:
/**

\page doc_script_class_ops Operator overloads

It is possible to define what should be done when an operator is
used with a script class. While not necessary in most scripts it can
be useful to improve readability of the code.

This is called operator overloading, and is done by implementing
specific class methods. The compiler will recognize and use these
methods when it compiles expressions involving the overloaded operators
and the script class.

\section doc_script_class_unary_ops Prefixed unary operators

op	opfunc

-	             opNeg

~	             opCom

++	            opPreInc

\--	           opPreDec

When the expression <tt>op a</tt> is compiled, the compiler will rewrite it as <tt>a.opfunc()</tt> and compile that instead.

\section doc_script_class_unary2_ops Postfixed unary operators

op	opfunc

++	            opPostInc

\--	           opPostDec

When the expression <tt>a op</tt> is compiled, the compiler will rewrite it as <tt>a.opfunc()</tt> and compile that instead.

\section doc_script_class_cmp_ops Comparison operators

op	opfunc

==	            opEquals

!=	            opEquals

<	          opCmp

<=	         opCmp

>	          opCmp

>=	         opCmp

is	            opEquals

!is	           opEquals

The <tt>a == b</tt> expression will be rewritten as <tt>a.opEquals(b)</tt> and <tt>b.opEquals(a)</tt> and
then the best match will be used. <tt>!=</tt> is treated similarly, except that the result is negated. The
opEquals method must be implemented to return a <tt>bool</tt> in order to be considered by the compiler.

The comparison operators are rewritten as <tt>a.opCmp(b) op 0</tt> and <tt>0 op b.opCmp(a)</tt>
and then the best match is used. The opCmp method must be implemented to return a <tt>int</tt> in order to be
considered by the compiler. If the method argument is to be considered larger than the object then the method
should return a negative value. If they are supposed to be equal the return value should be 0.

If an equality check is made and the opEquals method is not available the compiler looks for the opCmp method
instead. So if the opCmp method is available it is really not necesary to implement the opEquals method, except
for optimization reasons.

The identity operator, <tt>is</tt>, expects opEquals to take a handle, <tt>\@</tt>, so the addresses can be
compared to be able to return if it is the same object, in contrast two different objects that have
the same value.

\section doc_script_class_assign_ops Assignment operators

op	opfunc

=	             opAssign

+=	            opAddAssign

-=	            opSubAssign

*=	            opMulAssign

/=	            opDivAssign

\%=	           opModAssign

**=	           opPowAssign

&=	        opAndAssign

|=	            opOrAssign

^=	            opXorAssign

<<=	     opShlAssign

>>=	     opShrAssign

>>>=	 opUShrAssign

The assignment expressions <tt>a op b</tt> are rewritten as <tt>a.opfunc(b)</tt> and then the
best matching method is used. An assignment operator can for example be implemented like this:

  obj &opAssign(const obj &inout other)
  {
    // Do the proper assignment
    ...

    // Return a handle to self, so that multiple assignments can be chained
    return this;
  }

\subsection doc_script_class_assign_ops_auto Auto-generated assignment operator

The compiler will automatically generate an opAssign to copy the content of an instance of the same type
in case no opAssign method with a single parameter is explicitly declared. The generated opAssign will simply copy each member.

If the auto generated opAssign is not desired, then it can be explicitly excluded by flagging it as deleted.

  class MyClass
  {
	MyClass &opAssign(const MyClass &inout) delete;
  }

\section doc_script_class_binary_ops Binary operators

op	opfunc	opfunc_r

+	             opAdd	        opAdd_r

-	             opSub	        opSub_r

*	             opMul	        opMul_r

/	             opDiv	        opDiv_r

%	             opMod	        opMod_r

**	            opPow	        opPow_r

&	         opAnd	        opAnd_r

|	             opOr	         opOr_r

^	             opXor	        opXor_r

<<	      opShl	        opShl_r

>>	      opShr	        opShr_r

>>>	  opUShr	       opUShr_r

The expressions with binary operators <tt>a op b</tt> will be rewritten as <tt>a.opfunc(b)</tt>
and <tt>b.opfunc_r(a)</tt> and then the best match will be used.

\section doc_script_class_index_op Index operators

op	opfunc

[]	             opIndex

When the expression <tt>a[i]</tt> is compiled, the compiler will rewrite it as <tt>a.opIndex(i)</tt> and compile that instead.
Multiple arguments between the brackets is also supported.

The index operator can also be formed similarly to \ref doc_script_class_prop "property accessors". The get accessor should then be
named <tt>get_opIndex</tt> and have one parameter for the indexing. The set accessor should be named <tt>set_opIndex</tt> and have two
parameters, the first is for the indexing, and the second for the new value.

  class MyObj
  {
    float get_opIndex(int idx) const property { return 0; }
    void set_opIndex(int idx, float value) property { }
  }

When the expression <tt>a[i]</tt> is used to retrieve the value, the compiler will rewrite it as <tt>a.get_opIndex(i)</tt>. When
the expression is used to set the value, the compiler will rewrite it as <tt>a.set_opIndex(i, expr)</tt>.

\section doc_script_class_call Functor operator

op	opfunc

()	                opCall

When the expression <tt>expr(arglist)</tt> is compiled and expr evaluates to an object, the compiler will rewrite it
as <tt>expr.opCall(arglist)</tt> and compile that instead.

\section doc_script_class_conv Type conversion operators

op	opfunc

type(expr)	constructor, opConv, opImplConv

cast<type>(expr)	opCast, opImplCast

When the expression <tt>type(expr)</tt> is compiled and type doesn't have a \ref doc_script_class_construct "conversion constructor" that take an argument with
the type of the expression, the compiler will try to rewrite it as <tt>expr.opConv()</tt>. The compiler will then chose
the opConv that returns the desired type.

For implicit conversions, the compiler will look for a conversion constructor of the target type that take a
matching argument, and isn't flagged as explicit. If it doesn't find one, it will try to call the
opImplConv on the source type that returns the target type.

  class MyObj
  {
    double myValue;

    // Allow MyObj to be implicitly created from double
    MyObj(double v)            { myValue = v; }

    // Allow MyObj to be implicitly converted to double
    double opImplConv() const  { return myValue; }

    // Allow MyObj to be created from int, but only explicitly
    MyObj(int v) explicit      { myValue = v; }

    // Allow MyObj to be converted to int, but only explicitly
    int opConv() const         { return int(myValue); }
  }

This should only be used for value conversions and not reference casts. That is, the methods are expected to return
a new instance of the value with the new type.

\note When compiling the boolean expressions in conditions the compiler will not use the <tt>bool opImplConv</tt> on
reference types even if the class method is implemented. This is because it is ambigous if it is the handle
that is verified or the actual object.

If a reference cast is desired, i.e. a different type of handle to the same object instance, then the opCast
method should be implemented instead. The compiler will attempt to rewrite an expression <tt>cast<type>(expr)</tt>
as <tt>expr.opCast()</tt>, and chose the opCast overload that returns a handle of the desired type. Here too the
opImplCast can be implemented instead if the reference cast is allowed to be performed implicitly by the compiler.

  class MyObjA
  {
    MyObjB \@objB;
    MyObjC \@objC;
    MyObjB \@opCast() { return objB; }
    MyObjC \@opImplCast() { return objC; }
    const MyObjB \@opCast() const { return objB; }
    const MyObjC \@opImplCast() const { return objC; }
  }

An example where the opCast/opImplCast operator overloads come in handy is when extending a type without directly
\ref doc_script_class_inheritance "inheriting" from it.

\see \ref conversion, \ref doc_adv_inheritappclass

\section doc_script_class_foreach_ops Foreach loop operators

\todo Document this. reference \ref while

*/


code:
/**

\page doc_script_class_prop Property accessors

\note The application can optionally \ref doc_adv_custom_options_lang_mod "turn off support for property accessors",
so you need to verify your application's manual to determine if this is supported for your application or not.

Many times when working with properties it is necessary to make sure specific logic is followed when
accessing them. An example would be to always send a notification when a property is modified, or computing
the value of the property from other properties. By implementing property accessor methods for the properties
this can be implemented by the class itself, making it easier for the one who accesses the properties.

In AngelScript property accessors are declared with the following syntax:

  class MyObj
  {
    // A virtual property with accessors
    int prop
    {
      get const
      {
        // The actual value of the property could be stored
        // somewhere else, or even computed at access time.
        return realProp;
      }
      set
      {
        // The new value is stored in a hidden parameter appropriately called 'value'.
        realProp = value;
      }
    }

    // The actual value can be stored in a member or elsewhere.
    // It is actually possible to use the same name for the real property, if so is desired.
    private int realProp;
  }

Behind the scene the compiler transforms this into two methods with the name of the property and the prefixes
<tt>get_</tt> and <tt>set_</tt>, and with the function decorator 'property'. The following generates the equivalent
code, and is perfectly valid too:

  class MyObj
  {
    int get_prop() const property { return realProp; }
    void set_prop(int value) property { realProp = value; }
    private int realProp;
  }

If you implement the property accessors by explicitly writing the two methods you must make sure the return type
of the get accessor and the parameter type of the set accessor match, otherwise the compiler will not know which
is the correct type to use.

For interfaces the first alternative is usually the preferred way of declaring the property accessors, as it
gets quite short and easy to read.

  interface IProp
  {
    int prop { get const; set; }
  }

You can also leave out either the get or set accessor. If you leave out the set accessor, then the
property will be read-only. If you leave out the get accessor, then the property will be write-only.

Property accessors can also be implemented for global properties, which follows the same rules, except the
functions are global.

When the property accessors have been declared it is possible to access them like ordinary properties,
and the compiler will automatically expand the expressions to the appropriate function calls, either
<tt>set_</tt> or <tt>get_</tt> depending on how the property is used in the expression.

  void Func()
  {
    MyObj obj;

    // Set the property value just like a normal property.
    // The compiler will convert this to a call to set_prop(10000).
    obj.prop = 10000;

    // Get the property value just a like a normal property.
    // The compiler will convert this to a call to get_prop().
    assert( obj.prop == 1000 );
  }

Observe that as property accessors are actually a pair of methods rather than direct access to the value,
some restrictions apply as to how they can be used in expressions that inspect and mutate in the same operation.
Compound assignments can be used on property accessors if the owning object is a reference type, but not if
the owning object is a value type. This is because the compiler must be able to guarantee that the object stays
alive between the two calls to the get accessor and set accessor.

The increment and decrement operators are currently not supported.

In such cases the expression must be expanded so that the read and write operation are performed separately,
e.g. the increment operator must be rewritten as follows:

  a++;     // will not work if a is a virtual property
  a += 1;  // this is OK, as long as the owner of the virtual
           // property is a reference type or the property is global

\section doc_script_class_prop_index Indexed property accessors

Property accessors can be used to emulate a single property or an array of properties accessed through the index
operator. Property accessors for indexed access work the same way as ordinary property accessors, except that they
take an index argument. The get accessor should take the index argument as the only argument, and the set accessor
should take the index argument as the first argument, and the new value as the second argument.

  string firstString;
  string secondString;

  // A global indexed get accessor
  string get_stringArray(int idx) property
  {
    switch( idx )
    {
    case 0: return firstString;
    case 1: return secondString;
    }
    return "";
  }

  // A global indexed set accessor
  void set_stringArray(int idx, const string &in value) property
  {
    switch( idx )
    {
    case 0: firstString = value; break;
    case 1: secondString = value; break;
    }
  }

  void main()
  {
    // Setting the value of the indexed properties
    stringArray[0] = "Hello";
    stringArray[1] = "World";

    // Reading the value of the indexed properties
    print(StringArray[0] + " " + stringArray[1] + "\n");
  }

Compound assignments currently doesn't work for indexed properties.

*/


code:
/**

\page doc_datatypes Data types

Note that the host application may add types specific to that application, refer to the application's manual for more information.

 - \subpage doc_datatypes_primitives
 - \subpage doc_datatypes_obj
 - \subpage doc_datatypes_funcptr
 - \subpage doc_datatypes_strings
 - \subpage doc_datatypes_auto

\see \ref doc_script_stdlib

\page doc_datatypes_primitives Primitives

\section void void

void is not really a data type, more like lack of data type. It can only be used to tell the compiler that a function doesn't return any data.

\section bool bool

bool is a boolean type with only two
possible values: true or
false. The keywords
true and
false are constants of type
bool that can be used as such in expressions.

\section int Integer numbers

type	min value	max value

int8  	                      -128	                       127

int16 	                   -32,768	                    32,767

int   	            -2,147,483,648	             2,147,483,647

int64 	-9,223,372,036,854,775,808	 9,223,372,036,854,775,807

uint8 	                         0	                       255

uint16	                         0	                    65,535

uint  	                         0	             4,294,967,295

uint64	                         0	18,446,744,073,709,551,615

As the scripting engine has been optimized for 32 bit datatypes, using the smaller variants is only recommended for accessing application specified variables. For local variables it is better to use the 32 bit variant.

int32 is an alias for int, and uint32 is an alias for uint.

\section real Real numbers

type	range of values	smallest positive value	 maximum digits

float 	 +/- 3.402823466e+38      	 1.175494351e-38      	 6

double	 +/- 1.79769313486231e+308	 2.22507385850720e-308	 15

\note These numbers assume the platform uses the IEEE 754 to represent floating point numbers in the CPU

Rounding errors may occur if more digits than the maximum number of digits are used.

Curiousity: Real numbers may also have the additional values of positive and negative 0 or
infinite, and NaN (Not-a-Number). For float NaN is represented by the 32 bit data word 0x7fc00000.

\page doc_datatypes_obj Objects and handles

\section objects Objects

There are two forms of objects, reference types and value types.

Value types behave much like the primitive types, in that they are allocated on the stack and deallocated
when the variable goes out of scope. Only the application can register these types, so you need to check
with the application's documentation for more information about the registered types.

Reference types are allocated on the memory heap, and may outlive the initial variable that allocates
them if another reference to the instance is kept. All \ref doc_script_class "script declared classes" are reference types.
\ref doc_global_interface "Interfaces" are a special form of reference types, that cannot be instantiated, but can be used to access
the objects that implement the interfaces without knowing exactly what type of object it is.

  obj o;      // An object is instantiated
  o = obj();  // A temporary instance is created whose
              // value is assigned to the variable

\section handles Object handles

Object handles are a special type that can be used to hold references to other objects. When calling methods or
accessing properties on a variable that is an object handle you will be accessing the actual object that the
handle references, just as if it was an alias. Note that unless initialized with the handle of an object, the
handle is null.

  obj o;
  obj@ a;           // a is initialized to null
  obj@ b = \@o;      // b holds a reference to o

  b.ModifyMe();     // The method modifies the original object

  if( a is null )   // Verify if the object points to an object
  {
    \@a = \@b;        // Make a hold a reference to the same object as b
  }

Not all types allow a handle to be taken. Neither of the primitive types can have handles, and there may exist some object types that do not allow handles. Which objects allow handles or not, are up to the application that registers them.

Object handle and array type modifiers can be combined to form handles to arrays, or arrays of handles, etc.

\see \ref doc_script_handle

\page doc_datatypes_funcptr Function handles

A function handle is a data type that can be dynamically set to point to a global function that has
a matching function signature as that defined by the variable declaration. Function handles are commonly
used for callbacks, i.e. where a piece of code must be able to call back to some code based on some
conditions, but the code that needs to be called is not known at compile time.

To use function handles it is first necessary to \ref doc_global_funcdef "define the function signature"
that will be used at the global scope or as a member of a class. Once that is done the variables can be
declared using that definition.

Here's an example that shows the syntax for using function handles

  // Define a function signature for the function handle
  funcdef bool CALLBACK(int, int);

  // An example function that shows how to use this
  void main()
  {
    // Declare a function handle, and set it
    // to point to the myCompare function.
    CALLBACK \@func = \@myCompare;

    // The function handle can be compared with the 'is' operator
    if( func is null )
    {
      print("The function handle is null\n");
      return;
    }

    // Call the function through the handle, just as if it was a normal function
    if( func(1, 2) )
    {
      print("The function returned true\n");
    }
    else
    {
      print("The function returned false\n");
    }
  }

  // This function matches the CALLBACK definition, since it has
  // the same return type and parameter types.
  bool myCompare(int a, int b)
  {
    return a > b;
  }

\section doc_datatypes_delegate Delegates

It is also possible to take function handles to class methods, but in this case the class method
must be bound to the object instance that will be used for the call. To do this binding is called
creating a delegate, and is done by performing a construct call for the declared function definition
passing the class method as the argument.

  class A
  {
    bool Cmp(int a, int b)
    {
       count++;
       return a > b;
    }
    int count = 0;
  }

  void main()
  {
    A a;

    // Create the delegate for the A::Cmp class method
    CALLBACK \@func = CALLBACK(a.Cmp);

    // Call the delegate normally as if it was a global function
    if( func(1,2) )
    {
      print("The function returned true\n");
    }
    else
    {
      print("The function returned false\n");
    }

    printf("The number of comparisons performed is "+a.count+"\n");
  }

\page doc_datatypes_strings Strings

\note Strings are only available in the scripts if the application \ref doc_addon_std_string "registers the support for them".
The syntax for using strings may differ for the application you're working with so consult the application's manual
for more details.

Strings hold an array of bytes or 16bit words depending on the application settings.
Normally they are used to store text but can really store any kind of binary data.

There are two types of string constants supported in the AngelScript
language, the normal quoted string, and the documentation strings,
called heredoc strings.

The normal strings are written between double quotation marks (\") or single quotation marks (').
Inside the constant strings some escape sequences can be used to write exact
byte values that might not be possible to write in your normal editor.

sequence
value
description

\\0
0
null character

\\\\
92
back-slash

\\'
39
single quotation mark (apostrophe)

\\\"
34
double quotation mark

\\n
10
new line feed

\\r
13
carriage return

\\t
9
tab character

\\xFFFF
0xFFFF
FFFF should be exchanged for a 1 to 4 digit hexadecimal number representing the value wanted. If the application uses 8bit strings then only values up to 255 is accepted.

\\uFFFF
0xFFFF
FFFF should be exchanged for the hexadecimal number representing the unicode code point

\\UFFFFFFFF
0xFFFFFFFF
FFFFFFFF should be exchanged for the hexadecimal number representing the unicode code point

  string str1 = "This is a string with \"escape sequences\" .";
  string str2 = 'If single quotes are used then double quotes can be included without "escape sequences".';

The heredoc strings are designed for inclusion of large portions of text
without processing of escape sequences. A heredoc string is surrounded by
triple double-quotation marks (\"\"\"), and can span multiple lines
of code. If the characters following the start of the string until the first
linebreak only contains white space, it is automatically removed by the
compiler. Likewise if the characters following the last line break until the
end of the string only contains white space this is also removed.

  string str = """
  This is some text without "escape sequences". This is some text.
  This is some text. This is some text. This is some text. This is
  some text. This is some text. This is some text. This is some
  text. This is some text. This is some text. This is some text.
  This is some text.
  """;

If more than one string constants are written in sequence with only whitespace or
comments between them the compiler will concatenate them into one constant.

  string str = "First line.\n"
               "Second line.\n"
               "Third line.\n";

The escape sequences \\u and \\U will add the specified unicode code point as a
UTF-8 or UTF-16 encoded sequence depending on the application settings. Only valid unicode 5.1
code points are accepted, i.e. code points between U+D800 and U+DFFF (reserved for surrogate pairs)
or above U+10FFFF are not accepted.

\see \ref doc_script_stdlib_string

\page doc_datatypes_auto Auto declarations

It is possible to use 'auto' as the data type of an assignment-style variable declaration.

The appropriate type for the variable(s) will be automatically determined.

  auto i = 18;         // i will be an integer
  auto f = 18 + 5.f;   // the type of f resolves to float
  auto o = getLongObjectTypeNameById(id); // avoids redundancy for long type names

Auto can be qualified with const to force a constant value:

  const auto i = 2;  // i will be typed as 'const int'

For types that support handles, auto will always become a handle as it is more efficient
than doing a value assignment. If the variable must not be a handle for some reason, then
do not use the 'auto' keyword.

  auto  a = getObject();  // auto is typed 'obj@'
  auto@ b = getObject();  // this is still allowed if you want to be more explicit

Auto handles can not be used to declare class members, since their resolution is dependent on the constructor.

*/


code:
/**

\page doc_expressions Expressions

 - \ref assignment
 - \ref function
 - \ref math
 - \ref bits
 - \ref compound
 - \ref logic
 - \ref equal
 - \ref relation
 - \ref identity
 - \ref increment
 - \ref opindex
 - \ref condition
 - \ref member
 - \ref handle
 - \ref parenthesis
 - \ref scope
 - \ref conversion
 - \ref anonobj

\section assignment Assignments

  lvalue = rvalue;

lvalue must be an expression that evaluates to a memory location where the
expression value can be stored, e.g. a variable. An assignment evaluates to
the same value and type of the data stored. The right hand expression is
always computed before the left.

\section function Function call

  func();
  func(arg);
  func(arg1, arg2);
  lvalue = func();

Functions are called to perform an action, and possibly return a value that can be used in further operations.
If a function takes more than one argument, the argument expressions are evaluated in the reverse order, i.e.
the last argument is evaluated first.

Some functions are declared with output reference parameters to return multiple values. When calling such
functions the output parameter must be given as an expression that can be assigned with the returned value. If
the additional output value won't be used use the special argument 'void' to tell the compiler that.

  // This function returns a value in the output parameter
  void func(int &out outputValue)
  {
    outputValue = 42;
  }

  // Call the function with a valid lvalue expression to receive the output value
  int value;
  func(value);

  // Call the function with 'void' argument to ignore the output value
  func(void);

Arguments can also be named and passed to a specific argument independent of the order the parameters were
declared in. No positional arguments may follow any named arguments.

  void func(int flagA = false, int flagB = false, int flagC = false) {}

  // Call the function, setting only a subset of its parameters
  func(flagC: true);
  func(flagB: true, flagA: true);

\todo Describe how to call a function template with explicit types

\section math Math operators

  c = -(a + b);

operator	description	left hand	right hand	result

+	 unary positive	     	          NUM	       NUM

-	 unary negative	     	          NUM	       NUM

+	 addition	          NUM	      NUM	       NUM

-	 subtraction	       NUM	      NUM	       NUM

*	 multiplication	    NUM	      NUM	       NUM

/	 division	          NUM	      NUM	       NUM

%	 modulos	           NUM	      NUM	       NUM

**	 exponent	         NUM	      NUM	       NUM

Plus and minus can be used as unary operators as well. NUM can be exchanged
for any numeric type, e.g. int or float. Both terms
of the dual operations will be implicitly converted to have the same type. The
result is always the same type as the original terms. One exception is unary
negative which is not available for uint.

\section bits Bitwise operators

  c = ~(a | b);

operator	          description	    left hand	right hand	result

~	           bitwise complement	     	          NUM	       NUM

&	           bitwise and	           NUM	      NUM	       NUM

|	           bitwise or	            NUM	      NUM	       NUM

^	           bitwise xor	           NUM	      NUM	       NUM

<<	    left shift	            NUM	      NUM	       NUM

>>	    right shift	           NUM	      NUM	       NUM

>>>	arithmetic right shift	NUM	      NUM	       NUM

All except ~ are dual operators.

Both operands will be converted to integers while keeping the sign of the original
type before the operation. The resulting type will be the same as the left hand operand.

\section compound Compound assignments

  lvalue += rvalue;
  lvalue = lvalue + rvalue;

A compound assignment is a combination of an operator followed by the assignment. The two expressions
above means practically the same thing. Except that first one is more efficient in that the lvalue is
only evaluated once, which can make a difference if the lvalue is complex expression in itself.

Available operators: += -= *= /= %= **= &= |= ^= <<= >>= >>>=

\section logic Logic operators

  if( a and b or not c )
  {
    // ... do something
  }

operator	 description	  left hand	 right hand	result

not	logical not	          	           bool	bool

and	logical and	         bool	bool	bool

or	 logical or	          bool	bool	bool

xor	logical exclusive or	bool	bool	bool

Boolean operators only evaluate necessary terms. For example in expression
a and b, b is only evaluated if a is
true.

Each of the logic operators can be written as symbols as well, i.e. ||
for or, && for and, ^^ for
xor, and ! for not.

\section equal Equality comparison operators

  if( a == b )
  {
    // ... do something
  }

The operators == and != are used to compare two values to determine if they are equal
or not equal, respectively. The result of this operation is always a boolean value.

\section relation Relational comparison operators

  if( a > b )
  {
    // ... do something
  }

The operators <, >, <=, and >= are used to compare two
values to determine their relationship. The result is always a boolean value.

\section identity Identity comparison operators

  if( a is null )
  {
    // ... do something
  }
  else if( a is b )
  {
    // ... do something
  }

The operators is and !is are used to compare the identity of two objects, i.e. to determine if
the two are the same object or not. These operators are only valid for reference types as they compare the address of two
objects. The result is always a boolean value.

\section increment Increment operators

  // The following means a = i; i = i + 1;
  a = i++;

  // The following means i = i - 1; b = i;
  b = --i;

These operators can be placed either before or after an lvalue to
increment/decrement its value either before or after the value
is used in the expression. The value is always incremented or decremented with 1.

\section opindex Indexing operator

  arr[i] = 1;

This operator is used to access an element contained within the object. Depending on the
object type, the expression between the [] needs to be of different types.

\section condition Conditional expression

  choose ? a : b;

If the value of choose is true then the expression returns a
otherwise it will return b.

Both a and b must be of the same type. If they are not, the compiler will
attempt an implicit conversion by following the principle of least cost, i.e. the expression that
will be converted is the one that cost less to convert. This cost is determined the same way as is
done for \ref doc_script_func_overload "matching arguments in function calls".

If the conversion doesn't work, or the conversion of either expression cost the same, then the compiler will give an error.

The conditional expression can be used as an lvalue, i.e. on the left value of an assignment expression,
if both a and b are lvalues of the same type.

  int a, b;
  (expr ? a : b) = 42;

\section member Member access

  object.property = 1;
  object.method();

object must be an expression resulting in a data type that have members. property
is the name of a member variable that can be read/set directly. method is the name of a member
method that can be called on the object.

\section handle Handle-of

  // Make handle reference the object instance
  \@handle = \@object;

  // Clear the handle and release the object it references
  \@handle = null;

Object handles are references to an object. More than one handle can reference the same object, and only
when no more handles reference an object is the object destroyed.

The members of the object that the handle references are accessed the same way through the handle as if
accessed directly through the object variable, i.e. with . operator.

\see \ref doc_script_handle

\section parenthesis Parenthesis

  a = c * (a + b);
  if( (a or b) and c )
  {
    // ... do something
  }

Parenthesis are used to group expressions when the \ref doc_operator_precedence "operator precedence" does
not give the desired order of evaluation.

\section scope Scope resolution

  int value;
  void function()
  {
    int value;       // local variable overloads the global variable
    \::value = value; // use scope resolution operator to refer to the global variable
  }

The scope resolution operator :: can be used to access variables or functions from another scope when
the name is overloaded by a local variable or function. Write the scope name on the left (or blank for the global scope)
and the name of the variable/function on the right.

\see \ref doc_global_namespace

\section conversion Type conversions

  // implicitly convert the clss handle to a intf handle
  intf \@a = \@clss();

  // explicitly convert the intf handle to a clss handle
  clss \@b = cast<clss>(a);

Object handles can be converted to other object handles with the cast operator.
If the cast is valid, i.e. the true object implements the class or interface being
requested, the operator returns a valid handle. If the cast is not valid, the cast
returns a null handle.

The above is called a reference cast, and only works for types that support object handles.
In this case the handle still refers to the same object, it is just exposed through a
different interface.

Types that do not support object handles can be converted with a value cast instead. In
this case a new value is constructed, or in case of objects a new instance of the object is
created.

  // implicit value cast
  int a = 1.0f;

  // explicit value cast
  float b = float(a)/2;

In most cases an explicit cast is not necessary for primitive types, however,
as the compiler is usually able to do an implicit cast to the correct type.

\section anonobj Anonymous objects

Anonymous objects, i.e. objects that are created without being declared as variables, can be instantiated in expressions
by calling invoking the object's constructor as if it was a function. Both reference types and value types can be created
like this.

  // Call the function with a new object of the type MyClass
  func(MyClass(1,2,3));

For types that support it, the anonymous objects can also be initialized with initialization lists.

  // Call the function with a dictionary, explicitly informing the type of the initialization list
  func(dictionary = {{'banana',1}, {'apple',2}, {'orange',3}});

  // When there is only one possible type that support initialization lists it is possible
  // to omit the type and let the compiler implicitly determine it based on the use
  funcExpectsAnArrayOfInts({1,2,3,4});

\todo describe instantiating templates as anonymous objects

*/