머꼬 → Python 번역기 설계: 결정 사항 정리 (option.md)

mowkow -py 가.mk → 가.py 번역 기능을 설계하며, 판단이 필요했던 갈림길과 그에 대한 선택을 정리한 문서입니다.

날짜: 2026-07-22

결정 1 — 번역의 목적 (생성된 가.py의 모습)

선택: 교육용 읽기 좋은 코드.
→ 런타임 라이브러리로 감싸는 방식이 아니라, 각 머꼬 구문을 자연스러운 Python 구문으로 번역하는 코드 생성기.

결정 2 — 첫 버전(v1) 기능 범위

선택: 핵심 + 리스트/기본자료.
→ 매크로·quasiquote(특이인용/비인용)는 v1 제외.

결정 3 — 리스트/cons 계열의 Python 표현

선택: 네이티브 Python 리스트.

결정 4 — 구현 아키텍처

선택: 접근 A.

참고 — 합의된 의미 주의사항(caveats)

교육용 가독성을 우선하면서 발생하는, 인터프리터와의 미세한 의미 차이(설계 문서에 상세 기록):

1. 0의 참/거짓: 머꼬는 0을 참으로, Python은 거짓으로 취급. 조건에 raw 정수가 오면 불일치(실제 예제는 비교 결과라 영향 적음).
2. 나눗셈: / → Python //(정수 나눗셈).
3. 읽기: (읽기) → int(input()) (정수 입력만 가정).
4. 출력 서식: 리스트 출력이 ["안녕"] 형태로, 인터프리터의 (안녕)과 다름.
5. 점쌍/비리스트 cons: 미지원 → 명확한 경고 후 해당 파일 번역 중단.

머꼬 → Python 번역 기능 (mowkow -py) 매뉴얼

이 문서는 머꼬(mowkow) 해석기의 Python 번역 기능에 대한 설명서입니다.
본 매뉴얼(doc/ManMk.pdf)의 보충 자료이며, 추후 본 매뉴얼에 통합될 수 있습니다.

1. 개요

머꼬로 작성한 프로그램(.mk)을 교육용으로 읽기 좋은 Python 코드(.py)로 자동 번역합니다.
"이 머꼬 코드는 이런 Python과 같구나"를 눈으로 확인하며 배울 수 있도록, 각 머꼬 구문을
가장 자연스러운 Python 구문으로 옮깁니다.

예를 들어 가.mk를 번역하면 가.py가 만들어집니다.

2. 사용법

mk -py 가.mk

• -py 또는 --python 옵션을 붙이면 번역 모드로 동작합니다.
• 입력 파일마다 확장자를 .py로 바꾼 파일이 같은 위치에 생성됩니다. (가.mk → 가.py)
• 여러 파일을 한 번에 줄 수 있습니다: mk -py 가.mk 나.mk
• -py를 붙이지 않으면 기존처럼 해석기(인터프리터)로 실행됩니다.

동작 규칙

• 이미 같은 이름의 .py 파일이 있으면 덮어쓰지 않고 경고만 출력합니다.
• 소스 파일이 없으면 경고를 출력하고 다음 파일로 넘어갑니다.
• 번역 중 오류가 나면 해당 파일만 건너뛰고(친절한 한글 오류 출력) 나머지 파일은 계속 번역합니다.
• 번역 모드에서는 라이브러리(library_kor.scm)를 불러오지 않습니다. 라이브러리 함수는
  아래 표에 따라 Python 관용구로 직접 번역됩니다.

생성된 파일 맨 위에는 다음과 같은 안내 주석이 붙습니다.

# 이 파일은 머꼬 소스 '가.mk'에서 자동 번역된 Python 코드입니다.
# 주의: '/'는 정수 나눗셈(//)으로, '읽기'는 int(input())으로 번역됩니다.

3. 번역 예제

3.1 덧셈 (add.mk)

머꼬:

(정의 가 (읽기))
(정의 나 (읽기))
(정의 합 (+ 가 나))
(쓰기 합)

Python (add.py):

가 = int(input())
나 = int(input())
합 = 가 + 나
print(합)

3.2 최대공약수·최소공배수 (gcd_lcm.mk)

머꼬:

(정의 (나머지 가 나)
      (- 가 (* (/ 가 나) 나)))
(정의 (최대공약수 가 나)
      (만약 (= 나 0) 가 (최대공약수 나 (나머지 가 나))))
(정의 (최소공배수 가 나)
      (/ (* 가 나) (최대공약수 가 나)))
(정의 가 (읽기))
(정의 나 (읽기))
(쓰기 (최대공약수 가 나))
(쓰기 (최소공배수 가 나))

Python (gcd_lcm.py):

def 나머지(가, 나):
    return 가 - 가 // 나 * 나

def 최대공약수(가, 나):
    if 나 == 0:
        return 가
    else:
        return 최대공약수(나, 나머지(가, 나))

def 최소공배수(가, 나):
    return 가 * 나 // 최대공약수(가, 나)

가 = int(input())
나 = int(input())
print(최대공약수(가, 나))
print(최소공배수(가, 나))

3.3 리스트와 인용 (greet.mk)

머꼬:

(정의 질문 '(이름이 뭐니?))
(쓰기 질문)
(정의 이름 (읽기))
(쓰기 (리스트 '안녕? 이름))

Python (greet.py):

질문 = ["이름이", "뭐니?"]
print(질문)
이름 = int(input())
print(["안녕?", 이름])

4. 번역 규칙

4.1 특수형 (문장 문맥)

4.2 연산자

4.3 리스트·기본 자료

4.4 표준 라이브러리 함수

머리돌기/꼬리돌기가 쓰이면 생성 파일 맨 위에 import functools 한 줄이 자동으로 추가됩니다.

4.5 식별자 변환

Python 식별자로 그대로 쓸 수 있는 한글 이름(합, 최대공약수)은 변경 없이 사용됩니다.
특수 문자가 든 이름은 다음 규칙으로 안전하게 치환됩니다.

• 숫자로 시작하는 이름은 앞에 _를 붙입니다.
• Python 예약어와 겹치면 뒤에 _를 붙입니다.
• 서로 다른 이름이 같은 결과로 겹치면 _2, _3 … 을 붙여 구분합니다.

5. 주의사항 (인터프리터와의 차이)

교육용 가독성을 우선하기 때문에, 해석기로 실행한 결과와 미세하게 다를 수 있는 부분입니다.

1. 나눗셈: /는 Python의 정수 나눗셈 //로 번역됩니다.
2. 입력: (읽기)는 int(input())로 번역됩니다(정수 입력을 가정).
3. 참/거짓: 머꼬는 0을 참으로 취급하지만 Python은 거짓으로 취급합니다.
   조건에 정수 0이 직접 오는 드문 경우 동작이 달라질 수 있습니다.
   (대부분의 조건은 비교식이라 영향이 없습니다.)
4. 리스트 출력 서식: 리스트를 출력하면 Python 형식 ["안녕"]으로 나옵니다.
   해석기의 (안녕) 표기와 다릅니다.
5. 미지원 구문: 매크로, 특이인용(quasiquote)/비인용, 점쌍((가 . 나))은 v1에서
   번역하지 않습니다. 이런 구문을 만나면 해당 파일 번역을 건너뛰고 한글 오류를 출력합니다.

6. 오류 처리

• 번역할 수 없는 구문을 만나면 소스 행 번호와 함께 한글 오류를 출력합니다.
  예: 가.mk:3: 번역 오류: 매크로는 v1에서 지원하지 않습니다.
• 인수 개수가 맞지 않는 등 그 밖의 오류도 해당 파일만 건너뛰고 계속 진행하므로,
  파일 하나가 잘못되어도 전체 번역이 중단되지 않습니다.