diff --git a/docs/Five-1.0-Phase-C-TODO.md b/docs/Five-1.0-Phase-C-TODO.md new file mode 100644 index 0000000..c79807e --- /dev/null +++ b/docs/Five-1.0-Phase-C-TODO.md @@ -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. diff --git a/docs/RTL-Go-Native-Migration.md b/docs/RTL-Go-Native-Migration.md index 0cf3449..eec6bdb 100644 --- a/docs/RTL-Go-Native-Migration.md +++ b/docs/RTL-Go-Native-Migration.md @@ -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 "" 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 확장으로 커버 가능한지 미검증