.. index:: 
	single: Language Specification; Introduction

======================
Language Specification
======================

In this chapter we will learn about

* Language keywords
* Language Functions
* Compiler Errors
* Runtime Errors
* Environment Errors
* Language Grammar
* Virtual Machine (VM) Instructions

.. index:: 
	pair: Language Specification; Language Keywords

Language Keywords
=================

Keywords Count : 49

* again
* and
* but
* bye
* call
* case
* catch
* changeringkeyword
* changeringoperator
* class
* def
* do
* done
* else
* elseif
* end
* exit
* for
* from
* func
* get
* give
* if
* import
* in
* load
* loadsyntax
* loop
* new
* next
* not
* off
* ok
* on
* or
* other
* package
* private
* put
* return
* see
* step
* switch
* to
* try
* while
* endfunc
* endclass
* endpackage

.. index:: 
	pair: Language Specification; Language Functions

Language Functions
==================

Functions Count : 238

.. code-block:: ring

        acos()
        add()
        addattribute()
        adddays()
        addmethod()
        addsublistsbyfastcopy()
        addsublistsbymove()
        ascii()
        asin()
        assert()
        atan()
        atan2()
        attributes()
        binarysearch()
        bytes2double()
        bytes2float()
        bytes2int()
        callgarbagecollector()
        callgc()
        ceil()
        cfunctions()
        char()
        chdir()
        checkoverflow()
        classes()
        classname()
        clearerr()
        clock()
        clockspersecond()
        closelib()
        copy()
        cos()
        cosh()
        currentdir()
        date()
        dec()
        decimals()
        del()
        diffdays()
        dir()
        direxists()
        double2bytes()
        eval()
        exefilename()
        exefolder()
        exp()
        fabs()
        fclose()
        feof()
        ferror()
        fexists()
        fflush()
        fgetc()
        fgetpos()
        fgets()
        filename()
        find()
        float2bytes()
        floor()
        fopen()
        fputc()
        fputs()
        fread()
        freopen()
        fseek()
        fsetpos()
        ftell()
        functions()
        fwrite()
        getarch()
        getattribute()
        getchar()
        getpathtype()
        getpointer()
        getptr()
        globals()
        hex()
        hex2str()
        input()
        insert()
        int2bytes()
        intvalue()
        isalnum()
        isalpha()
        isandroid()
        isattribute()
        iscfunction()
        isclass()
        iscntrl()
        isdigit()
        isfreebsd()
        isfunction()
        isglobal()
        isgraph()
        islinux()
        islist()
        islocal()
        islower()
        ismacosx()
        ismethod()
        ismsdos()
        isnull()
        isnumber()
        isobject()
        ispackage()
        ispackageclass()
        ispointer()
        isprint()
        isprivateattribute()
        isprivatemethod()
        ispunct()
        isspace()
        isstring()
        isunix()
        isupper()
        iswindows()
        iswindows64()
        isxdigit()
        left()
        len()
        lines()
        list()
        list2str()
        loadlib()
        locals()
        log()
        log10()
        lower()
        max()
        memcpy()
        memorycopy()
        mergemethods()
        methods()
        min()
        murmur3hash()
        newlist()
        nofprocessors()
        nullpointer()
        nullptr()
        number()
        obj2ptr()
        object2pointer()
        objectid()
        packageclasses()
        packagename()
        packages()
        perror()
        pointer2object()
        pointer2string()
        pointercompare()
        pow()
        prevfilename()
        ptr2obj()
        ptr2str()
        ptrcmp()
        raise()
        random()
        randomize()
        read()
        remove()
        rename()
        reverse()
        rewind()
        right()
        ring_give()
        ring_see()
        ring_state_delete()
        ring_state_filetokens()
        ring_state_findvar()
        ring_state_init()
        ring_state_main()
        ring_state_mainfile()
        ring_state_new()
        ring_state_newvar()
        ring_state_runcode()
        ring_state_runfile()
        ring_state_runobjectfile()
        ring_state_scannererror()
        ring_state_setvar()
        ring_state_stringtokens()
        ringvm_callfunc()
        ringvm_calllist()
        ringvm_cfunctionslist()
        ringvm_classeslist()
        ringvm_evalinscope()
        ringvm_fileslist()
        ringvm_functionslist()
        ringvm_genarray()
        ringvm_give()
        ringvm_hideerrormsg()
        ringvm_info()
        ringvm_memorylist()
        ringvm_packageslist()
        ringvm_passerror()
        ringvm_scopescount()
        ringvm_see()
        ringvm_settrace()
        ringvm_tracedata()
        ringvm_traceevent()
        ringvm_tracefunc()
        setattribute()
        setpointer()
        setptr()
        shutdown()
        sin()
        sinh()
        sort()
        space()
        sqrt()
        srandom()
        str2hex()
        str2hexcstyle()
        str2list()
        strcmp()
        string()
        substr()
        swap()
        sysget()
        sysset()
        system()
        sysunset()
        tan()
        tanh()
        tempfile()
        tempname()
        time()
        timelist()
        trim()
        type()
        ungetc()
        unsigned()
        upper()
        uptime()
        variablepointer()
        varptr()
        version()
        windowsnl()
        write()
	
.. index:: 
	pair: Language Specification; Compiler Errors

Compiler Errors
===============

* Error (C1)  : Error in parameters list, expected identifier
* Error (C2)  : Error in class name
* Error (C3)  : Unclosed control structure, 'ok' is missing
* Error (C4)  : Unclosed control structure, 'end' is missing
* Error (C5)  : Unclosed control structure, next is missing
* Error (C6)  : Error in function name
* Error (C7)  : Error in list items
* Error (C8)  : Parentheses ')' is missing 
* Error (C9)  : Brackets ']' is missing 
* Error (C10) : Error in parent class name
* Error (C11) : Error in expression operator
* Error (C12) : No class definition
* Error (C13) : Error in variable name
* Error (C14) : Try/Catch miss the Catch keyword!
* Error (C15) : Try/Catch miss the Done keyword!
* Error (C16) : Error in Switch statement expression!
* Error (C17) : Switch statement without OFF
* Error (C18) : Missing closing brace for the block opened!
* Error (C19) : Numeric Overflow!
* Error (C20) : Error in package name
* Error (C21) : Unclosed control structure, 'again' is missing
* Error (C22) : Function redefinition, function is already defined!
* Error (C23) : Using '(' after number!
* Error (C24) : The parent class name is identical to the subclass name
* Error (C25) : Trying to access the self reference after the object name
* Error (C26) : Class redefinition, class is already defined!

* Error (S1) : Literal not closed!

* Warning (W1) : Duplication in file name
* Warning (W2) : The Compiler command ChangeRingKeyword requires two words as parameters
* Warning (W3) : Compiler command ChangeRingKeyword - Keyword not found !
* Warning (W4) : The Compiler command  ChangeRingOperator requires two words as parameters
* Warning (W5) : Compiler command ChangeRingOperator - Operator not found !
* Warning (W6) : Using the EXIT command outside loop!"
* Warning (W7) : Using the LOOP command outside loop!"

.. index:: 
	pair: Language Specification; Runtime Errors

Runtime Errors
==============

* Error (R1)  : Can't divide by zero !
* Error (R2)  : Array Access (Index out of range) !
* Error (R3)  : Calling Function without definition !
* Error (R4)  : Stack Overflow !
* Error (R5)  : Can't access the list item, Object is not list !
* Error (R6)  : Variable is required
* Error (R7)  : Can't assign to a string letter more than one character
* Error (R8)  : Variable is not a string 
* Error (R9)  : Using exit command outside loops 
* Error (R10) : Using exit command with number outside the range 
* Error (R11) : Error in class name, class not found! 
* Error (R12) : Error in property name, property not found! 
* Error (R13) : Object is required
* Error (R14) : Calling Method without definition !
* Error (R15) : Error in parent class name, class not found! 
* Error (R16) : Using braces to access unknown object ! 
* Error (R17) : Error, using 'Super' without parent class! 
* Error (R18) : Numeric Overflow! 
* Error (R19) : Calling function with less number of parameters!
* Error (R20) : Calling function with extra number of parameters!
* Error (R21) : Using operator with values of incorrect type
* Error (R22) : Using loop command outside loops 
* Error (R23) : Using loop command with number outside the range 
* Error (R24) : Using uninitialized variable 
* Error (R25) : Error in package name, Package not found! 
* Error (R26) : Calling private method from outside the class 
* Error (R27) : Using private attribute from outside the class 
* Error (R28) : Using bad data type as step value
* Error (R29) : Using bad data type in for loop
* Error (R30) : Parent class name is identical to child class name 
* Error (R31) : Trying to destroy the object using the self reference 
* Error (R32) : The CALL command expect a variable contains string!
* Error (R33) : Bad decimals number (correct range >= 0 and <= 90)
* Error (R34) : Variable is required for the assignment operation
* Error (R35) : Can't create/open the file!
* Error (R36) : The column number is not correct! It's greater than the number of columns in the list
* Error (R37) : Sorry, The command is not supported in this context
* Error (R38) : Runtime Error in loading the dynamic library!
* Error (R39) : Error occurred creating unique filename
* Error (R40) : Numeric underflow!
* Error (R41) : Invalid numeric string

.. index:: 
	pair: Language Specification; Environment Errors

Environment Errors
==================

* Error (E1) : Caught SegFault
* Error (E2) : Out of Memory
* Error (E3) : Deleting scope while no scope!
* Error (E4) : Long VM Instruction!
* Error (E5) : The file type is not correct - the VM expect a ring object file
* Error (E6) : The Ring Object File version is not correct!
* Error (E7) : Internal error in using sscanf() function!
* Error (E8) : Internal error in using fscanf() function!

.. index:: 
	pair: Language Specification; Language Grammar

Language Grammar
================

Program ---> {statement}

Statement ---> 'package' <Identifier> { '.' <Identifier> } ['{' {statement} '}'] ['end'|'endpackage']

Statement ---> 'class' <Identifier> [ 'from'|':'|'<' <Identifier> ] ['{' {statement} '}']['end'|'endclass']

Statement ---> 'func'|'def' <Identifier> [ParaList] ['{' {statement} '}']['end'|'endfunc']

Statement ---> 'import' <Identifier> { '.' <Identifier> }

Statement ---> 'private'

Statement ---> 'load' ['package'|'again'] <Literal>

Statement ---> 'loadsyntax' <Literal>

Statement ---> 'changeringkeyword' <OldKeyword> <NewKeyword>

Statement ---> 'changeringoperator' <OldOperator> <NewOperator>

Statement ---> 'see'|'put' <Expr>

Statement ---> 'give'|'get' <Identifier>

Statement ---> 'if' <Expr> ['{'] {statement} [ {'but'|'elseif' <Expr> {Statement} } ] ['else' {Statement} ] 'ok'|'end'|'}'

Statement ---> 'Switch' <Expr> ['{'] { 'on'|'case' <Expr> {statement} } ['other' {Statement} ]  'off'|'end'|'}'

Statement ---> 'for' <Identifier> '=' <Expr> 'to' <Expr> [ 'step' <Expr> ] ['{'] {Statement} 'next'|'end'|'}'

Statement ---> 'for' <Identifier> 'in' <Expr>  [ 'step' <Expr> ] ['{'] {statement} 'next'|'end'|'}'

Statement ---> 'while' <Expr> ['{'] {statement} 'end'|'}'

Statement ---> 'do' {statement} 'again' <Expr> 

Statement ---> 'try' {statement} ['{'] 'catch' {statement} 'done'|'end'|'}'

Statement ---> 'return' <Expr>

Statement ---> 'bye'

Statement ---> 'exit'

Statement ---> 'loop'

Statement ---> <Expr>

Statement ---> epslion

ParaList ---> epslion

ParaList ---> ['('] <Identifier> [{ ',' <Identifier> }] [')']

Expr ---> <LogicNot> [{ 'and'|'or' <LogicNot> }]

LogicNot --> ['not'] <EqualOrNot> 

EqualOrNot --> [ '='|'!=' ] <Compare>

Compare ---> <BitOrXor> [ { '<' | '>' | '<=' | '>=' <BitOrXor> } ]

BitOrXor ---> <BitAnd> [ { '|' | '^' <BitAnd> } ]

BitAnd ---> <BitShift> [ { '&' <BitShift> } ]

BitShift ---> <Arithmetic> [ { '<<' | '>>' <Arithmetic> } ]

Arithmetic ---> <Term> [ { '+' | '-'  <Term>  } ]

Term ---> <Range> [ { '*' | '/' | '%' <Range> } ]

Range ---> <Factor> [ ':' <Factor> ]

Factor ---> <Identifier> [ {Mixer} ] [ '=' <Expr> ]

Factor ---> <Number>

Factor ---> <Literal>

Factor ---> ':' <Identifier>

Factor ---> '-' <Factor>

Factor ---> '(' <Expr> ')'

Factor ---> <List>

Factor ---> 'new' <Identifier>

Factor ---> <AnonymousFunction>

Factor ---> 'call' <identifier> { '.' <Identifier> } '(' <Parameters> ')'

List ---> '[' [ <Expr> { ',' <Expr> } ] ']'

Mixer ---> { '.' <Identifier> }

Mixer ---> '[' <Expr> ']'

Mixer ---> '(' [ <Expr> [ { ',' <Expr> }] ]  ')'

Mixer ---> '{' {Statement} '}'

AnonymousFunction ---> 'func'|'def'| [<ParaList>] '{' {Statement} '}'

.. index:: 
	pair: Language Specification; Virtual Machine Instructions

Virtual Machine (VM) Instructions
=================================

Definitions :-

* VM : Virtual Machine
* Stack : VM Stack
* IR : Instruction Register
* PC : Program Counter
* VP : Variable Pointer
* Stack[nSize] : Last Item in the Stack (Last In - First Out)
* VV : Variable Value (We have a Pointer to a variable, And we access this variable value)
(Stack and Variables)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_PUSHC 		Add string from the IR to the stack
ICO_PUSHN 		Add number from the IR to the stack
ICO_PUSHV 		Replace VP in the stack[nSize] with the variable value 
ICO_LOADADDRESS 	Read variable name from the IR, push VP to the stack
ICO_ASSIGNMENT		Stack[nSize-1] VV = Stack[nSize] VV , POP Stack[nSize]
ICO_INC 		Increment Number in Stack[nSize] by 1
ICO_LOADAPUSHV		The same as ICO_LOADADDRESS then ICO_PUSHV
ICO_NEWLINE		Store new line number (debug info)
ICO_FREESTACK		Remove all items from the stack , nSize = 0
ICO_FILENAME		Store the source code file name (debug info)
ICO_FREELOADASCOPE	Free the Scope List of the current Expression
=======================	============================================================================

(Jump)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_JUMP		Set PC to new value from the IR 
ICO_JUMPZERO		If Stack[nSize] is a number = 0 then Set PC to new value from the IR 
ICO_JUMPFOR		End of for loop
ICO_JUMPONE		If Stack[nSize] is a number = 1 then Set PC to new value from the IR 
ICO_JUMPZERO2		As ICO_JUMPZERO but add 1 to the stack (required for many 'AND' conditions)
ICO_JUMPONE2		As ICO_JUMPONE but add 1 to the stack (required for many 'OR' conditions)
=======================	============================================================================

(Compare)

=======================	==========================================================================================================
Operation			Description
=======================	==========================================================================================================
ICO_LESSEQUAL		If stack[nSize-1] <= stack[nSize] , POP stack[nSize], set Stack[nSize-1] = 1 else set Stack[nSize-1] = 0
ICO_EQUAL		If stack[nSize-1] = stack[nSize] , POP stack[nSize], set Stack[nSize-1] = 1 else set Stack[nSize-1] = 0
ICO_LESS		If stack[nSize-1] < stack[nSize] , POP stack[nSize], set Stack[nSize-1] = 1 else set Stack[nSize-1] = 0
ICO_GREATER		If stack[nSize-1] > stack[nSize] , POP stack[nSize], set Stack[nSize-1] = 1 else set Stack[nSize-1] = 0
ICO_GREATEREQUAL	If stack[nSize-1] >= stack[nSize] , POP stack[nSize], set Stack[nSize-1] = 1 else set Stack[nSize-1] = 0
ICO_NOTEQUAL		If stack[nSize-1] != stack[nSize] , POP stack[nSize], set Stack[nSize-1] = 1 else set Stack[nSize-1] = 0
=======================	==========================================================================================================

(Math)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_SUM			Stack[nSize-1] = Stack[nSize-1] + Stack[nSize] , POP stack[nSize]
ICO_SUB			Stack[nSize-1] = Stack[nSize-1] - Stack[nSize] , POP stack[nSize]
ICO_MUL			Stack[nSize-1] = Stack[nSize-1] * Stack[nSize] , POP stack[nSize]
ICO_DIV			Stack[nSize-1] = Stack[nSize-1] / Stack[nSize] , POP stack[nSize]
ICO_MOD			Stack[nSize-1] = Stack[nSize-1] % Stack[nSize] , POP stack[nSize]
ICO_NEG			Stack[nSize] = - Stack[nSize-1]
ICO_PLUSPLUS		Stack[nSize] = Stack[nSize] + 1
ICO_MINUSMINUS		Stack[nSize] = Stack[nSize] - 1
=======================	============================================================================

(Logic)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_AND			Stack[nSize-1] = Stack[nSize-1] && Stack[nSize] , POP stack[nSize]
ICO_OR			Stack[nSize-1] = Stack[nSize-1] || Stack[nSize] , POP stack[nSize]
ICO_NOT			Stack[nSize]   = ! Stack[nSize]  
=======================	============================================================================

(Lists)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_LISTSTART		Start New List in Temp. Memory
ICO_LISTITEM		Add List Item
ICO_LISTEND		End List
ICO_LOADINDEXADDRESS	Stack[nSize-1] = Stack[nSize-1] VV [ Stack[nSize] ] , POP stack[nSize]
=======================	============================================================================

(Functions)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_LOADFUNC		Find function
ICO_CALL		Call function
ICO_RETURN		Return from function
ICO_RETNULL		Return NULL from function
ICO_RETFROMEVAL		Return after eval() 
ICO_RETITEMREF		Return the list item reference - not the value
ICO_NEWFUNC		Start new function
ICO_BLOCKFLAG		Flag to determine where to jump later (after ICO_RETURN)
ICO_FUNCEXE		Start executing function
ICO_ENDFUNCEXE		End function execution
ICO_ANONYMOUS		Anonymous function
ICO_FREETEMPLISTS	Delete temp. lists
=======================	============================================================================

(User Interface)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_PRINT		Print value to the standard output
ICO_GIVE		Get input from the keyboard
=======================	============================================================================

(End Program/Loop)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_BYE			End execution of VM
ICO_EXITMARK		Place to exit to from a loop	
ICO_POPEXITMARK		Remove exit mark
ICO_EXIT		Break from one loop or more 
ICO_LOOP		Continue to next loop 
=======================	============================================================================

(For Better Performance)

========================	============================================================================
Operation			Description
========================	============================================================================
ICO_PUSHP			Push pointer to the stack
ICO_INCP			Increment variable value using pointer
ICO_PUSHPV			Push value of variable using variable pointer
ICO_INCJUMP			Increment then jump
ICO_INCPJUMP			Increment using pointer then jump
ICO_JUMPVARLENUM		Jump if variable value is <= numeric value
ICO_JUMPVARPLENUM		Jump if variable value (using pointer) <= numeric value 
ICO_LOADFUNCP			Push function pointer
ICO_PUSHPLOCAL			Push pointer to local variable
ICO_INCLPJUMP			Increment value using pointer to local variable then jump
ICO_JUMPVARLPLENUM		Jump if the variable value (using pointer) <= numeric value
ICO_INCPJUMPSTEP1	 	Increment value using variable pointer then jump (for loop step = 1)
ICO_JUMPVARPLENUMSTEP1		Increment value using variable pointer then jump (for loop step = 1)
========================	============================================================================

(Try-Catch-Done)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_TRY			Start try region
ICO_DONE		End try region
=======================	============================================================================

(Duplicate and Range)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_DUPLICATE		Duplicate stack value
ICO_RANGE		Create list from value to value
=======================	============================================================================

(OOP)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_NEWOBJ		Create new object, get class name from the IR, push object pointer to the stack.
ICO_SETSCOPE		Called after creating new object, set the active scope to be the object scope.
ICO_LOADSUBADDRESS	Get object attribute, push the pointer to the stack.
ICO_LOADMETHOD		Find object method 
ICO_AFTERCALLMETHOD	Used after calling a method - normal case
ICO_AFTERCALLMETHOD2	Used after calling a method - second case
ICO_NEWCLASS		Start new class region
ICO_BRACESTART		Open brace
ICO_BRACEEND		End brace
ICO_IMPORT		Import package
ICO_PRIVATE		start private attributes region
ICO_SETPROPERTY		set attribute value - check for setter.	
ICO_CALLCLASSINIT	call class init() method.
=======================	============================================================================

(Other)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_SETREFERENCE	Copy by reference
ICO_KILLREFERENCE	Remove reference
ICO_ASSIGNMENTPOINTER 	Determine the left side variable
ICO_BEFOREEQUAL		Determine operators like += , -= , ... etc
=======================	============================================================================

(Bitwise Operators)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_BITAND		Stack[nSize-1] = Stack[nSize-1] & Stack[nSize] , POP stack[nSize]
ICO_BITOR		Stack[nSize-1] = Stack[nSize-1] | Stack[nSize] , POP stack[nSize]
ICO_BITXOR		Stack[nSize-1] = Stack[nSize-1] ^ Stack[nSize] , POP stack[nSize]
ICO_BITNOT		Stack[nSize] = ! Stack[nSize] 
ICO_BITSHL		Stack[nSize-1] = Stack[nSize-1] << Stack[nSize] , POP stack[nSize]
ICO_BITSHR		Stack[nSize-1] = Stack[nSize-1] >> Stack[nSize] , POP stack[nSize]
=======================	============================================================================

(For Step)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_STEPNUMBER		Determine step number in for loop
ICO_POPSTEP		POP step number from steps stack
ICO_LOADAFIRST		Load the first address of variable name 
=======================	============================================================================

(Custom Global Scope)

=======================	============================================================================
Operation			Description
=======================	============================================================================
ICO_NEWGLOBALSCOPE	Start new custom global scope - used by 'load package' command
ICO_ENDGLOBALSCOPE	End of custom global scope - used by 'load package' command
ICO_SETGLOBALSCOPE	Set the current global scope 
=======================	============================================================================

