10. 유틸리티 함수

유틸리티 함수

달빛약속은 런타임 외에도 개발 도구 제작에 유용한 유틸리티 함수를 제공합니다.

dalbitToJS: 달빛 값을 JavaScript 값으로 변환

dalbitToJS 함수는 달빛약속의 ValueType을 JavaScript의 기본 타입으로 변환합니다. 약속 코드 실행 결과를 JavaScript에서 활용할 때 유용합니다.

import { dalbitToJS, YaksokSession } from '@dalbit-yaksok/core'

const session = new YaksokSession()
session.addModule(
    'main',
    `
결과 = [1, 2, 3]
`,
)

const results = await session.runModule('main')
const result = results.get('main')!

if (result.reason === 'finish') {
    const value = result.scope.getVariable('결과')
    const jsValue = dalbitToJS(value)
    console.log(jsValue) // [1, 2, 3] (JavaScript 배열)
}

변환 규칙

달빛약속 타입	JavaScript 타입
StringValue	string
NumberValue	number
BooleanValue	boolean
ListValue	unknown[] (재귀 변환)
TupleValue	unknown[] (재귀 변환)
IndexedValue	Record<string | number, unknown> (재귀 변환)
ReferenceStore	내부 참조 값
기타 ValueType	원본 그대로 반환

리스트, 튜플, 딕셔너리 등 중첩된 값은 재귀적으로 변환됩니다.

getAutocomplete: 자동완성 후보 가져오기

getAutocomplete 함수는 주어진 코드 파일에서 특정 위치의 자동완성 후보 목록을 반환합니다. 코드 에디터에서 자동완성 기능을 구현할 때 사용합니다.

import { getAutocomplete, YaksokSession } from '@dalbit-yaksok/core'

const session = new YaksokSession()
const codeFile = session.addModule(
    'main',
    `
내_변수 = 10
약속, (대상)에게 인사하기
    대상 + "님, 안녕하세요!" 보여주기

`,
)

// 유효성 검사를 먼저 수행해야 스코프 정보가 생성됩니다
session.validate('main')

// 4번째 줄, 1번째 열 위치에서의 자동완성 후보
const suggestions = getAutocomplete(codeFile, { line: 4, column: 1 })
console.log(suggestions) // ['내_변수', '(대상)에게 인사하기', ...]

동작 방식

getAutocomplete는 다음과 같은 정보를 수집하여 자동완성 후보를 제공합니다:

1. 현재 스코프의 변수: 커서 위치에서 접근 가능한 모든 변수명
2. 현재 스코프의 함수: 커서 위치에서 호출 가능한 모든 약속(함수)명
3. 부모 스코프 탐색: 중첩된 스코프의 경우 부모 스코프까지 재귀적으로 탐색
4. 모듈 식별자: 다른 모듈에서 가져올 수 있는 함수와 변수 (@모듈명 접두사 포함)

::: tip 약속 이름에 분기(/)가 포함된 경우 (예: (대상)이여/여 인사하기), 각 분기를 분리하여 여러 자동완성 후보로 확장합니다. :::

주의사항

• getAutocomplete를 호출하기 전에 반드시 session.validate()를 먼저 수행해야 합니다. 유효성 검사 과정에서 스코프 정보가 생성되기 때문입니다.
• Position은 { line: number, column: number } 형태이며, 둘 다 1부터 시작합니다.