foxbin2prg/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A local shared copy of FoxBin2Prg (the VFPX tool by Fernando D. Bozzo, maintained by Lutz Scheffler): a Visual FoxPro 9 program that converts VFP binary files to PRG-style text and back. Supported conversions: PJX↔PJ2, SCX↔SC2, VCX↔VC2, FRX↔FR2, LBX↔LB2, DBC↔DC2, DBF↔DB2, MNX↔MN2.

This directory is a git clone with two remotes:

• origin = https://github.com/fdbozzo/foxbin2prg.git (upstream, read-only). master tracks origin/master and stays a pristine mirror.
• romfast = git@gitea.romfast.ro:romfast/foxbin2prg.git (our fork on Gitea, SSH). Working branch romfast (default on Gitea) = upstream master + the ROA additions committed (vcx2txt.ps1, PROMPT_cautare_vfp.md, CLAUDE.md, git_svn_parallel_init_prompt.md). The pre-git local state is kept on branch local-snapshot-v1.21.04.

Update flow (sync fork from upstream): git fetch origin → git checkout master && git merge --ff-only origin/master → git checkout romfast && git merge master → git push romfast romfast master. After any update, regenerate binaries/EXE in VFP9 with DO ReCreate_FoxBin2Prg.prg (an error about TESTS\FXUResults.db2 is expected). Text caches live outside this folder (D:\ROA\_vfp_textcache\, see below) so ReCreate never touches them; compiled binaries are kept out of git via the upstream .gitignore plus .git/info/exclude (which also still ignores any stray local _textcache*).

It serves two purposes:

1. Upstream tool source (for occasional patches to FoxBin2Prg itself).
2. A shared search tool for the ROA VFP projects (D:\ROA\ROAGEST, D:\ROA\ROAIMOB, D:\ROA\ROAACNPRO, …) via the local additions below.

Local additions (ROA-specific, not part of upstream)

• vcx2txt.ps1 — PowerShell script that converts the VFP binaries of a project (read from its .pjx) into text under a cache folder, so the code inside .vcx/.scx/.frx/.mnx/.dbc binaries becomes greppable. Incremental (skips up-to-date files), does not need the VFP IDE open (uses the compiled FoxBin2Prg.EXE).
• Text caches live outside this folder, under D:\ROA\_vfp_textcache\ (one subfolder per project: roacnpro, roagest, roaimob) — per-project regenerable text caches. Safe to delete; never version them. They must stay outside foxbin2prg: ReCreate_FoxBin2Prg.prg does a recursive Prg2Bin over the whole tool folder (get_FilesFromDirectory recurses into every subfolder, foxbin2prg.prg:6135) and would reconvert any .??2 under it back into stray binaries.
• PROMPT_cautare_vfp.md — reusable prompt (Romanian) explaining how to set up this search flow in any VFP project. Read it before working on VFP code search.

Golden rule: the generated text cache is read-only, for searching only. Code changes to a VFP project are made in the VFP IDE on the binary files (.vcx/.scx/...), never by editing the cached text.

# Populate/refresh a project's text cache (incremental)
& 'D:\ROA\UTIL\foxbin2prg\vcx2txt.ps1' -Project 'D:\ROA\ROAGEST\roagest.pjx' -ProjectRoot 'D:\ROA\ROAGEST' -CacheRoot 'D:\ROA\_vfp_textcache\roagest'

# Include reports/menus too: -Types vcx,scx,frx,mnx
# One-off conversion of a file/folder not in the project: -Source 'path\to\lib.vcx'
# Other flags: -Force (reconvert all), -Clean (wipe cache first)

Then search the cache with Grep (e.g. PROCEDURE do_salvare), citing file:line from the cache.

Commands

All FoxBin2Prg commands run inside VFP 9 (or via the compiled FoxBin2Prg.EXE).

* After clone/pull: regenerate all binaries from text and compile the EXEs.
* NEVER run foxbin2prg.prg directly for this — it uses a special config.
DO ReCreate_FoxBin2Prg.prg

* Convert a single file (direction inferred from extension)
DO FOXBIN2PRG.PRG WITH "<path>\file.scx"     && binary -> text (.sc2)
DO FOXBIN2PRG.PRG WITH "<path>\file.sc2"     && text -> binary (.scx)

* Convert a whole directory
DO FOXBIN2PRG.PRG WITH "<path>","Bin2Prg"
DO FOXBIN2PRG.PRG WITH "<path>","Prg2Bin"

* Config templates
DO FOXBIN2PRG.PRG WITH "-c","template.cfg"      && default settings
DO FOXBIN2PRG.PRG WITH "-C","config.cfg"        && active settings
DO FOXBIN2PRG.PRG WITH "-t","table.dbf.cfg"     && per-table template

* Interactive help / option list
DO FOXBIN2PRG.PRG WITH "?"

Tests

Unit tests live in TESTS/ and use FoxUnit (path configured in TESTS/foxunit_path.txt). Files: ut__foxbin2prg__<class>__<method>.prg (unit) and ft__foxbin2prg__<class>.prg (functional). Run them from VFP via FoxUnit; test fixtures live in TESTS/DATOS_READONLY/.

Architecture

Nearly everything is in one ~34,000-line file: foxbin2prg.prg. Key class hierarchy inside it:

• c_foxbin2prg (As Session) — entry point / public API. Parameter parsing, config resolution (evaluateConfiguration), file dispatch, progress UI, error logging. Also usable as COM-ish object (CREATEOBJECT('c_foxbin2prg'), .execute(...)), which is how the .vbs helpers and SCM integrations drive it.
• c_conversor_base — shared conversion logic (backup handling, timestamps, comment/property parsing, exclusion blocks).
  • c_conversor_bin_a_prg and per-type subclasses (c_conversor_vcx_a_prg, c_conversor_scx_a_prg, c_conversor_pjx_a_prg, c_conversor_dbf_a_prg, …) — binary → text.
  • c_conversor_prg_a_bin and per-type subclasses — text → binary.
• CL_* model classes (CL_CLASE, CL_PROJECT, CL_DBC*, CL_DBF_*, CL_MENU*, …) — object model the text files are parsed into / generated from.
• CL_CFG / CL_DBF_CFG — config file handling (FOXBIN2PRG.CFG with directory inheritance, per-table .dbf.cfg).
• CL_LANG — localization (EN/ES/FR/DE), auto-selected.

Supporting files: foxbin2prg_keywords.dbf/.cdx (VFP keyword table used during generation — has its own .db2 text form), props_*.txt (per-control default property lists used to suppress default values in output), Create_FoxBin2Prg.cfg (the special self-conversion config), Fb2P_Diff/ and FileName_Caps/ (companion sub-projects, built by ReCreate_FoxBin2Prg.prg), BuildProcess/ (VFPXDeployment build hooks), ThorUpdater/ (Thor/VFPX release plumbing).

Text format is position-sensitive: the generated .??2 files look like PRG/XML but are parsed line by line; structure and line layout must be preserved when editing them. Properties/methods are emitted alphabetically sorted.

Upstream contribution conventions (from .github/CONTRIBUTING.md)

If patching FoxBin2Prg itself:

• Two version constants at the top of foxbin2prg.prg: bump only the minor part of DC_FB2PRG_VERSION_REAL (e.g. '1.21.04'); do not change DN_FB2PRG_VERSION (1.21) — it's written into every text file and forces mass recommits.
• Add the change to the history section at the top of foxbin2prg.prg and to docs/ChangeLog.md; update the version in README.md.
• Style: mixed-case keywords, tab indentation, spaces around operators and after list items; do not run BeautifyX with mDots insertion.
• After changes, regenerate text with DO Create_FoxBin2Prg.prg and compile in VFP9 SP2.

Documentation

• docs/FoxBin2Prg_Internals.md — settings reference and internals (ZOrder, timestamps, class-per-file, DBF export hooks, API).
• docs/FoxBin2Prg_Run.md — full command-line/parameter reference.
• docs/FoxBin2Prg_git.md, docs/FoxBin2Prg_SCM.md — SCM integration.
• Spanish docs in Documentacion/ are unmaintained.