<library name="Core">
	<description>
		The core library exposes some basic built-in language functionality. 
		Unlike other libraries, the Core library does not need to be imported and is readily available from all files.
	</description>
	<namespace name="Core">
		<enum name="Type">
			<description>Enum representing the various types in Crayon.</description>
			<value name="NULL" description="null"/>
			<value name="BOOLEAN" description="booleans (true and false)"/>
			<value name="INTEGER" description="integers"/>
			<value name="FLOAT" description="floating point decimals"/>
			<value name="STRING" description="strings (text)"/>
			<value name="LIST" description="lists"/>
			<value name="DICTIONARY" description="dictionaries"/>
			<value name="OBJECT" description="object instances" />
			<value name="FUNCTION" description="function pointer" />
			<value name="CLASS" description="class reference"/>
		</enum>
		<function name="assert">
			<arg name="condition" type="bool" description="A boolean condition that must be true."/>
			<arg name="message" type="string" optional="true" description="An optional error message to show when the assertion condition is false."/>
			<description>Generates an exception if the condition is false.</description>
		</function>
		<function name="fail">
			<arg name="message" type="string" description="An error message to show in the exception."/>
			<description>Generates an exception when called.</description>
		</function>
		<function name="chr">
			<arg name="charCode" type="int" description="Unicode code point value."/>
			<returns type="string">A single character</returns>
			<description>Converts a character code value (as a unicode point value) into a single-character string.</description>
		</function>
		<function name="ord">
			<arg name="character" type="string" description="A single-character string"/>
			<returns type="int">The character code value (as a unicode point value).</returns>
			<description>Converts a character value into its numerical unicode point value. If the string passed in has multiple characters, the first character is used.</description>
		</function>
		<function name="currentTime">
			<returns type="float">The current time as a float</returns>
			<description>Returns the current unix time stamp as reported by the local machine. The unix time stamp is the number of seconds since midnight January 1st, 1970.</description>
		</function>
		<function name="parseFloat">
			<arg name="value" type="string" description="A floating point number as a string."/>
			<returns type="float">The numerical value of the text or null if there's an error.</returns>
			<description>
				Converts a decimal (or integer) string into its actual numeric value. 
				If the number depicted is an integer, the return value will still be a float (see parseInt).
				Surrounding whitespace is ignored.
				If the string does not depict a number, null is returned instead.
			</description>
		</function>
		<function name="parseInt">
			<arg name="value" type="string" description="An integer as a string."/>
			<returns type="int">The integer value of the text as an integer type.</returns>
			<description>
				Converts an integer as a text string into the actual integer type.
				Surrounding whitespace is ignored.
				If the string does not depict an integer, null is returned.
				If the string is a floating point decimal, null is also returned (see parseFloat).
			</description>
		</function>
		<function name="print">
			<arg name="value" type="any" description="Item or message to display in standard output"/>
			<description>
				Shows a message or value in the standard output. Standard output is generally in the same window
				as the command line for platforms that support this, however, the actual output may appear elsewhere
				depending on the platform (for example, the JavaScript console, or the Android Log).
			</description>
		</function>
		<function name="sleep">
			<arg name="delay" type="float" description="Number of seconds to pause execution"/>
			<description>
				Pauses execution for some number of seconds. NOTE: for JavaScript-exported platforms, the underlying
				implementation uses a setTimeout rather than blocking the browser thread, so this is still safe to use
				in JavaScript without causing the browser to become unresponsive.
			</description>
		</function>
		<function name="typeof">
			<arg name="value" type="any" description="Any value"/>
			<returns type="Core.Type" description="A type"/>
			<description>
				Determines which type the given value is.
			</description>
		</function>

		<function name="isString">
			<arg name="value" type="any" description="Any value"/>
			<returns type="bool" description="True if the value is a string"/>
			<description>
				Returns true if the given value is a string. This is semantically identical to typeof(value) == Core.Types.STRING.
			</description>
		</function>

		<function name="isNumber">
			<arg name="value" type="any" description="Any value"/>
			<returns type="bool" description="True if the value is an integer or a float"/>
			<description>
				Returns true if the given value is one of the numeric types (integer or float). 
				This is semantically identical to typeof(value) == Core.Types.INTEGER || typeof(value) == Core.Types.FLOAT.
			</description>
		</function>

		<class name="Exception">
			<description>The root class of all exceptions.</description>
			<field name="message" type="string" description="Error message of the exception"/>
			<field name="cause" type="Core.Exception" description="A wrapped exception that caused this exception to occur."/>
			<function name="(constructor)">
				<arg name="message" type="string" optional="true" description="Message to show in the exception"/>
				<arg name="cause" type="Core.Exception" optional="true" description="Another exception"/>
				<description>
					Instantiates a new exception. Optionally allows for setting a message and also another exception
					that caused this exception.
				</description>
			</function>
			<function name="getTrace">
				<description>Returns a stack trace of where the exception was thrown.</description>
				<returns type="list-of-string" description="The stack trace of this exception."/>
			</function>
		</class>

		<class name="FatalException" parent="Core.Exception">
			<description>
				An exception that cannot be caught. 
				This is generated by the VM in situations where it cannot recover, such as stack overflows.
			</description>
		</class>

		<class name="AssertionFailedException" parent="Core.Exception">
			<description>Exception thrown by Core.assert() and Core.fail()</description>
		</class>

		<class name="DivisionByZeroException" parent="Core.Exception">
			<description>Generated when you divide or mod by 0.</description>
		</class>

		<class name="IndexOutOfRangeException" parent="Core.Exception">
			<description>Generated when you access an index in a list outside of its bounds.</description>
		</class>

		<class name="InvalidArgumentException" parent="Core.Exception">
			<description>
				General exception used when an argument to a function is wrong. 
				The message field should contain specific information.
			</description>
		</class>

		<class name="InvalidAssignmentException" parent="Core.Exception">
			<description>
				Exception generated when you assign a value to an invalid target. For example,
				attempting to assign a value to a field that is already occupied by a function defined in code.
			</description>
		</class>

		<class name="InvalidInvocationException" parent="Core.Exception">
			<description>Generated when you attempt to invoke a non-function value like a function.</description>
		</class>

		<class name="InvalidKeyException" parent="Core.Exception">
			<description>Generated when you attempt to use a value for a dictionary key that is not an integer, object, or string.</description>
		</class>

		<class name="InvalidOperationException" parent="Core.Exception">
			<description>
				General-purpose exception for when something has been invoked incorrectly. 
				The message should contain specific information.
			</description>
		</class>

		<class name="KeyNotFoundException" parent="Core.Exception">
			<description>Generated when you attempt to access a key in a dictionary that does not exist.</description>
		</class>

		<class name="NotImplementedException" parent="Core.Exception">
			<description>Useful exception to throw for when you want to mark a function as not having been implemented.</description>
		</class>

		<class name="NullReferenceException" parent="Core.Exception">
			<description>Thrown when null is accessed as though it is a non-null value.</description>
		</class>

		<class name="UnassignedVariableException" parent="Core.Exception">
			<description>Occurs when a variable is used before it has any value assigned to it.</description>
		</class>

		<class name="UnknownFieldException" parent="Core.Exception">
			<description>Occurs when you access a field on a value that does not exist.</description>
		</class>

		<class name="UnsupportedOperationException" parent="Core.Exception">
			<description>
				General purpose exception for when you attempt to use code in a way that it was not designed to support.
				Also thrown when you perform operations on types that do not have that combination of operations defined.
				For example, subtracting a list from a string.
			</description>
		</class>
	</namespace>

	<namespace name="Core.Reflection">
		<function name="getClassFromInstance">
			<arg name="instance" type="object" description="Any instance of an object."/>
			<returns type="class" description="The class of the object."/>
			<description>
				Gets a reference to the class of the given object.
			</description>
		</function>

		<function name="getClasses">
			<arg name="commonBaseClass" type="class" optional="true" description="filters results to only classes that extend from this class"/>
			<returns type="list-of-class" description="A list of class references"/>
			<description>
				Gets a list of all class types in the project.
				Optionally, you can pass a filter argument to limit results down to only classes that implement that base class.
			</description>
		</function>

		<function name="getMethods">
			<arg name="instanceOrClass" type="object|class" description="instance or class to get methods from."/>
			<returns type="list-of-function" description="A list of function pointers."/>
			<description>
				Gets a list of methods on an instance or class. 
				For instances, only instance methods are returned.
				For classes, only static methods are returned.
			</description>
		</function>
	</namespace>
</library>
