ㅎ 한글스크립트0.8 문서

자연스러운 한글 문법 확장 설계

상태: 검토 중인 제안. 아래의 새로운 문법·진단 코드·AST·Windows 어댑터는 구현되지 않았습니다. “0.9”는 우선 검토 범위를 가리키며 출시 버전이나 일정의 약속이 아닙니다. 현재 언어 버전은 루트 package.json의 0.8.0입니다.

목표와 현재의 경계

한글스크립트의 목표는 함수 이름을 한글로 바꾸는 데서 더 나아가, 익숙하고 따뜻한 문장으로 의도를 표현하는 프로그래밍 언어입니다. 표현의 선택지는 넓히되, 문장의 의미를 런타임 AI가 추측하지 않도록 합니다.

결정적 컴파일은 실행 결과가 외부 입력과 무관하게 고정된다는 뜻이 아닙니다. 소스·문법 버전·컴파일러 버전·타깃과 옵션을 고정하면 의미 AST와 생성 코드가 같아야 한다는 계약입니다. 서로 다른 동등 표현은 위치 정보를 제외한 동일 의미 AST로 정규화하며, 원문 범위와 표현 정보는 별도로 보존합니다. UI 상태·이벤트 발생 시각·사용자 입력은 실행 결과에 영향을 줄 수 있습니다.

영역 0.8에서 확인한 기반 이번 제안
문장 은/는 선언, 함수·조건·반복과 공백 들여쓰기 조사 분리·정중 표현·산술·비교 확장
식 JS 표현식, 한글 리터럴, 정해진 정렬·복사·중복 제거 표현 한국어 연산을 위한 토큰과 의미 AST
검사 TypeScript 검사기, 원본 HGS 진단 위치, 포맷 전용 AST·문법 오류 복구·문장별 진단
빌드 Node 실행, HGS 모듈 그래프, JS + .d.ts, Vite 기존 출력과 의미를 유지하는 확장
UI 데모의 "계산하기" 버튼을 누르면:과 제한된 UI 함수 외부 Windows UIA 어댑터와 명시적 대상

대조 기준은 현재 문법, src/sentences.js, src/expressions.js, 모듈·진단·자료구조·UI 테스트입니다. 현재 한글 값 표현은 임의의 산문을 허용하는 기능이 아닙니다. 전용 HGS AST와 Windows 자동화는 아직 없습니다.

목표 문장과 실행 개념

다음은 실행할 수 있는 예제가 아니라 제안 문법입니다.

지금 실행한다:
    결과는 3 더하기 8이다
    만약 결과가 7이면:
        출력("7이 맞습니다")
    아니면:
        출력("결과는", 결과)

윈도우 자동화를 사용한다
윈도우의 "계산하기" 버튼이 눌리면:
    출력("계산 버튼이 활성화됐습니다")

현재 창에서 "계산하기" 버튼을 눌러줘
  • 지금 실행한다:는 도달 시 블록을 한 번 평가하는 동기 블록 제안입니다. 자체 블록 스코프를 가지며 함수나 타이머가 아닙니다. 모듈 최상위에서는 모듈이 실행될 때 실행됩니다. 이 표기를 파일 시작에 요구하지 않습니다.
  • 만약은 조건 분기입니다. 3 + 8은 11이므로 위 예제는 결과는 11을 출력합니다.
  • 외부 버튼 이벤트는 어댑터에 구독을 등록합니다. 선언 시 본문을 즉시 실행하지 않습니다.
  • 버튼 실행 명령은 대상을 찾고 권한·지원 패턴·상태를 검사한 뒤 활성화를 요청합니다. 이벤트 구독과 다른 AST 노드입니다.

기존 데모의 "계산하기" 버튼을 누르면:는 외부 Windows 이벤트로 재해석하지 않습니다. 현재처럼 UI 브리지의 버튼 상태에 따라 전체 예제를 다시 실행하는 의미를 유지합니다.

등록된 표현만 정규화

값과 명령

표현 제안 의미
3 더하기 8, 3에 8을 더한 값, 3과 8을 더한 값, 3 + 8 숫자 덧셈식
3과 8을 더해줘 식을 평가하는 명령문. 자동 출력하지 않음
3에서 8을 빼줘 숫자 뺄셈식 평가
3 곱하기 8 숫자 곱셈식
8을 2로 나눠줘 숫자 나눗셈식 평가

값 표현은 선언·조건·다른 식에 들어가며, 해줘 명령형은 문장 위치에서만 허용하는 안을 우선합니다. 출력해줘는 출력 명령입니다. “더해줘”를 “출력해줘”로 추측해서 바꾸지 않습니다. 한국어 산술은 우선 숫자 피연산자로 제한하고, 문자열 결합은 기존 JS 식의 계약을 유지합니다. 숫자 계산은 기존 JS Number 의미를 따릅니다. 0 나눗셈·부동소수점·NaN 정책을 Python 방식으로 조용히 바꾸지 않습니다.

“3 더하기 5는?”, “1부터 10까지 다 합치면?”은 최종 목표를 설명하는 문장입니다. 질문을 자동 출력으로 처리할지는 별도 문법·부수효과 계약이 필요하며 이번 우선 범위의 확정 문법이 아닙니다.

말투와 문자열 보호

다음 출력 표현은 같은 숫자 11을 한 번 출력하는 명령으로 정규화하는 안입니다.

출력(3 + 8)
3 더하기 8을 출력해
3 더하기 8을 출력해줘
3 더하기 8을 출력해주세요
3 더하기 8을 출력해라
3 더하기 8을 출력 좀 해줘
3 더하기 8을 한 번 출력해줘!

허용 후보는 조사 은/는·이/가·을/를, 종결형 해·해줘·해주세요·해라, 정해진 출력 명령 자리의 좀·한번·한 번입니다. 문장 끝 . ! ?도 등록된 문법 자리에서만 인식합니다. 소수점, 속성 접근, !=, !==, 삼항식, 선택적 접근의 기호를 문장 부호로 지우지 않습니다. “한 번”은 해당 출력 명령의 표현이며 프로그램 전체의 반복이나 이벤트 횟수를 바꾸지 않습니다.

문자열·템플릿·주석·정규식·객체 속성 이름을 보호합니다. 출력("버튼을 눌러줘")는 문자열 출력일 뿐입니다. 식별자 내부의 조사처럼 보이는 글자를 임의로 잘라내지 않습니다. 기존 식별자와 조사 해석이 충돌하면 0.8 의미를 우선 보존하고, 구별할 수 없는 새 문장은 위치와 수정 방법을 포함한 모호성 진단으로 거절합니다.

하지 마·아마·대충·정도·쯤은 꾸밈말로 삭제하지 않습니다. 초기 확장에서는 출력하지 마를 명시적 미지원 진단으로 거절하고 실행하지 않는 정책을 택합니다. 부정문 전체 문법을 도입하기 전까지 단순한 무시나 긍정 명령으로의 변환은 금지합니다. 자유 서술 블록·프로젝트별 말투 등록은 별도 제안이며 미등록 문장을 무시하는 근거가 되지 않습니다.

3이랑 8을 적당히 계산해줘
→ HGS-N102(제안): 연산을 확정할 수 없습니다.
  제안: “3과 8을 더해줘”처럼 연산을 명시하세요.

진단의 대안 문장은 해당 문법 버전에서 실제로 지원하고 타입 검사도 통과하는 표현만 제시합니다. 아직 없는 평균 문법을 해결책으로 안내하지 않습니다. 새 N 계열 코드는 설계용이며 현재 오류 코드 계약을 대체하지 않습니다.

조건과 우선순위

기존 만약 점수 >= 80 이라면:와 JS 표현식은 유지합니다.

조건 표현 제안 정규화
A가 B이면, A가 B와 같으면 A === B
A가 B가 아니면 A !== B
A가 B보다 크면, A가 B보다 높으면 A > B
A가 B보다 작으면 A < B
A가 B 이상이면 A >= B
A가 B 이하이면 A <= B
A이고 B이면 A && B
A 또는 B이면 A || B

A·B는 설명용 메타변수입니다. 피연산자 뒤 조사와 종결형의 허용 조합은 문법 표로 따로 정의해야 하며, 이 표가 어떤 문자열이든 치환하는 규칙은 아닙니다.

만약 점수가 80 이상이면:
    출력("합격")

만약 3 더하기 8이 7이면:
    출력("참")
아니면:
    출력("거짓")

만약 이름이 "철수"가 아니면:
    출력("다른 사람")

우선순위는 괄호 → 단항 부호 → 곱셈·나눗셈 → 덧셈·뺄셈 → 비교 → 논리 AND → 논리 OR로 고정합니다. 같은 우선순위의 산술은 왼쪽부터 결합하고, AND/OR는 기존 JS처럼 단락 평가합니다. 비교 연쇄 1보다 크고 10보다 작으면은 암묵적 주어·비교 체인을 먼저 정의하지 않고 허용하지 않습니다.

3 더하기 8이 7이면의 의미는 (3 + 8) === 7입니다. 숫자 토큰 8과 조사 이를 분리하되 식별자·문자열 경계를 침범하지 않습니다. 숫자 7과 문자열 "7"을 강제로 같은 값으로 바꾸지 않습니다. 정적으로 서로 겹치지 않는 타입의 비교는 타입 오류로 진단할 수 있고, 허용된 동적 값 비교에서도 엄격 비교 의미를 유지합니다. 기존 JS의 ==를 소급해 ===로 바꾸지 않습니다.

자료 처리와 시간의 의미 계약

영역 문장 후보 검토 계약
선언 이름은 "철수"이다 기존 선언. 재대입으로 바꾸지 않음
변경 이름을 "영희"로 바꾼다 기존 변수에 대입. 선언되지 않은 이름은 오류
계산 3과 8을 더한 값 숫자 산술식
조건 만약 점수가 80 이상이면: 조건 분기
반복 1부터 10까지 반복한다: 양 끝 포함 10회. 인덱스 이름은 자동 생성해 노출하지 않음
필터 점수들 중에서 80 이상인 값 새 목록. 요소를 가리키는 범위·타입 규칙을 먼저 명세
정렬 점수들을 높은 순서로 정렬한 값 새 목록. 원본 변경은 별도 명령으로 설계
시간 3초 후에 실행한다: 실제 비동기 타이머. 취소·종료·예외 처리 계약 필요
사건 윈도우의 "저장" 버튼이 눌리면: Windows 어댑터의 이벤트 구독
검사 결과가 11인지 확인한다 조건 실패 진단. 타입 좁히기와의 연결 별도 검토

기존 범위(1, 10)은 끝 제외를 유지합니다. 새 포함 범위는 이를 그대로 호출해서 9회로 만들지 않으며 음수·소수·역방향·최대 반복 수를 별도로 명세합니다. 0.8의 정렬·복사·중복 제거 문장도 유지합니다. 원본을 정렬한다는 변경 명령을 별도로 명세할 때만 허용합니다. 지연 실행이 웹 데모의 2초 실행 제한이나 격리를 우회하지 않도록 합니다.

Windows 자동화: 독립 어댑터

Windows 어댑터는 제안 단계입니다. 브라우저 데모·일반 Node·React/Vue 연결 기능에 포함되지 않습니다. 사용 선언과 호스트 권한이 모두 있어야 하며 모듈을 선언하는 것 자체가 권한 승인을 뜻하지 않습니다. Windows 외의 호스트나 미설치 환경에서는 명확한 어댑터 오류를 내고 중단합니다.

외부 동작에는 윈도우의, 현재 창에서, "계산기" 창에서 등 대상을 명시하는 원칙을 유지합니다. 외부 사용 선언만으로 "계산하기" 버튼을 눌러줘 같은 생략 문장을 허용하지 않습니다. 기존 데모 UI 문법과 충돌하는 문법은 추가하지 않습니다.

대상 선택 규칙과 원안의 모순 해결

기본 이름 선택은 정확 일치 우선, 정확 일치가 없을 때만 포함 검색으로 결정합니다. 현재 창은 해당 명령을 시작할 때의 활성 창으로 한정하고, 다른 창으로 자동 확장하지 않습니다.

  1. 선택한 창의 Button 요소에서 정확한 접근성 이름을 찾습니다.
  2. 정확 일치가 하나면 그 요소를 선택합니다. 비활성·지원 패턴 부재는 오류이며 다른 부분 일치로 대체하지 않습니다.
  3. 정확 일치가 둘 이상이면 모호성 오류입니다.
  4. 정확 일치가 없으면 포함 이름 후보를 찾습니다. 하나일 때만 선택하고, 0개면 대상 없음, 둘 이상이면 모호성 오류입니다.
  5. 실행 직전에 창·요소 식별과 상태를 재검사합니다. 요소가 사라지거나 식별이 바뀌면 중단합니다.

따라서 “계산하기”와 “다시 계산하기”가 함께 있으면 정확한 “계산하기” 하나를 선택합니다. 둘 다 포함된다는 이유로 오류라고 했던 원안 설명은 이 정책과 맞지 않습니다. “계산하기”가 두 개면 오류입니다. “다시 계산하기”와 “빠르게 계산하기”만 있으면 포함 후보가 두 개이므로 오류입니다.

정밀 선택 문장 후보 선택 의미
현재 창에서 "계산하기" 버튼을 눌러줘 정확 일치 우선, 없으면 포함 검색
현재 창에서 이름이 "계산하기"와 같은 버튼을 눌러줘 정확 일치만
현재 창에서 이름에 "계산"이 포함된 버튼을 눌러줘 포함 검색만. 정확 이름 우선 규칙을 적용하지 않음
"계산기" 창에서 "계산하기" 버튼을 눌러줘 창부터 정확하게 하나로 확정
현재 창에서 식별자가 "submitButton"인 버튼을 눌러줘 AutomationId 정확 일치. 중복 가능성도 검사

대소문자·공백을 자동 보정하거나 첫 요소를 택하지 않습니다. 부분 검색이 맞지 않는 기능에는 정확 선택을 명시할 수 있습니다.

활성화·이벤트·권한

Microsoft UIA의 InvokePattern과 InvokedEvent를 어댑터 기반으로 검토합니다. 이는 컨트롤의 의미적 활성화와 제공자 이벤트이며, 모든 앱의 물리적 마우스 클릭을 감지한다는 뜻이 아닙니다. 앱이 지원하는 패턴을 조회해야 하고, 체크박스·선택 항목은 별도의 제어 패턴이 필요할 수 있습니다. 패턴 부재 시 임의 좌표 클릭으로 대체하지 않습니다.

윈도우의 "계산하기" 버튼이 눌리면:의 대상은 등록 시 활성 창과 요소로 확정해 구독 수명 동안 유지하는 안입니다. 창이 바뀔 때마다 다른 버튼에 다시 연결하지 않습니다. 구독 해제·창 종료·요소 소멸·대기 시간 초과·오류 전달·프로그램 종료 계약을 정의해야 합니다. 기본적으로 같은 구독 콜백의 재진입과 자기 활성화 반복을 차단하고, 종료 시 자원을 해제합니다.

호스트는 허용된 앱/창·행동·구독 수명을 제한합니다. 컴파일 시 필요한 기능을 확인하고, 실행 시 실제 권한·대상·상태를 확인합니다. 언어 문장을 썼다는 이유로 운영체제 권한을 올리거나 승인 절차를 생략하지 않습니다.

후속 후보는 입력창 값 설정, 체크박스 선택, 목록 항목 선택, 창 열림 이벤트, 제한 시간 대기, 활성 상태 검사, 단축키 전송입니다. 모두 외부 대상과 환경을 명시해야 합니다. 웹·Android·macOS 어댑터는 장래 검토 대상이며 지원 플랫폼 목록이 아닙니다.

컴파일러 구조와 도입 순서

.hgs 소스
  → 어휘 분석: 원문 범위·문자열 보호·토큰과 조사
  → 등록 문법 파싱: 표현 동등성·부정과 모호성 검사
  → HGS 의미 AST + 별도 원문/표현 정보
  → 타입 검사·호스트 기능 검사
  → 기존 JS + .d.ts 출력
  → 실행 시 호스트 권한·대상 검사
      ├─ Node / 웹의 기존 실행 경로
      └─ Windows UIA 어댑터 (별도 설치와 허용 필요)

0.8 문법과 JS 표현식의 구문 섬을 유지하면서 전용 AST로 옮깁니다. 조사·말투의 정규화는 토큰과 문법 자리 위에서 수행하며 전체 산문에 전역 정규식 치환을 적용하지 않습니다. 식·출력·선언·대입·즉시 블록·조건·이벤트 구독·UI 활성화 노드를 구분합니다. 알 수 없는 문장이나 타입 오류가 있는 실행 단위는 실행 전에 거절합니다. 파싱 실패를 기존 모드로 조용히 폴백하지 않습니다.

우선순위 검토 범위 다음 단계로 가기 위한 근거
첫 단계, 0.9 후보 토큰·AST·조사·정중 표현·숫자 사칙연산·비교·조건 기존 코드 의미 보존, 위치 진단, 연산/부정/문자열 회귀
이후, 0.10 후보 포함 범위·반복·필터·정렬·명시적 변경·비동기 시간 원본 변경·경계·평가 횟수·비동기 수명 계약
독립 후속, 0.11 후보 Windows UIA 어댑터·선택·이벤트·활성화·권한 Windows 실제 앱 통합 검사와 실패/재진입 검증
안정화, 1.0 후보 명세·호환성·마이그레이션·진단 계약 적합성 테스트와 공개된 지원 범위에 대한 릴리스 기준

이 번호는 작업 묶음의 제안이며 버전 출시를 확정하지 않습니다. 전용 AST와 회귀 검증을 먼저 갖추고, 확정한 작은 문법부터 추가합니다.

구현 시 고정할 적합성 사례

이 표는 향후 테스트 명세이며 현재 테스트 통과 목록이 아닙니다.

입력·상황 기대 계약
3 더하기 8이 7이면 / 11이면 거짓 / 참
3 더하기 8을 출력 좀 해줘 11 한 번 출력
3 더하기 8을 출력하지 마 미지원 부정문 진단, 실행하지 않음
출력("버튼을 눌러줘") 문자열만 출력, UI 동작 없음
단어가 조사로 끝나는 식별자·문자열·정규식·템플릿 원래 내용과 0.8 의미 보존
3 더하기 8 곱하기 2 / (3 더하기 8) 곱하기 2 19 / 22
AND와 OR 혼합·부수효과가 있는 오른쪽 식 고정 우선순위·단락 평가·불필요한 중복 평가 없음
숫자와 문자열 비교 암묵 변환 없음, 정적 타입 정책 적용
1부터 10까지 / 기존 범위(1, 10) 10회 / 9개 원소
새 정렬 표현 원본 불변·동점 안정성·키 계산 횟수 계약 유지
정확 이름 1개 + 부분 이름 1개 정확 이름 선택
정확 이름 2개 / 정확 이름 없이 포함 후보 2개 모호성 오류, 동작 없음
명시적 포함 검색에 후보 2개 정확 이름 유무와 무관하게 모호성 오류
버튼 없음·비활성·패턴 미지원·실행 전 소멸 각각 명확한 오류, 임의 대체 없음
어댑터 없음·호스트 권한 없음 환경/권한 오류, 동작 없음
이벤트 자기 재발동·콜백 처리 중 재활성화 기본 재진입 차단
창 종료·취소·프로그램 종료 구독/타이머 자원 정리
현재 0.8 예제·JS 표현식·모듈 출력·타입·변경 여부·예외·모듈 의미 보존

아직 결정할 세부 사항

  • 조사와 식별자가 충돌할 때의 구체적인 토큰·명시 구분 표기, 정확한 문장 종결 허용 표.
  • 자연어 질문과 값 평가 명령의 사용자 경험, 복합 필터의 주어·스코프 문법.
  • 타이머·구독의 반환값, 취소 핸들, 비동기 예외와 종료 대기 규칙.
  • 문법 버전 선택과 마이그레이션, AST 스키마 및 오류 복구 API.
  • Windows 이벤트별 지원 앱 범위, 권한 선언 형식, 런타임 진단 코드.

현재 지원 범위 · 전체 로드맵