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

Five 1.0 — Phase C TODO (Harbour Contrib Libraries)

Status as of commit 4a1bbdb (2026-04-18).

Context

Phase A (language blockers), Phase B (RTL blockers), and the compatibility-audit follow-ups are complete. Summary below, then the remaining Phase C work (contrib libraries) + a short list of low-priority edge cases surfaced by the Harbour test-suite audit.

Phase A — language blockers (done)

• ::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

Phase B — RTL blockers (done / re-scoped)

• ACCEPT — user deferred (revisit if needed).
• 11 HBTYPE functions — not actually blockers: these are Harbour's scalar class factories (HBARRAY wraps the Array scalar 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.

2026-04-18 audit follow-ups (done)

Harbour test suite re-audit (50 files sampled, broad coverage) moved from 34/40 building to 47/50 (94%). Fixes landed:

• Implicit CLASS binding for standalone METHOD bodies — 0a5482b
• Keyword-as-identifier at stmt-block boundaries — d3c4447
• common.ch ISNIL/ISARRAY/ISNUMBER/ISCHARACTER/ISDATE/ISLOGICAL/ ISOBJECT/ISBLOCK/ISMEMO aliases — d6c2610
• #xcommand NAME( <m>, <n> ) paren-attached keyword — 4b629f7
• SWITCH empty / OTHERWISE-only / EXIT-from-case — 65b2edc
• M-> / MEMVAR-> memvar access — 385a4ec
• PP stringify markers + paren-balanced capture — e952277
• USE &cFile ALIAS &a INDEX &c macro args — 85002df
• #pragma BEGINDUMP inline-C detection with friendly error — 5514780
• Inline Go #pragma BEGINDUMP imports hoisted + HB_FUNC dispatch — b1024c5
• #xcommand [, <vn> TO <xn>] optional-repeat blocks (DEFAULT / UPDATE in common.ch now work) — 4a1bbdb

Remaining low-priority edge cases (from the audit)

#	Symptom	Where	Scope
1	RDDTESTF NIL, {arr}, call() — xcommand taking a <x> regular marker where the argument itself contains top-level commas. PP captures fine but expansion produces output that the Harbour-style rddtst_wr can't re-parse.	tests/rddtest/adscl52.prg, adscl53.prg	xcommand argument-count resolution OR extend <*x*> wild marker support. ~2-4h
2	Integer overflow on u64 literals like 18446744073709600000. Five emits Go's signed int64; overflow causes cannot use ... (untyped int constant) in generated Go.	tests/dyn.prg	Route large literals to Go uint64 / math/big. ~1-2h
3	USE ../alias — relative path literal with ../ tokenised as decimal-dot operator.	tests/mt/mttest10.prg	Lexer context for .. inside USE filename. ~1-2h
4	Harbour legacy identifier { C-code } inline C block syntax (deprecated form predating #pragma BEGINDUMP).	tests/hbinline.prg	Friendly error similar to 5514780. ~30min.

None block a realistic 1.0 — all are specialised to Harbour's own test conventions, not production code patterns.

Phase C scope

Originally three libraries (hbct, hbnf, hbtip). User clarified: PRG contribs can be imported as-is as long as their low-level RTL deps exist in Five. So Phase C is really "audit each contrib's RTL dependencies, fill the gaps, then copy the .prg files wholesale".

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.