# Han 언어 명세 (Han Language Specification)

> **Han (한)** — 한국어 키워드를 사용하는 범용 컴파일 프로그래밍 언어
> CLI: `hgl` | 파일 확장자: `.hgl` | 컴파일러: Rust + LLVM IR → clang

---

## 1. 개요 (Overview)

Han은 한국어 키워드를 사용하는 정적 타입 컴파일 언어입니다.
- 한국어 키워드 + 한글/영문 식별자 모두 허용
- C/Rust 스타일 구문 구조
- LLVM IR → clang을 통한 네이티브 바이너리 생성
- 범용 언어 (시스템 프로그래밍 ~ 스크립팅)

---

## 2. 키워드 (Keywords)

| 키워드 | 의미 | 영어 대응 |
|--------|------|-----------|
| `함수` | 함수 정의 | `fn` / `function` |
| `반환` | 값 반환 | `return` |
| `변수` | 가변 변수 선언 | `let mut` / `var` |
| `상수` | 불변 상수 선언 | `const` / `let` |
| `만약` | 조건문 | `if` |
| `아니면` | 조건 분기 | `else` |
| `반복` | for 반복문 | `for` |
| `동안` | while 반복문 | `while` |
| `멈춰` | 반복 중단 | `break` |
| `계속` | 다음 반복 | `continue` |
| `참` | 불리언 참 | `true` |
| `거짓` | 불리언 거짓 | `false` |
| `없음` | 빈 값 / void | `null` / `void` |
| `출력` | 표준 출력 | `print` |
| `입력` | 표준 입력 | `input` |

---

## 3. 타입 시스템 (Type System)

| 한국어 타입 | LLVM 타입 | 크기 | 설명 |
|------------|-----------|------|------|
| `정수` | `i64` | 8 bytes | 64비트 정수 |
| `실수` | `f64` | 8 bytes | 64비트 부동소수점 |
| `문자열` | `i8*` | 포인터 | UTF-8 문자열 |
| `불` | `i1` | 1 bit | 참(1) / 거짓(0) |
| `없음` | `void` | — | 반환값 없음 |

---

## 4. 문법 (Grammar — EBNF)

```ebnf
프로그램    ::= 선언*

선언        ::= 함수선언 | 변수선언 | 상수선언 | 표현식문

함수선언    ::= "함수" 식별자 "(" 매개변수목록? ")" ("->" 타입)? 블록
매개변수목록 ::= 매개변수 ("," 매개변수)*
매개변수    ::= 식별자 ":" 타입

변수선언    ::= "변수" 식별자 (":" 타입)? "=" 표현식
상수선언    ::= "상수" 식별자 (":" 타입)? "=" 표현식

블록        ::= "{" 문장* "}"

문장        ::= 변수선언
              | 상수선언
              | 반환문
              | 조건문
              | for반복문
              | while반복문
              | 멈춰문
              | 계속문
              | 표현식문

반환문      ::= "반환" 표현식?
조건문      ::= "만약" 표현식 블록 ("아니면" 블록)?
for반복문   ::= "반복" 변수선언 ";" 표현식 ";" 표현식 블록
while반복문 ::= "동안" 표현식 블록
멈춰문      ::= "멈춰"
계속문      ::= "계속"
표현식문    ::= 표현식

표현식      ::= 할당표현식
할당표현식  ::= 식별자 "=" 표현식 | 논리표현식
논리표현식  ::= 비교표현식 (("&&" | "||") 비교표현식)*
비교표현식  ::= 덧셈표현식 (("==" | "!=" | "<" | ">" | "<=" | ">=") 덧셈표현식)*
덧셈표현식  ::= 곱셈표현식 (("+" | "-") 곱셈표현식)*
곱셈표현식  ::= 단항표현식 (("*" | "/" | "%") 단항표현식)*
단항표현식  ::= ("-" | "!") 단항표현식 | 기본표현식
기본표현식  ::= 정수리터럴 | 실수리터럴 | 문자열리터럴 | 불리터럴
              | 식별자 | 함수호출 | "(" 표현식 ")"

함수호출    ::= 식별자 "(" 인자목록? ")"
인자목록    ::= 표현식 ("," 표현식)*

타입        ::= "정수" | "실수" | "문자열" | "불" | "없음"
식별자      ::= (한글문자 | 영문자 | "_") (한글문자 | 영문자 | 숫자 | "_")*
```

---

## 5. 예제 코드 (Examples)

### 5.1 Hello World
```
함수 main() -> 없음 {
    출력("안녕하세요, 세계!")
}
```

### 5.2 변수와 상수
```
변수 나이 = 20
상수 이름 = "한국"
변수 점수: 실수 = 98.5
```

### 5.3 함수 정의와 호출
```
함수 더하기(가: 정수, 나: 정수) -> 정수 {
    반환 가 + 나
}

함수 main() -> 없음 {
    변수 결과 = 더하기(3, 5)
    출력(결과)
}
```

### 5.4 조건문
```
함수 절댓값(x: 정수) -> 정수 {
    만약 x < 0 {
        반환 -x
    } 아니면 {
        반환 x
    }
}
```

### 5.5 for 반복문
```
함수 main() -> 없음 {
    반복 변수 i = 0; i < 10; i += 1 {
        출력(i)
    }
}
```

### 5.6 while 반복문
```
함수 main() -> 없음 {
    변수 n = 1
    동안 n <= 100 {
        출력(n)
        n += 1
    }
}
```

### 5.7 재귀 함수 — 피보나치
```
함수 피보나치(n: 정수) -> 정수 {
    만약 n <= 1 {
        반환 n
    }
    반환 피보나치(n - 1) + 피보나치(n - 2)
}

함수 main() -> 없음 {
    출력(피보나치(10))
}
```

### 5.8 팩토리얼
```
함수 팩토리얼(n: 정수) -> 정수 {
    만약 n <= 1 {
        반환 1
    }
    반환 n * 팩토리얼(n - 1)
}

함수 main() -> 없음 {
    출력(팩토리얼(10))
}
```

### 5.9 멈춰 / 계속
```
함수 main() -> 없음 {
    반복 변수 i = 0; i < 20; i += 1 {
        만약 i % 2 == 0 {
            계속
        }
        만약 i > 15 {
            멈춰
        }
        출력(i)
    }
}
```

### 5.10 문자열 출력
```
함수 인사(이름: 문자열) -> 없음 {
    출력("안녕하세요, ")
    출력(이름)
    출력("!")
}

함수 main() -> 없음 {
    인사("세계")
    인사("한국")
}
```

---

## 6. 연산자 (Operators)

| 연산자 | 종류 | 우선순위 |
|--------|------|---------|
| `*`, `/`, `%` | 곱셈 | 높음 |
| `+`, `-` | 덧셈 | 중간 |
| `==`, `!=`, `<`, `>`, `<=`, `>=` | 비교 | 낮음 |
| `&&` | 논리 AND | 더 낮음 |
| `\|\|` | 논리 OR | 가장 낮음 |
| `=`, `+=`, `-=`, `*=`, `/=` | 할당 | 우결합 |

---

## 7. 주석 (Comments)

```
// 한 줄 주석
// Han 언어는 현재 블록 주석을 지원하지 않습니다
```

---

## 8. 컴파일 파이프라인 (Compilation Pipeline)

```
소스코드 (.hgl)
    ↓ 렉서 (Lexer)
토큰 스트림 (Token Stream)
    ↓ 파서 (Parser)
추상 구문 트리 (AST)
    ↓ 코드 생성기 (CodeGen)
LLVM IR 텍스트 (.ll)
    ↓ clang
네이티브 바이너리
```

---

## 9. 현재 제한사항 (Current Limitations)

- 제네릭 없음
- 클래스/상속 없음 (구조체와 메서드는 지원)
- 가비지 컬렉터 없음 (현재 값/참조 기반 런타임)
- 표준 라이브러리는 V2에서 파일 I/O, JSON, HTTP, 정규식, 수학/행렬 연산까지 확장됐지만 안정화 중
