> For the complete documentation index, see [llms.txt](https://0xlava.gitbook.io/ducky-morph/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://0xlava.gitbook.io/ducky-morph/python-api/duckymorph.md).

# DuckyMorph

### High-Level API

`DuckyMorph` is the main public interface of the framework.

It provides a simplified, high-level API that exposes the entire Duckymorph compilation pipeline through a small set of methods.

Instead of interacting directly with parsers, generators, and internal services, users can rely on this class to perform all common operations.

The class acts as a facade over the framework internals, hiding implementation details while providing a clean and intuitive developer experience.

***

### Design Overview

The `DuckyMorph` API coordinates multiple internal components:

* `DuckyParser` for parsing Duckyscript.
* `FileManager` for filesystem operations.
* `CodeGeneratorsFactory` for loading and managing transpilers.

The typical workflow is:

1. Parse a Duckyscript source into an AST.
2. Optionally save the AST for inspection or debugging.
3. Discover available code generators.
4. Generate target code from the AST.

This architecture allows users to interact with the framework without understanding its internal implementation.

***

### Typical Workflow

```python
from duckymorph import DuckyMorph

dm = DuckyMorph()

ast = dm.parse_duckyscript("payload.ds")

code = dm.generate_code(
    generate="arduino",
    ast=ast
)

print(code)
```

***

### Core Methods

#### <mark style="color:yellow;">parse\_duckyscript</mark>(script\_file, duckyscript="")

Parses Duckyscript source code and produces an Abstract Syntax Tree (AST).

#### Behavior

* Creates a new parser instance.
* Accepts either:
  * A source file path.
  * Raw Duckyscript code.
* Validates source files when necessary.
* Parses the source code.
* Returns the generated AST.

#### Use Cases

* Parsing `.ds` source files.
* Parsing dynamically generated Duckyscript.
* Building custom transpilation pipelines.

***

#### <mark style="color:yellow;">save\_ast</mark>(ast, file)

Exports an AST structure into a JSON file.

#### Behavior

* Verifies that the output file uses the `.json` extension.
* Delegates serialization to `FileManager`.
* Saves the AST in a human-readable JSON format.

#### Use Cases

* Debugging parser output.
* Inspecting intermediate representations.
* Visualizing AST structures.

***

#### <mark style="color:yellow;">get\_avaliable\_generators</mark>(load\_all=False)

Returns all registered code generators.

#### Behavior

* Optionally loads all generators before querying.
* Retrieves the currently registered generators from the factory.

#### Use Cases

* Listing supported transpilation targets.
* Building dynamic CLI interfaces.
* Discovering installed plugins.

***

#### <mark style="color:yellow;">generate\_code</mark>(generate, ast)

Generates target source code from an AST.

#### Behavior

* Requests the appropriate generator from the factory.
* Instantiates the selected generator.
* Delegates code generation to the generator implementation.
* Returns the generated source code.

#### Use Cases

* Transpiling Duckyscript into supported targets.
* Producing payload source code.
* Integrating DuckyMorph into external tools.

***

### Facade Pattern

`DuckyMorph` implements a Facade Pattern.

The class encapsulates multiple subsystems behind a unified interface, significantly reducing the complexity exposed to end users.

Users only interact with a single object while the API internally coordinates parsers, file services, and code generators.

***

### Error Handling

Errors raised by underlying components are propagated through the API.

Common error scenarios include:

* Invalid or missing source files.
* Parsing failures.
* Unsupported code generators.
* Invalid AST export paths.
* Generator loading failures.
* Syntax errors inside Duckyscript source code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://0xlava.gitbook.io/ducky-morph/python-api/duckymorph.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.