DTLcode — Reference Manual v1.7-3
Functional and technical reference for the heuristic source-file analyzer.
Purpose and scope
DTLcode produces a functional overview of an unfamiliar source file. It identifies the language, observes the structure, records the main interactions, and generates an HTML page explaining what the file probably does and how it obtains its results.
The software supports rapid discovery of legacy applications, audit or documentation preparation, and early orientation before a detailed code review.
Design principles
- Caution: wording describes likely behavior and does not present inference as certainty.
- Readability: the report favors plain explanations over exhaustive code documentation.
- Observation: subroutine descriptions are based on operations found in their bodies and never repeat their names.
- Self-containment: the HTML page includes its styling and requires no server.
- Deduplication: lists are cleaned, bounded, and stripped of repeated entries.
Architecture
Analysis pipeline
The orchestration function creates an AnalysisResult, fills it in stages, and passes it to the HTML generator. The analysis core is independent from the terminal or file-selection dialog used to start the program.
File organization
DTLcode.py
Complete implementation: reading, analysis, functional inference, HTML generation, and launch interface.
DTLcode.spec
PyInstaller recipe used to produce the standalone Windows executable DTLcode.exe.
README_Fr.md / README.md
Short overview, examples, and limitations in both documentation languages.
Result model
AnalysisResult centralizes observed facts and inferred behavior. It stores file metadata, code structures, resources, interactions, warnings, usage details, and the rows used by the subroutine table.
| Family | Representative fields | Purpose |
|---|---|---|
| File | path, language, size, encoding, lines | Precisely identify the analyzed target. |
| Structure | variables, constants, imports, functions, classes | Present the main code components. |
| Behavior | purpose, workflow, inputs, results | Explain the likely functional role. |
| Integrations | files, URLs, network, database, commands | Show observed dependencies and external effects. |
| Robustness | error handling, warnings | Report safeguards and analysis limitations. |
Analysis reference
Recognized languages and extensions
| Family | Extensions |
|---|---|
| Python | .py, .pyw |
| PowerShell | .ps1, .psm1, .psd1 |
| Web | .php, .js, .mjs, .cjs, .ts, .tsx, .jsx, .html, .htm, .css, .scss, .sass |
| Scripts | .bat, .cmd, .sh, .bash, .zsh, .vbs |
| Data | .sql, .json, .yaml, .yml, .xml, .ini, .toml |
| Compiled and other | .java, .c, .h, .cpp, .cc, .hpp, .cs, .go, .rs, .rb, .pl, .lua |
An unknown extension invokes generic analysis and adds a warning to the report.
Common extraction
Regular-expression patterns look for URLs, file paths, system commands, network or database access, user interaction, and error-handling constructs. Useful comments are extracted according to language syntax and limited to sufficiently meaningful items.
Specialized Python processing
Python receives syntax-aware analysis through the standard ast module. DTLcode records imports, classes, functions, global assignments, and simple values without executing the program. Literal strings and comments can be neutralized during common searches to reduce false positives.
Subroutine descriptions
The subroutine table contains a functional label and a one- or two-sentence description. The description never repeats the technical name; it is built from observed operations such as file reading or writing, syntax analysis, pattern matching, validation, user interaction, command execution, or HTML generation.
When a precise role cannot be established, the report cautiously describes iteration, conditions, or the returned value. Small internal utilities are omitted to preserve readability.
HTML report
Generated sections
- header with file, path, language, line count, size, and encoding;
- likely purpose and processing steps;
- accessible table of the main subroutines;
- interface, resources, error handling, and warnings;
- usage syntax, parameters, and expected results;
- a note explaining the heuristic nature of the summary.
The layout is responsive, printable, and readable without JavaScript. Empty sections are omitted.
Rendering safety
All content originating from the analyzed file is escaped with html.escape before insertion. A tag or script found in source code is therefore displayed as text and cannot become active HTML content.
Interface and return codes
Command line
Without a source argument, a Windows dialog selects the file. Without an output option, the report is written to DTLcode_report.html and opened with the associated application when supported by the operating system.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Report created, version displayed, or file selection cancelled. |
| 1 | Read, write, dialog, or operating-system error. |
| 2 | The source path does not exist or is not a file. |
Operations and maintenance
Input encodings
Reading tries UTF-8 with BOM, UTF-8, Windows-1252, and Latin-1 in that order. The selected encoding appears in the report. The output page is always written as UTF-8.
PyInstaller build
The specification builds a one-file console executable. Under the project rules, every rebuild must first increment the patch version and propagate it to all affected code, metadata, tests, and documentation.
Known limitations
- Analysis is heuristic and does not replace a compiler, a full parser, or human review.
- The language is inferred from the filename extension rather than the actual content.
- Dynamic code, metaprogramming, and calls built at runtime are difficult to interpret statically.
- Non-Python analysis relies primarily on regular expressions and has less syntactic context.
- Beyond 5,000 lines, the report remains intentionally concise and displays a warning.