DTLcode — User Guide v1.7-3
Quickly analyze a source file and understand its role without executing it.
What does DTLcode do?
DTLcode helps answer a simple question: “What does this source file do?” It reads the file, recognizes its language, identifies its components, and produces a clear HTML page describing its likely purpose.
Use it to discover a legacy program, prepare documentation, guide an audit, or obtain an initial overview before reading the code in detail.
Requirements
Using the executable
Run DTLcode.exe directly. Python is not required on the computer.
Using the source
Use Python 3.10 or later. No external library is required.
Getting started
Simplest method: the file dialog
- Double-click
DTLcode.exe. - Select the source file in the file dialog.
- Wait for
DTLcode_report.htmlto be created. - The report opens automatically in your default browser.
If you cancel the selection, the program exits without creating a file or displaying an error.
Command-line use
This command analyzes MyProgram.py, writes DTLcode_report.html in the current directory, and attempts to open it.
The same operation can be run from the Python source.
Reading the report
General information
The top of the page shows the file name and path, detected language, line count, size, and encoding. Use this information to immediately confirm that the correct file was analyzed.
Purpose and workflow
What this file is for summarizes its likely purpose. How the program obtains the result lists the main observed steps, such as reading data, analysis, transformation, external calls, or result creation.
Subroutine table
The table has two columns:
| Column | Content |
|---|---|
| Function | A readable functional label for the subroutine. |
| Description | One or two sentences explaining the operations actually observed: reading, analysis, validation, object creation, HTML generation, and so on. |
The description does not repeat the technical subroutine name. If its role is uncertain, DTLcode reports visible operations instead of inventing intent.
Resources, errors, and usage
- Interface and presentation: detected user interactions or visual elements.
- Resources used: observed files, URLs, network, database, or commands.
- Error handling: checks, exceptions, or failure-handling constructs.
- Limitations or warnings: unknown extension, very large file, or reduced analysis.
- Usage: syntax and parameters inferred from the analyzed program.
Practical examples
Analyze a Python program
Use quotation marks when a path contains spaces. Python receives the richest analysis: imports, classes, functions, assignments, and operations found inside function bodies.
Choose the report name and location
The -o or --output option sets the HTML page path. The destination directory must already exist and be writable.
Use DTLcode from a script
The exit code allows a Batch or PowerShell script to detect failure. Automatic report opening depends on the HTML file association configured in Windows.
Display the version
This command displays the application name and version without analyzing a file.
Messages, errors, and troubleshooting
Exit codes
| Code | Situation | Suggested action |
|---|---|---|
| 0 | Report created, version displayed, or selection cancelled. | No action required. |
| 1 | Read, write, or operating-system error. | Check permissions, encoding, and the output directory. |
| 2 | The path does not exist or is not a file. | Correct the path or select another file. |
Common problems
| Symptom | Likely cause | Solution |
|---|---|---|
| The report does not open | No application is associated with HTML files. | Open the report manually in a browser. |
| The report cannot be written | The folder is missing or protected. | Choose an existing folder where you have write access. |
| Unknown language | The extension is missing or unrecognized. | Check the extension; generic analysis is still produced. |
| Very little information | Generic language, dynamic code, or a mostly data-oriented file. | Treat the report as an orientation aid and complete it with human review. |
| Incorrect characters | An uncommon encoding was not recognized. | Convert a copy of the file to UTF-8 and analyze it again. |
Interpreting results correctly
- The report is a heuristic summary, not formal proof of behavior.
- DTLcode does not follow calls into other files and analyzes one target at a time.
- A feature may exist without being detected, especially when it is built dynamically.
- A resource mentioned in code is not necessarily used during every execution.
- For files over 5,000 lines, the summary is intentionally limited.