# 한선씨 RPN 사용법 — 클로드 숙지 카드 (SSOT)

> **목적**: 클로드(모든 모델·세션)가 한선씨 RPN — 한글 단어와 띄어쓰기로, 뒤로 돌아가지 않고
> 앞으로만 진행하는 3레이어 언어 — 로 능숙하게 코딩하게 하는 단일 원본 카드.
> **모든 예제는 2026-07-07 실컴파일 검증 통과분만 수록** (`예제검증.sh`로 재검증 가능).
> 세션에서 RPN 작업 전 이 카드를 읽어라: `~/crowny-rpnkit/rpn숙련.sh 사용법`

## 0. 한 줄 정신

**값을 먼저 놓고, 동사가 뒤에 온다. 쓴 것은 지우지 않고 앞으로만 간다.**

```
3 7 더해 보여줘 끝        ; → 10
```

수학의 "3+7"이 아니라 말의 순서다: "3과 7을 더해 보여줘. 끝."
한국어 어순(목적어→동사)과 RPN(피연산자→연산자)이 정확히 일치한다 — 이것이 한선씨 RPN이 한국어 네이티브인 이유.

## 1. 두 가지 컴파일 경로 (둘 다 .toau = 4상균형3진 기계어)

| 경로 | 입력 | 컴파일러 | 용도 |
|------|------|----------|------|
| **정통(std)** | 순수 RPN 단어열 (stdin) | `hanseonc_std.toau` (자기호스팅) | 짧은 코어·교육·정본 |
| **실용(rpn)** | `.rpn.한선` 파일 | `hanseonc_rpn` (C, 125키워드) | 실전 도구 정본 (brain.sh 검증 경로) |

```bash
CC=/Users/ef/CrownyOS/crownyc
# 정통: stdin → toau → 실행
echo '3 7 더해 보여줘 끝' | $CC/crownyc run $CC/hanseonc_std.toau > /tmp/p.toau && $CC/crownyc run /tmp/p.toau
# 실용: 파일 → toau → 실행 (stderr 분리 필수! 2>&1 금지)
$CC/hanseonc_rpn 파일.rpn.한선 > /tmp/p.toau 2>/dev/null && $CC/crownyc run /tmp/p.toau
```

## 2. 값과 변수

```
5 →엑스          ; 대입: 스택 top → 변수 엑스
엑스 보여줘       ; 참조: 변수값을 스택에 올림 → 5
"안녕" →인사      ; 문자열
참 →확인          ; 3진 리터럴: 참(1) 거짓(-1) 모름(0)
```

- ⚠️ **3진 리터럴 함정 (실측)**: `거짓`·`모름`은 **실용 RPN 전용**. 정통 std에서는 둘 다 0이 된다(거짓≠-1!). std에서 거짓이 필요하면 `-1`을 직접 써라.

- 기호는 4개뿐: `→`(대입) `.`(라벨정의) `@`(라벨참조) `"`(문자열). 나머지는 전부 한글 단어+띄어쓰기.
- ⚠️ **최대 함정: 미지 단어 = 조용히 값 0인 변수.** 오타(`더헤`, `보여쥐`)는 에러가 아니라 0이 되어 결과만 틀린다. 커밋 전 반드시 `rpn숙련.sh 검사 <파일>` 린트를 돌려라.

## 3. 연산 (피연산자 먼저, 동사 나중)

```
3 7 더해         ; 10        빼 곱해 나눠(자연반올림 |r|≤|b|/2) 나머지
2 10 거듭제곱     ; 1024      루트 절댓값 반올림 내림 올림 최소 최대
3 5 작다         ; 참(1)     같다 다르다 크다 (거짓이면 -1)
참 거짓 그리고    ; Kleene 3값 논리: 그리고 또는 아닌 (모름=0 전파)
"가" "나" 문자열연결  ; "가나"    글자수 부분 포함 문자열변환 숫자변환
```

- ⚠️ **`크거나같다`·`작거나같다`는 실용 RPN 전용 (실측 2026-07-07 적대검증 적발)**: 정통 std에서는 미지단어=0이 되어 항상 거짓 취급 — 4모델 블라인드 시험에서 3모델이 동일 침몰한 함정. std에서는 `크다`/`작다`/`같다`/`다르다`만 쓰고, ≥는 `작다 아닌` 또는 경계 조정(`x n 크다`를 `x n-1 크다`로)으로 우회하라.
- ⚠️ 실용 RPN의 `글자`는 코드포인트 정수를 반환(`코드값`과 동일 opcode 343) — 1글자 문자열이 필요하면 `s i i 1 더해 부분`(후위 부분)을 써라.
- ⚠️ `"\n"` 리터럴은 역슬래시+n으로 컴파일됨 — 진짜 개행은 `10 글자변환`.

스택 조작(실용 RPN): `복사`(dup) `교환`(swap) `지움`(drop) `회전`(rot) `깊이`(depth)
```
3 복사 더해 보여줘 끝    ; → 6 (3을 복사해 3+3)
```

## 4. 제어 흐름 — 라벨과 점프 (앞으로만)

```
; 조건문: 조건이 거짓이면 라벨로 점프(아니면점프)
3 5 작다 @끝 아니면점프
"3이 5보다 작다" 보여줘
.끝 끝
```

```
; 루프 관용구 (0,1,2 출력) — 계속조건을 앞에, 거짓이면 탈출
0 →i
.루프
  i 3 작다 @끝 아니면점프
  i 보여줘
  i 1 더해 →i
  @루프 점프
.끝 끝
```

- `.이름` = 라벨 정의(그 지점의 주소), `@이름` = 라벨 주소 참조
- `@라벨 점프`(무조건) / `조건 @라벨 아니면점프`(**거짓이면** 점프 — 두 경로 공통의 유일한 조건점프)
- `가`(=점프 별칭)는 **정통 std 전용** — 실용 RPN에서는 미지단어=0이 되어 점프하지 않는다(실측: 무점프 통과).
- `조건 @라벨 만약`(**참이면** 점프)은 **실용 RPN(hanseonc_rpn) 전용** — 정통 std에는 없다(미지단어=0 함정 → 무한루프).
- ⚠️ `같으면`·`만약점프`·`불러`·`돌아`는 ISA 문서에는 있으나 **두 컴파일러 모두/일부 미지원** (실측 2026-07-07). `아니면점프`·`점프`·`호출`·`반환`만 써라.
- ⚠️ `@라벨`을 참조했는데 `.라벨` 정의가 없으면 미정의 동작 — 린트가 잡는다.

## 5. 함수 — 라벨 + 호출 + 반환

```
@본문 점프           ; 함수 정의부를 건너뛴다 (필수 관용구!)
.제곱                ; 함수 = 라벨
  →n                 ; 인자를 스택에서 pop (다중 인자는 역순으로 pop)
  n n 곱해
  반환
.본문                ; 메인 시작
4 제곱 호출 보여줘 끝  ; → 16 (정통 std 형식)
```

- 호출 형식은 **방언별로 다르다 (실측)**: 정통 std = `인자 함수이름 호출` (bare) / 실용 RPN = `인자 @함수이름 호출` (**@ 필수** — bare는 조용히 0 반환 또는 PC0 무한루프).
- ⚠️ 파일 맨 앞에 `@본문 점프` 없이 함수 정의를 두면 정의부가 그냥 실행돼 버린다.
- ⚠️ **실용 RPN은 단일패스 컴파일러**: 변수 참조가 텍스트상 `→대입`보다 앞이면(함수 본문이 메인보다 앞) 토큰째 미방출되어 스택이 오염된다. 해법 = **모든 변수를 파일 선두에서 `0 →이름` 선선언**. 함수 인자·반환값은 전역 변수 경유가 안전(스택 경유는 타입태그 소실 — 'MUL 문자' 경고는 표시성, 페이로드는 정상).
- 실용 RPN에는 `프레임시작`/`프레임끝`(지역 프레임)도 있다.

## 6. 자료구조

```
; 맵 (정통 std에서도 동작 — 재대입 필수)
맵생성 →m
m "키" 5 맵넣어 →m
m "키" 맵꺼내 보여줘 끝   ; → 5. ⚠️ 미스=-1 (맵있나로 구분)
```

```
; 배열 (실용 RPN .rpn.한선 전용) — 반드시 후위형으로
[] →목록
목록 10 추가 →목록
목록 20 추가 →목록
목록 0 원소 보여줘 끝    ; → 10
```

- ⚠️ **배열 콘텐츠 리터럴 함정 (실측)**: `[10, 20, 30]`은 컴파일은 되지만 **빈 배열**이 된다. `[]`+후위 `추가`만 신뢰.
- ⚠️ **호출식 함정 (실측)**: `추가(목록, 10)`도 컴파일은 되지만 **조용한 no-op**(빈 배열 유지). 실용 RPN에서도 후위형 `목록 10 추가 →목록`만 써라. (기존 .rpn.한선 정본 일부에 호출식 잔존 — 재검증 대상)
- 정통 std 경로에는 배열 자체가 없다(맵·문자열로 대체).
- 배열 단일 4095 캡·문자열풀 480k·읽기() 64KB 캡 — 대량 데이터는 스트리밍(메모리 함정 카드 참조).

## 7. 입출력

```
"결과: " 42 문자열변환 문자열연결 보여줘   ; 문자열+숫자는 변환 후 연결
입력 →줄                                  ; 실용 RPN 전용. ⚠️ 첫 입력 프라임리드가 첫 줄 소비
"경로" 읽기 →내용                          ; 실용 RPN 전용. ⚠️ 64KB 캡
"경로" "내용" 쓰기    "경로" "내용" 덧쓰기   ; 경로가 먼저, 후위형만
```

- ⚠️ **파일 I/O·입력은 실용 RPN(hanseonc_rpn) 전용** (실측: std에서는 쓰기가 조용히 무동작). 정통 std는 계산·문자열·맵·출력 코어로만 써라.
- ⚠️ 호출식 `쓰기("경로", 내용)`은 실용 RPN에서도 **조용한 no-op** — 모든 내장은 후위형만 신뢰.

## 8. 주석과 종료

```
; 세미콜론 줄 주석 (정통 std·실용 둘 다)
// 실용 RPN은 이중슬래시도 허용
끝              ; 프로그램 끝 — 반드시 마지막 토큰
```

## 9. 3레이어 (T→O→A)

| 레이어 | 형태 | 파일 |
|--------|------|------|
| T(한글) | RPN 한선씨 소스 | `.rpn.한선` |
| O(의미코드) | @의미코드 열 | `.3layer` 중간부 |
| A(기계어) | 4상균형3진 TOAU (T=+1 O=0 A=-1 U=구분) | `.toau` |

`high2rpn.sh --3layer 파일.한선` → 3레이어 문서. 자연어→의미어→RPN 직결은 `의미어rpn.sh` 사용.

## 10. 작성 수칙 (클로드 강제)

1. **새 로직은 RPN 직접 작성** (헌법: 자연어→RPN 직변환이 정통. 고수준은 이행보조).
2. **한 줄에 한 문장** — `값들 동사` 단위로 줄을 끊으면 스택 추적이 쉽다. 각 줄 끝의 스택 상태를 주석으로.
3. **작성 → 즉시 `rpn숙련.sh 검사 <파일>`** — 오타=조용한 0 함정은 린트만이 잡는다.
4. **통과 → `rpn숙련.sh 학습 <intent> <파일>`** — 학습DB에 RPN 정본 축적(다음부터 토큰0 재사용).
5. 모호하면 관용구를 조회: `~/.claude/scripts/crownycode-learn.sh search "<키워드>"`.

## 11. 참조

- 키워드→opcode 전표: `/Users/ef/CrownyOS/docs/HANSEON_REFERENCE.md`
- ISA729: `/Users/ef/CrownyOS/docs/ISA729_QUICK_REF.md` · TOAU 인코딩: `docs/TOAU_ENCODING.md`
- 변환 전략·규칙표: `/Users/ef/CrownyOS/crownyc/tools/RPN_CONVERSION_STRATEGY.md`
- 실전 정본 예제: `~/.claude/scripts/*.rpn.한선` (브레인 계열 13종)

## 11. 실용 RPN 함수·배열 실측 규약 (2026-07-07 의미어연결기 정본 700줄 검증분)

- **전방참조 소실**: hanseonc_rpn은 단일패스 — 함수 본문이 참조하는 변수가 텍스트상 뒤에서 처음 `→대입`되면 그 토큰은 0도 아니고 **통째로 미방출**(스택 오염). → **모든 변수를 파일 선두에서 `0 →이름` 선선언**.
- **호출은 `@라벨 호출`만**: bare 라벨명은 미지단어 → PC0 점프 무한루프. §5의 bare 호출 예제는 std 전용.
- **인자·반환값은 전역 경유**: 선선언된 전역이 함수 안에서 정상 가시(스택 경유도 동작하나 타입태그 소실로 '문자' 경고 스팸).
- **`[]`는 핸들 공유 함정**: `[] →a [] →b` 하면 a·b가 **같은 배열**. 분리 배열은 **`배열 →a`** 키워드로 생성 (실측: [] 2개 공유 확인, 배열 2개 분리 확인).
- **파일존재**: 2026-07-07 이전엔 330(파일열기)으로 오매핑 → -1 반환. 621(FILE_EXISTS)로 수리됨.
- **신규 등록 키워드**(hanseonc_rpn 2026-07-07): 사전생성/사전넣어/사전꺼내/사전있나/사전크기/사전파일적재(v11 대용량사전 875~880) · 버퍼파일읽기(874) · 버퍼바이트읽기(851) · 버퍼해제(398) · 맵있나(751).
- **대형 실증**: libs/의미어셀코어연결기.rpn.한선 — 함수 9개·버퍼 바이트스캔·O(1)사전, 고수준판과 전 수치 일치(사전 3556·연결 7327), 0.25s.