[PY-INJ] Python Injected Material

About [PY-INJ] Material

A material in GraphScript is a system that defines and implements side-effects for a GraphScript code file.

The [PY-INJ] material allows you to implement GraphScript syntax nodes via injected Python code. It is one of the first materials and a very primitive one, yet it is extremely powerful.

How to create a [PY-INJ] Material

Steps

1. Clone this repository.
2. Remove the .git folder (preferably, re-initialize the git repository).
3. Edit the materials/template/main.py file to implement your own nodes.
4. Rename the materials/template folder to your material name.
5. Edit the test.gsam file with relevant usage of your material.
6. Run the test.gsam file with the GraphScript runtime. (gsam test.gsam)
7. Edit the README.md file to document your material. [OPTIONAL]
8. Publish your material to GitHub and share it with the GraphScript community. [OPTIONAL]
9. Use your material in your GraphScript projects. [OPTIONAL, but highly recommended]

Anticipated Folder Structure

.
├── README.md
├── materials
│   └── <material_name>
│       ├── main.py
│       └── material.conf
└── test.gsam

Injection Template (Python File)

A material is organized into the following sections:

• INTERFACES (Optional)
• RUNTIME IMPORTS (Required)
• UTILITY FUNCTIONS (Optional)
• IMPLEMENTATIONS (Required)
• NODE DEFINITIONS (Required)
• LOAD FUNCTION (Required)

Implementing Nodes

Create a syntax node by subclassing SyntaxNode and implementing execute_material.

@extends
class ExampleNode(Interface.SyntaxNode):
  def execute_material(
    self: Interface.SyntaxNode,
    syntax: Interface.SyntaxNode,
    stream: Interface.ExecutionStream,
  ):
    """
    # Example Node: Execute Material

    - `self`: The registered node instance.
    - `syntax`: The syntax node being executed.
    - `stream`: The active execution stream.
    """

    # Implement the node's side-effect here
    ...

Exporting Nodes

Export every syntax node through the _definitions dictionary.

_definitions = {
  "example": ExampleNode,
}

The key is the exported node name. The value is the corresponding SyntaxNode subclass.

The load() Function

Every material must define a load() function. The runtime calls it once when importing the material.

Typical responsibilities include:

• Reading material configuration.
• Registering exported nodes.
• Performing one-time initialization.

While the template already handles registering nodes via _definitions. Memory of the runtime can also be manually manipulated using the memory API. For example, you can register a node with a fixed name like this:

memory.upsert(
  fixed_name,
  NodeClass("*", fixed_name),
)

Helper Functions

Most materials benefit from helper functions for parsing arguments.

• Keyword Arguments

  kw_parse(syntax)

• Positional Arguments

  arg_parse(syntax)

These helpers are optional but recommended for consistency across materials.