five/README.md

# Five — Harbour + Go Fusion Language

**Harbour PRG 코드를 네이티브 Go 바이너리로 컴파일하는 퓨전 언어.**

30년간 축적된 Harbour/xBase 비즈니스 로직을 Go의 성능, 동시성, 크로스 플랫폼 위에서 실행합니다.

```
employees.prg  →  five build  →  employees (단일 실행파일, 18MB)
```

## 주요 특징

- Harbour 문법 100% 지원 (CLASS, CODE BLOCK, BEGIN SEQUENCE, ...)
- Go 네이티브 바이너리 출력 (CGo 없음, 순수 Go)
- DBF/NTX/CDX 데이터베이스 엔진 내장
- 479개 RTL 내장 함수
- FiveSql2: DBF 위에서 SQL:1999 쿼리 (43/43 테스트 통과)
- **pgserver**: PostgreSQL 와이어 프로토콜 v3 — psql/pgx/JDBC/DBeaver 등 모든 PG 클라이언트가 DBF 테이블에 직접 접속 (SCRAM-SHA-256, TLS, 11/11 통합 테스트 통과). 자세한 내용은 [docs/pgserver.md](docs/pgserver.md)
- Goroutine/Channel 확장 (`GO BLOCK`, `CHANNEL`)
- @byref 참조 전달, mutable closure
- 대화형 디버거 (TUI/CLI)

---

## 빌드 방법

### 1. Go 설치

Five는 Go 1.21 이상이 필요합니다.

**Linux/WSL:**
```bash
# 이미 설치되어 있는지 확인
go version

# 없으면 설치
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc
go version
```

**macOS (Apple Silicon — M1/M2/M3/M4):**
```bash
brew install go
# 또는 직접 다운로드:
wget https://go.dev/dl/go1.22.5.darwin-arm64.tar.gz
sudo tar -C /usr/local -xzf go1.22.5.darwin-arm64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.zshrc
source ~/.zshrc
```

**macOS (Intel):**
```bash
brew install go
# 또는 직접 다운로드:
wget https://go.dev/dl/go1.22.5.darwin-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.5.darwin-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.zshrc
source ~/.zshrc
```

**Windows:**
```
https://go.dev/dl/ 에서 .msi 설치
```

### 2. Five 컴파일러 빌드

```bash
git clone https://gitea.fivego.org/fivedev/five.git
cd five
go build -o five ./cmd/five
```

빌드 확인:
```bash
./five version
```

### 3. PRG 프로그램 컴파일 및 실행

**단일 파일:**
```bash
# 컴파일
./five build examples/hello.prg -o hello

# 실행
./hello
```

**다중 파일 (FiveSql2 등):**
```bash
./five build _FiveSql2/test/test_sql1999.prg _FiveSql2/src/*.prg -o test_sql
./test_sql
```

### 4. 테스트 실행

```bash
# Go 유닛 테스트
go test ./...

# FiveSql2 SQL 테스트 (43/43)
./five build _FiveSql2/test/test_sql1999.prg _FiveSql2/src/*.prg -o /tmp/test_sql
cd /tmp && ./test_sql

# Harbour 호환 테스트 (56/56)
./five build tests/compat_harbour.prg -o /tmp/test_compat
/tmp/test_compat

# std.ch 매크로 테스트 (17/17)
bash tests/std_ch/run.sh

# FRB 모듈 테스트 (7/7)
bash tests/frb/run.sh

# pgserver 통합 테스트 (11/11) — psql 필요
bash tests/pgserver/run.sh
```

---

## Five 명령어

```
five run <file.prg>              컴파일 후 즉시 실행
five build <file.prg> [-o out]   네이티브 바이너리 생성
five gen <file.prg>              생성된 Go 코드 출력 (디버깅용)
five debug <file.prg>            대화형 디버거 실행
five version                     버전 정보
```

## Hello World

```harbour
// hello.prg
PROCEDURE Main()
   ? "Hello, Five!"
   ? "Date:", Date()
   ? "Time:", Time()
RETURN
```

```bash
./five build hello.prg -o hello && ./hello
```

## SQL 예제

```harbour
// sql_demo.prg
#include "FiveSqlDef.ch"

PROCEDURE Main()
   // 테이블 생성
   five_SQL("CREATE TABLE employees (id INTEGER, name CHAR(30), salary NUMERIC(12,2))")

   // 데이터 삽입
   five_SQL("INSERT INTO employees (id, name, salary) VALUES (1, 'Alice', 8000)")
   five_SQL("INSERT INTO employees (id, name, salary) VALUES (2, 'Bob', 7000)")

   // SQL 쿼리
   LOCAL aR := five_SQL("SELECT name, salary FROM employees WHERE salary > 6000 ORDER BY salary DESC")

   ? "Results:", Len(aR[2]), "rows"
   LOCAL i
   FOR i := 1 TO Len(aR[2])
      ? "  ", aR[2][i][1], aR[2][i][2]
   NEXT
RETURN
```

```bash
./five build sql_demo.prg _FiveSql2/src/*.prg -o sql_demo && ./sql_demo
```

---

## PostgreSQL 클라이언트로 원격 접속

같은 SQL 엔진을 TCP/IP로 공개합니다. `psql`, pgx, JDBC, DBeaver, Tableau 등
모든 PostgreSQL 클라이언트가 그대로 접속합니다.

```harbour
// pg_demo.prg
#include "FiveSqlDef.ch"

PROCEDURE Main()
   USE customers SHARED NEW
   PG_ADD_ROLE( "alice", "swordfish" )
   PG_SERVER_START( ":5432", "scram-sha-256" )   /* blocks */
   RETURN
```

```bash
./five build pg_demo.prg _FiveSql2/src/*.prg -o pg_demo && ./pg_demo &
PGPASSWORD=swordfish psql 'postgres://alice@127.0.0.1:5432/alice?sslmode=disable' \
  -c "SELECT * FROM customers"
```

지원 기능: Simple + Extended Protocol, BEGIN/COMMIT/ROLLBACK, trust/password/
md5/SCRAM-SHA-256 인증, TLS, 소스 IP allowlist, pg_catalog stub (BI 도구).
**제약 및 보안 모델은 반드시 [docs/pgserver.md](docs/pgserver.md)를 확인하세요.**

---

## 프로젝트 구조

```
five/
├── cmd/five/          Five CLI (main entry point)
├── compiler/          PRG → Go 컴파일러
│   ├── lexer/         토크나이저
│   ├── parser/        구문 분석기
│   ├── analyzer/      의미 분석기
│   ├── gengo/         Go 코드 생성기
│   └── pp/            전처리기 (#include, #define)
├── hbrt/              런타임 (VM, Stack, Value, Class)
├── hbrtl/             RTL 표준 라이브러리 (479개 함수)
├── hbrdd/             RDD 데이터베이스 엔진
│   ├── dbf/           DBF 파일 드라이버
│   ├── ntx/           NTX 인덱스 드라이버
│   ├── cdx/           CDX 인덱스 드라이버
│   └── mem/           메모리 RDD
├── _FiveSql2/         SQL:1999 엔진 (PRG)
│   ├── src/           SQL 엔진 소스 (14 파일, 10,458 LOC)
│   └── test/          SQL 테스트 스위트
├── tests/             호환성 테스트
├── examples/          예제 프로그램
└── docs/              기술 문서
```

## 현재 상태

| 항목 | 수치 |
|------|------|
| Go 프로덕션 코드 | ~36,000 LOC |
| RTL 내장 함수 | 479개 |
| RDD 드라이버 | 4종 (DBF, NTX, CDX, Memory) |
| FiveSql2 테스트 | 43/43 (100%) |
| Harbour 호환 테스트 | 56/56 (100%) |
| std.ch 테스트 | 17/17 (100%) |
| FRB 테스트 | 7/7 (100%) |
| pgserver 통합 테스트 | 11/11 (100%) |
| Go 테스트 | ALL PASS |

## 라이선스

Copyright (c) 2025-2026 Charles KWON OhJun (charleskwonohjun@gmail.com)
All rights reserved.