> 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/filemanager.md).

# FileManager

### File Management Service

The `FileManager` is responsible for handling all file-related operations inside DuckyMorph.

It provides a centralized interface for validating source files, storing generated output, and exporting internal structures such as the Abstract Syntax Tree (AST).

By isolating file operations in a dedicated service, DuckyMorph keeps I/O logic separated from parsing and transpilation logic.

***

### Design Overview

The service follows a straightforward workflow:

1. Validate input Duckyscript files.
2. Convert file paths into `Path` objects.
3. Save generated source code to disk.
4. Export AST structures into JSON format.

This design ensures that all filesystem interactions are managed consistently across the framework.

***

### Supported File Types

When validating source files, the manager currently accepts:

* `.ds`
* `.txt`

Any unsupported extension should result in validation failure.

***

### Core Methods

#### <mark style="color:yellow;">parse\_duckyscript\_file</mark>(file\_path)

Validates a Duckyscript source file and converts it into a `pathlib.Path` object.

#### Behavior

* Checks whether the file exists.
* Verifies that the extension is supported.
* Returns a `Path` object representing the source file.

#### Use Cases

* Loading Duckyscript programs.
* Validating CLI input.
* Preventing invalid source files from entering the compilation pipeline.

***

#### <mark style="color:yellow;">save\_generated\_code</mark>(code, file, ext="txt")

Saves transpiled or generated source code to disk.

#### Behavior

* Checks whether the destination filename already contains an extension.
* Automatically appends the specified extension when necessary.
* Writes the generated code using UTF-8 encoding.

#### Use Cases

* Saving transpilation results.
* Exporting generated payloads.
* Writing output files produced by code generators.

***

#### <mark style="color:yellow;">save\_ast\_as\_json</mark>(ast, saving\_path)

Serializes an Abstract Syntax Tree (AST) and stores it as a JSON document.

#### Behavior

* Converts each `ASTNode` into its dictionary representation.
* Serializes the complete AST structure.
* Saves the resulting JSON file with indentation for readability.

#### Use Cases

* Debugging parser output.
* Visualizing generated AST structures.
* Inspecting intermediate compilation stages.

***

### Example Workflow

```python
manager = FileManager()

source = manager.parse_duckyscript_file("payload.ds")

manager.save_generated_code(
    code=generated_code,
    file="output.py"
)

manager.save_ast_as_json(
    ast=ast,
    saving_path="ast.json"
)
```

***

### Error Handling

The `FileManager` may raise exceptions in situations such as:

* Source file does not exist.
* Unsupported file extension.
* Invalid saving path.
* Filesystem permission errors.
* JSON serialization failures.


---

# 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/filemanager.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.