API reference of DiddiParser 2

This document explains the internal API of DiddiParser 2

diddiparser2.diddiscript_types – DiddiScript standard types

This Python module stores all the DiddiScript types (written in Python) defined by DSGP 1. You can return these types in your extensions.

class diddiparser2.diddiscript_types.DiddiScriptType

The template type for all the DiddiScript types. Please don’t use this type.

value

The Python value that is represented by the DiddiScript type. On this template type, is is an empty object.

__str__(self)

Returns the value, as a string. In most of the cases, this method is respected by all the subclasses.

__int__(self)

Returns the value as a Python integer. If a ValueError is raised, we raise our own exception.

__float__(self)

Returns the value as a Python float. If a ValueError is raised, we raise our own exception.

__bool__(self)

Returns the value as a Python bool.

class diddiparser2.diddiscript_types.Integer(DiddiScriptType)

The type that represents integer numbers.

__init__(self, value_text)

Parameters:

value_text – The value to be stored. This becomes diddiparser2.diddiscript_types.DiddiScriptType.value.

Constructor method. The value is converted to int.

__int__(self)

Instead of trying to convert to int, we just return the value.

class diddiparser2.diddiscript_types.Floating(DiddiScriptType)

The type that represents floating numbers.

__init__(self, value_text)

Parameters:

value_text – The value to be stored. This becomes diddiparser2.diddiscript_types.DiddiScriptType.value.

Constructor method. The value is converted to float.

__float__(self)

Instead of trying to convert to float, we just return the value.

class diddiparser2.diddiscript_types.Text(DiddiScriptType)

The type that represents text.

__init__(self, value_text)

Parameters:

value_text – The value to be stored. This becomes diddiparser2.diddiscript_types.DiddiScriptType.value.

Constructor method. The value is not converted, since we always expect value to be a string.

class diddiparser2.diddiscript_types.Boolean(DiddiScriptType)

The type that represents booleans.

__init__(self, value_text)

param value_text:

The value to be stored. This becomes diddiparser2.diddiscript_types.DiddiScriptType.value.

Constructor method. It tries to convert the value to bool. If that doesn’t work, we convert value to the bool resulting from a truthy-falsy comparation (however, this is not needed at all).

__bool__(self)

Instead of trying to convert to bool, we just return the value.

class diddiparser2.diddiscript_types.Null(DiddiScriptType)

The type that represents a null value.

__init__(self, value_text=None)

Parameters:

value_text – We only have this to avoid argument issues, but it is ignored.

Constructor method. Actually, value_text is ignored here, we store None instead.

__str__(self)

This method is overriden to return a "Null" text.

diddiparser2.parser – main parser configurations

This module configures the main DiddiScript parser, and some useful variables.

diddiparser2.parser.__version__

Type:

str

A string that represents the parser’s version.

diddiparser2.parser.EXECUTION_VARIABLES

Type:

dict

Value:

{}

A name: value dictionary of defined variables.

class diddiparser2.parser.DiddiParser

This class is the main DiddiScript parser.

__init__(self, file, ignore_suffix=False, verbose=False, compile_only=False, notify_success=True)

Parameters:

• file (str) – The DiddiScript file to be parsed.

• ignore_suffix (bool) – If True, tells DiddiParser to ignore the suffix mismatch.

• verbose (bool) – If True, the parser will echo all the commands executed by diddiparser2.parser.DiddiParser.runfile().

• compile_only (bool) – If True, the parser will just run what is necessary for compiling (like library loaders and variable definitions), and will try to find potential errors (unresolved references, invalid code, etc.).

• notify_success (bool) – Mostly an internally-used option, to avoid notifying when an execution finishes without issues.

The constructor method. It reads the selected filename, and gets the commands via diddiparser2.parser.DiddiParser.get_commands().

get_commands(self)

Returns:

A list of prepared commands.

Return type:

list

Raises:

diddiparser2.messages.error – When a syntax error is found.

This function returns a list of DiddiScript commands, without comments. It can raise a compile error if there are missing semicolons (;).

executeline(self, line)

Parameters:

line (str) – A line of DiddiScript code.

Raises:

diddiparser2.messages.error – If the execution fails.

Run a single line of code. It runs diddiparser2.parser.DiddiParser.execute_def() and diddiparser2.parser.DiddiParser.execute_func() when necessary.

execute_def(self, line)

Parameters:

line (str) – A line of DiddiScript code.

Raises:

diddiparser2.messages.error – If the execution fails.

Execute a line with a variable definition, according to DSGP 1.

See also

DSGP 1

Read the DSGP that specifies the variable standards, and is used by this method.

execute_func(self, line)

Parameters:

line (str) – A line of DiddiScript code.

Raises:

diddiparser2.messages.error – If the execution fails.

Execute a line with a function.

identify_value(self, arg, from_func=False)

Parameters:

• arg (str) – A string that must become a readable value for DiddiParser.

• from_func (bool) – This is used internally, to tell this method that the value was returned from a library/extension.

Identify a value inside a text, and return the correct value.

Note

When from_func is True, the method won’t fail if no values are found. Instead, it will return a string of the value. This is a workaround to one of our current issues with interpreting the values returned by libraries/extensions.

However, this is not a recommended behavior. See DiddiLeija/diddiparser2#43 for more information.

parse_string_indexing(self, line)

Parameters:

line (str) – A string.

Format a string with variables, using the DSGP 1 specification.

See also

DSGP 1

Read the DSGP that specifies the variable indexing with strings, and is used by this method.

runfile(self)

Runs diddiparser2.parser.DiddiParser.executeline() for each line, and then prints a success message.

class diddiparser2.parser.InteractiveDiddiParser(DiddiParser)

This is a subclass of diddiparser2.parser.DiddiParser, which generates an interactive console to execute commands on real time. It left unchanged the methods from his ancestor (it only modified the __init__ and print_command). However, it added some other methods, described below.

loop(self)

Generates a “DiddiScript console” which calls diddiparser2.parser.DiddiParser.executeline() for each line of input.

diddiparser2.messages – Tools for user/parser interactions

These functions are used by the parser (generated by diddiparser2.parser) to interact with you as the “interpreter”. Also, you can use some of this functions in your extensions.

exception diddiparser2.messages.error

An exception (which is a direct subclass of Exception) raised when a function decided to stop the program.

diddiparser2.messages.run_error(msg)

Raises:

error – at the end of the function.

Prints a “run error” in red, and stop the executions. This function is used when something in the execution failed. In most of the cases, this function is used by libraries and extensions.

diddiparser2.messages.compile_error(msg)

Raises:

error – at the end of the function.

This function prints a “compile error” in red, and stop all the executions. This is commonly raised by the parser when a syntax error appears, a missing function is called, etc.

diddiparser2.messages.show_warning(msg)

This function prints a warning in yellow. It does not stop the execution.

diddiparser2.messages.success_message(msg=None)

Parameters:

msg – An optional message. If it’s None, a default message is used.

This function is called by the parser to tell the user that the execution finished succesfully.

diddiparser2.editor – The DiddiScript editor

In most of the cases, the API contained in this subpackage is just used internally for the DiddiScript Editor.

The main configurations happen at diddiparser2.editor.main, and are imported by diddiparser2.editor.__main__ to use it via python -m diddiparser2.editor.

See also

The DiddiScript Editor Guide

A complete guide to the editor’s GUI and options.

Here’s a small description of each component of this subpackage:

diddiparser2.editor.__init__

The init file. It only contains a docstring.

diddiparser2.editor.__main__

This enables the use of python -m diddiparser2.editor, to do the same than the diddiscript-editor command.

diddiparser2.editor.formatter

This is the responsible of the “themes stuff”. Here, the theme colorization is made, the themes are stored, and themes are loaded from JSON files.

diddiparser2.editor.main

This is where the GUI building, setup, and running is done. It generates a DiddiScriptEditor class, which contains a functional editor with Tk.