five/docs/Five-1.0-Phase-C-TODO.md

Five 1.0 — Phase C TODO (Harbour Contrib Libraries)

Status as of commit 2a66252 (2026-04-18).

Context

Phase A (language blockers) and Phase B (RTL blockers) are complete:

• ::super:Method() dispatch — 3a56bd3
• METHOD INLINE + MESSAGE INLINE — 34485cd
• OPERATOR ... ARG x INLINE — 66f045b
• &var / &(expr) runtime macro — e089c81
• DATA x, y, z multi-name parse — 327f75b
• DO(xTarget, args...) — 2a66252
• ACCEPT — skipped (user decision, revisit if needed)
• 11 HBTYPE functions — not actually blockers: these are Harbour's scalar class factories (HBARRAY etc. wrap the Array class used for cStr:Upper() syntax). Five provides the same surface via hbrt/valuemethods.go SendBuiltin and doesn't need the C-level factories exposed.

Remaining for 1.0 is the contrib library ecosystem — Harbour ships ~70 libraries under harbour-core/contrib/, only a handful of which real Harbour programs depend on in 2026. This doc lists the three that block a credible 1.0 release and the minimum scope for each.

The Three

1. hbct — Clipper Tools (highest priority)

Why blocker: Almost every legacy Harbour app imports at least a handful of hbct functions. String/array/date utilities that Clipper shipped with its "Tools" library in the 1990s — now standard Harbour.

Source: harbour-core/contrib/hbct/ — 87 C files, ~1.6 MB.

Full function count: ~250. Realistic 1.0 scope: top ~40 by usage frequency.

Suggested initial batch (each file in hbct/ implements a handful of related functions):

Category	Examples	Harbour source
String formatting	POSCHAR, POSDIFF, POSREPL, POSDEL, POSINS	poschar.c, posdiff.c
String search	RANGEREM, TOKEN*, AFTERATNUM	token1.c, token2.c, afterat.c
String case	ASCIISUM, CHARADD, CHARREM, CHARREPL	asciisum.c, charadd.c
Substring slice	CHARPIX, CHARSORT, CHARSWAP	charpix.c, charsort.c
Numeric	CELSIUS, FAHRENHEIT, PAYMENT, PV, FV	celsius.c, payment.c
Date	DOW, MONTH, NOLEAP, SETDATE	dow.c, month.c
Array	ARRAYTOTOKEN, TOKENTOARRAY	token3.c
Bit ops	NUMAND, NUMOR, NUMXOR, NUMNOT	numand.c, etc.

Approach: Port function-by-function into hbrtl/hbct*.go files grouped by category. Register each via register.go. Most are single-screen Go implementations (the C versions are small and algorithmic — no Harbour VM calls involved).

Harbour-compat verification: Each port should run against the corresponding test in harbour-core/contrib/hbct/tests/ if it exists, otherwise check Harbour's docs/en/ function reference for exact semantics (edge cases on empty string / out-of-range indices frequently differ between C and Go default behaviour).

2. hbnf — Numeric Functions (business/finance)

Why blocker: Accounting, statistics, depreciation calculations. Standard in business apps. Pure-PRG library — 99 .prg files.

Source: harbour-core/contrib/hbnf/source/ — each .prg is one function.

Approach: Unlike hbct which is C, hbnf is pure PRG — Five can load the .prg files directly and compile them. Test with representative sample first (can the Five parser handle the syntax?) then bulk-compile the lot.

First-pass scope:

Function	Purpose
FT_AVG	Arithmetic mean of array
FT_STDDEV	Standard deviation
FT_VARIANCE	Variance
FT_FV	Future value of annuity
FT_PV	Present value
FT_PMT	Loan payment
FT_PRINC	Principal payment
FT_INTEREST	Interest portion
FT_SLN	Straight-line depreciation
FT_DDB	Double declining balance depreciation

Risk: Some FT_* functions use Clipper idioms Five may not yet support. Parse every .prg first before committing to full import — any syntax gap surfaces as a parser error, which points at a specific Phase A/B follow-up.

3. hbtip — TCP/IP, SMTP, POP3, HTTP

Why blocker: Modern Harbour apps do network I/O through hbtip. Without it, sending email, HTTP API calls, FTP transfers all require Go bridging — which Five supports but users shouldn't need to reach for in week one.

Source: harbour-core/contrib/hbtip/ — mix of C + PRG, ~548 KB.

Five advantage: Go's stdlib net/* covers every protocol hbtip implements. Port surface: design the PRG-facing API shape to match hbtip, implement each in one Go function that wraps stdlib.

Minimum 1.0 scope:

Class/Function	Wraps
TIPClientHTTP	net/http client GET/POST
TIPClientSMTP	net/smtp send
TIPClientPOP3	stdlib-less; implement RFC1939 directly
TIPMail	MIME message builder
hb_base64Encode / Decode	encoding/base64
hb_urlEncode / Decode	net/url

Effort Estimate

Phase	Effort	Payoff
hbct top 40 functions	3-5 days	Covers "my legacy app imports CT tools" baseline
hbnf FT_* financial subset	1-2 days (mostly PRG compile)	Business-app completeness
hbtip minimum	2-3 days	Unblocks modern network I/O
Total	~6-10 days	1.0 credibility

Suggested Order

1. hbct — biggest payoff per hour (many small wins)
2. hbtip — strategic: modern apps need it
3. hbnf — pure PRG, lightest integration work

Open Questions

• Partial shipping policy: Can 1.0 ship with "hbct: 40/250 functions" and label the rest as post-1.0? Probably yes — Harbour apps tend to use a small subset, and the port can extend without breaking.
• Test coverage: Do we adopt harbour-core/tests/*.prg as a regression suite, or write Five-specific tests? Adopting the Harbour suite is the strongest compat signal but may hit other unrelated gaps (MT, dynobj, etc.).
• Namespace: Are hbct/hbnf/hbtip functions registered globally (hbrtl.Register*) or gated behind #include "hbct.ch" style imports? Harbour is globally-scoped; matching keeps user code portable.

References

• RTL-Go-Native-Migration.md — prior perf work and 1.0 gap analysis that produced this list.
• RTL-Todo.md — lower-level RTL function gaps (file I/O, string, date) separate from contrib.