📄 Updated lib_template.py!

examples/ezr-python-library-template/lib_template.py

@@ -1,5 +1,5 @@
 # Import needed classes from ezr.py
-from ezr import Interpreter, RuntimeResult, RuntimeError, VarAccessNode, CallNode, BaseFunction, Nothing, Bool, Number, String, List, RTE_INCORRECTTYPE
+from ezr import Interpreter, RuntimeResult, RuntimeError, VarAccessNode, CallNode, BaseFunction, Nothing, Number, String, RTE_INCORRECTTYPE
 
 # ezr value classes
 # -----------------
@@ -8,54 +8,53 @@
 #
 #   Nothing() -> NOTHING value
 #
-#   Bool(True/False) -> Boolean value
+#   Bool(True / False) -> Boolean value
 #       'Bool(True)' -> Boolean value of True
-#   Number(value) -> Int/Float value
+#   Number(value) -> Int / Float value
 #       'Number(4)' -> Int value of 4
 #       'Number(4.45)' -> Float value of 4.45
 #   String(value) -> Str value
 #       'String('Hello!')' -> Str value of 'Hello!'
 #   List(values) -> List of any values
-#       'List([String('t'), Number(3), Bool(False)])' -> List of values ['t', 3, False]
+#       'List([String('t'), Number(3), Bool(False)])' -> List of values ['t', 3, false]
+#   Dict(pairs) -> Dictionary of any values
+#       'Dict([(String('t'), Number(3)), (Bool(False), List([Number(4)]))])' -> Dict of values {'t' : 3, false : [4]}
 #
 #   Function(name, body_node, arg_names, should_auto_return) -> Function definition
 #   Object(name, body_node, arg_names) -> Object definition
 #
-# It is not recommended to use ezrs' Function or Object classes
-# other than for inheritance; Use Python functions/objects instead
-# NOTE: The Value and BaseFunction class are ONLY for inheritance, all others can be returned
-# Refer to ezr.py for the code for these classes
+# NOTE: Dictionary keys must be hashable
+# The Value and BaseFunction class are ONLY for inheritance, all others can be returned as output.
+# Refer to ezr.py for the code for these classes.
 
 # RuntimeResult and error handling
 # --------------------------------
-# RuntimeResult is the class used for registering expressions and checking for
-# errors and SKIP, STOP and RETURN calls
-# All functions should have a RuntimeResult().success(return-value) call
-# as that is how ezr checks for error, or the lack thereof
-# To throw errors, use the failure function in RuntimeResult and return it
+# RuntimeResult is the class used for registering expressions and checking for errors and SKIP, STOP and RETURN calls.
+# All functions should have a RuntimeResult().success(return-value) call as that is how ezr checks for error, or the lack thereof.
+# To display errors, use the failure function in RuntimeResult and return it-
 # eg: return RuntimeResult().failure(RuntimeError(self.start_pos, self.end_pos, ERROR_TAG, 'Error message', self.context))
-# Error tags are str values used to catch errors in the TRY statement
-# An error tag can be as simple as this: EXAMPLE_ERRORTAG = 'EXAMPLE-ERRORTAG'
-# Any errors thrown with this tag will be caught by TRY statements using the 'EXAMPLE-ERRORTAG' tag
 # You can import any error class from ezr.py, such as:
 #   UnknownCharError(start_pos, end_pos, details) -> Raised when any undefined characters are found
 #   InvalidSyntaxError(start_pos, end_pos, details) -> Raised when the expected syntax is not found
 #   RuntimeError(start_pos, end_pos, error_type, details, context) -> Any errors caused while running the code
-# It is recommended to only use the RuntimeError class for libraries
-# You can also make your own error class by inheriting from the base Error class or the RuntimeError class
-# It is recommended to only use the built-in error tags that ezr.py provides; They can be imported into any project
+# Always return / inherit from the RuntimeError class. The TRY statement is coded to only handle RuntimeErrors-
+# as InvalidSyntax and UnknownChar errors MUST NOT occur in the Interpreter.
+# 
+# Error tags are str values used to catch errors in the TRY statement.
+# An error tag can be as simple as this: EXAMPLE_ERRORTAG = 'EXAMPLE-ERRORTAG'
+# Any errors thrown with this tag will be caught by TRY statements using the 'EXAMPLE-ERRORTAG' tag
+# ezr.py has some builtin error tags too- they can be imported into any project
 #   RTE_DEFAULT        = 'RUNTIME'
 #   RTE_CUSTOM         = 'CUSTOM'
+#   RTE_DICTKEY        = 'DICTIONARY-KEY'
 #   RTE_ILLEGALOP      = 'ILLEGAL-OPERATION'
 #   RTE_UNDEFINEDVAR   = 'UNDEFINED-VAR'
 #   RTE_IDXOUTOFRANGE  = 'INDEX-OUT-OF-RANGE'
-#   RTE_TOOMANYARGS    = 'TOO-MANY-FUNCTION-ARGS'
-#   RTE_TOOFEWARGS     = 'TOO-FEW-FUNCTION-ARGS'
+#   RTE_TOOMANYARGS    = 'TOO-MANY-ARGS'
+#   RTE_TOOFEWARGS     = 'TOO-FEW-ARGS'
 #   RTE_INCORRECTTYPE  = 'INCORRECT-TYPE'
 #   RTE_MATH		   = 'MATH'
-#   RTE_FILEREAD	   = 'FILE-READ'
-#   RTE_FILEWRITE	   = 'FILE-WRITE'
-#   RTE_RUNFILE 	   = 'RUN-FILE'
+#   RTE_IO	   		   = 'IO'
 # More details about these error tags are available in the ezr documentation
 
 # Create main object
@@ -108,7 +107,7 @@ def execute(self):
         # Return a copy of self
         return res.success(self.copy())
 
-    # Function to 'retrieve' variables/functions from object
+    # Function to 'retrieve' variables / functions from object
     def retrieve(self, node):
         res = RuntimeResult()
 
@@ -117,7 +116,7 @@ def retrieve(self, node):
             # Retrieving variable from object, defaulting to NOTHING
             return_value = self.get_variable(node.var_name_token.value)
 
-        # For CallNodes (Function/object calls)
+        # For CallNodes (Function / object calls)
         elif isinstance(node, CallNode):
             # Getting function name
             method_name = f'function_{node.node_to_call.var_name_token.value}'
@@ -200,8 +199,8 @@ def function_test_add(self, node, context):
         val_a = context.symbol_table.get('val_a')
         val_b = context.symbol_table.get('val_b')
 
-        if not isinstance(val_a, Number): return res.failure(RuntimeError(node.start_pos, node.end_pos, RTE_INCORRECTTYPE, 'First argument has to be a [NUMBER]', self.context))
-        if not isinstance(val_b, Number): return res.failure(RuntimeError(node.start_pos, node.end_pos, RTE_INCORRECTTYPE, 'Second argument has to be a [NUMBER]', self.context))
+        if not isinstance(val_a, Number): return res.failure(RuntimeError(node.start_pos, node.end_pos, RTE_INCORRECTTYPE, 'First argument has to be a [NUMBER]', context))
+        if not isinstance(val_b, Number): return res.failure(RuntimeError(node.start_pos, node.end_pos, RTE_INCORRECTTYPE, 'Second argument has to be a [NUMBER]', context))
 
         return res.success(Number(val_a.value + val_b.value))
     function_test_add.arg_names = ['val_a', 'val_b']