docs: Phase C contrib TODO + Phase A/B completion marker
Create Five-1.0-Phase-C-TODO.md capturing the remaining 1.0 work: three Harbour contrib libraries (hbct Clipper Tools, hbnf Numeric Functions, hbtip TCP/IP/SMTP/POP3/HTTP). Each entry lists the Harbour source path, a minimum first-pass scope, and an effort estimate. Suggested order: hbct → hbtip → hbnf. Total ~6-10 days. Update RTL-Go-Native-Migration.md "남은 병목" with the Phase A/B completion list — six features shipped this session — plus a note that the 11 HBTYPE functions the initial analysis flagged are actually Harbour's internal scalar class factories, not user-facing blockers (Five's SendBuiltin covers the same surface). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
156
docs/Five-1.0-Phase-C-TODO.md
Normal file
156
docs/Five-1.0-Phase-C-TODO.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# 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/`](../../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/`](../../harbour-core/contrib/hbnf/) — 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/`](../../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](RTL-Go-Native-Migration.md) — prior
|
||||
perf work and 1.0 gap analysis that produced this list.
|
||||
- [RTL-Todo.md](RTL-Todo.md) — lower-level RTL function gaps (file
|
||||
I/O, string, date) separate from contrib.
|
||||
@@ -1008,6 +1008,25 @@ dbCloseAll() // flush + close all
|
||||
|
||||
## 아직 남은 병목 (차기 검토 후보)
|
||||
|
||||
### 언어/VM 커버리지 (Phase A + B, 2026-04-18 완료)
|
||||
|
||||
- ✅ `::super:Method()` 디스패치 (`3a56bd3`)
|
||||
- ✅ `METHOD ... INLINE expr` + `MESSAGE ... INLINE` (`34485cd`)
|
||||
- ✅ `OPERATOR "<op>" ARG x INLINE` + VM 이항 연산 디스패치 (`66f045b`)
|
||||
- ✅ `&var` / `&(expr)` 런타임 매크로 컴파일 (`e089c81`)
|
||||
- ✅ `DATA x, y, z` 다중-이름 파싱 (`327f75b`)
|
||||
- ✅ `DO(xTarget, args...)` 동적 디스패치 (`2a66252`)
|
||||
- ⏸ `ACCEPT` — TUI 인터랙티브 입력. 사용자 판단으로 보류
|
||||
- ✗ `HBARRAY` 등 11개 HB*TYPE — 조사 결과 Harbour 내부 클래스 팩토리로,
|
||||
Five의 `SendBuiltin`이 이미 동등 기능 제공. 1.0 blocker 아님
|
||||
|
||||
### Phase C — Contrib 라이브러리 (별도 작업 예정)
|
||||
|
||||
[Five-1.0-Phase-C-TODO.md](Five-1.0-Phase-C-TODO.md) 참조. hbct (Clipper
|
||||
Tools 40개) + hbnf (재무/통계 FT_*) + hbtip (네트워크 I/O) — 약 6-10일.
|
||||
|
||||
### 성능 영역 (Phase A/B와 무관, 계속 유효)
|
||||
|
||||
- **TSqlParser2 Go 포팅**: 가장 무거운 단계. PRG Pratt 파서 → Go 재구현
|
||||
- **EvalExpr Go 네이티브화**: 현재 B4/B14/B15에서 17-20% CPU 차지. ~300-500줄 Go 포팅 + `Resolve` 등 executor 메서드 콜백 필요. 예상 10-15% 추가 수익, 리스크 높음
|
||||
- **B8 recursive CTE**: sub-executor at `nDepth>1`이 여전히 temp alias 순환 — stable alias 확장으로 커버 가능한지 미검증
|
||||
|
||||
Reference in New Issue
Block a user