CUE는 모든 것을 할 수 있지만, 문해력도 있나요?

I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have it, I’ll translate it into Korean while preserving the original formatting, markdown, and technical terms.

CUE – 파일 생성의 스위스‑아미 나이프 (그리고 리터러시 프로그래밍)

CUE는 다음과 같은 작업이 필요할 때 찾아 쓰는 도구입니다:

• 복잡한 JSON 생성,
• YAML 검증,
• 정수가 정말 정수인지 확인,

그리고 놀랍게도 리터러시‑프로그래밍 워크플로우가 필요할 때도.

왜 리터러시‑프로그래밍 도구가 필요할까?

현재 리터러시 프로그래밍의 “왕”은 org‑mode입니다.
Emacs 내부에서는 아주 잘 동작하지만, VS Code(또는 다른 편집기)를 사용하는 사람과 문서를 공유하려 하면 공급자 종속에 빠지게 됩니다.

문서—리터러시 코드—를 이식 가능하게 만들고 싶습니다. 한 편집기에서만 동작하는 마법 같은 것이 아니라 말이죠.

코드에 대해 글을 쓸 때(블로그 포스트, 튜토리얼, 내부 문서) 보통 하나의 거대한 파일을 내버려 두지는 않습니다. 대신에:

1. 로직의 일부를 보여줍니다.
2. 설정의 일부를 보여줍니다.
3. 필요하면 CSS 조각을 보여줍니다.

이러한 서로 다른 부분들을 prose(본문)와 함께 엮어 나갑니다.

“복사‑붙여넣기 헌사”

훌륭한 튜토리얼을 작성하고, 작동하는 코드를 Markdown 파일에 복사한 뒤, 나중에 변수(t → timeout)를 이름을 바꿉니다. 소스 코드는 수정했지만 Markdown은 수정하지 않았습니다. 독자들은 이제 깨진 코드를 복사하고, 튜토리얼은 거짓이 되며, 당신은 부실해 보입니다.

CUE는 부분을 정의하고 이를 프로그래밍적으로 엮을 수 있게 함으로써 이 문제를 해결합니다. 단순히 텍스트를 보관하는 것이 아니라, 조각들이 실제로 맞는지 검증하여 설명에 나온 코드가 최종 빌드에 사용된 코드와 정확히 일치함을 보장합니다.

마치 구조가 불안정하면 벽돌이 끼워지지 않는 레고 세트와 같습니다.¹

트리비트를 중단하기: 문서를 빌드 타깃처럼 다루기

CUE의 tool/file은 파일을 만들고, tool/exec은 명령을 실행합니다.
우리는 단순히 문자열을 템플릿화하는 것이 아니라 의존성 그래프를 정의하고 있습니다. 만약 어떤 의존성(예: 코드 조각)이 유효하지 않다면, 문서는 존재하지 않게 됩니다.

예시 1 – 동적 버전으로 마크다운 파일 생성하기

package example

import (
    "tool/file"
    "tool/exec"
)

// Build command – for every entry in the `files` struct, create a file.
command: example: {
    for k, v in files {
        "(k)": file.Create & {
            filename: k
            contents: v
        }
    }
}

// Run a shell script to obtain a version number.
data: exec.Run & {
    cmd:   ["sh", "-c", "echo '1.2.3'"]
    stdout: string
}

// Final document, stitched together.
// `(data.stdout)` is a promise that `data` will run before the string is finalized.
files: {
    "output.md": """
My Awesome Project

Current version: (data.stdout)
"""
}

CUE 없이: 1.2.3을 직접 입력해야 합니다. 나중에 버전이 1.2.4로 바뀌면, 파일은 다시 편집할 때까지 오래된 상태가 됩니다.

CUE와 함께: data.stdout이 실패하면(예: 셸 명령이 크래시) 파일이 생성되지 않고 빌드가 실패합니다 – 이는 독자를 잘못된 정보로부터 보호합니다.

빌드 실행 – cue cmd

CUE는 선언형이다: 원하는 상태를 기술하지만 스스로 변경하지는 않는다. file.Create와 exec.Run은 작업 엔진을 호출하기 전까지는 단지 데이터일 뿐이다:

cue cmd

cue cmd는 CUE에서 부작용을 허용하는 유일한 부분이다. 그것은:

1. command: 블록을 찾는다.
2. 작업을 순차적으로 실행한다.
3. “파일이 필요해” (정의)와 “여기에 파일이 있어” (현실) 사이의 간극을 메운다.

중요: cue cmd가 명령을 인식하려면 파일 이름이 _tool.cue 로 끝나야 합니다 (예: build_tool.cue). example.cue와 같이 이름을 지정하면 CUE가 명령을 완전히 무시합니다.

CUE 확장 – tool/exec 로 커스텀 렌더러 만들기

간단한 셸 명령은 장난감 예제에는 충분하지만, 실제 프로젝트에서는 더 큰 힘이 필요합니다(예: Haskell 컴파일, 다이어그램 렌더링). CUE를 사용하면 어떤 CLI 도구든 렌더러 로 쉽게 감쌀 수 있습니다.

예제 2 – 다중 언어 렌더러

package example

import (
    "tool/exec"
)

// Renderers – wrappers around CLI tools.
// Each renderer takes a `code` string and pipes it into a command.

renderers: pikchr: exec.Run & {
    cmd:    ["pikchr", "--svg-only", "-"]
    code:   string
    stdin:  code
    stdout: string
}

renderers: haskell: exec.Run & {
    cmd:    ["stack", "runghc"]
    code:   string
    stdout: string
    // Wrap the snippet in a module so it compiles standalone.
    stdin: """
module Program where
(code)
"""
}

renderers: bash: exec.Run & {
    cmd:    ["bash", "-e"]
    code:   string
    stdin:  code
    stdout: string
}

// And, because sometimes Bash isn’t hip enough…
renderers: zsh: exec.Run & {
    cmd:    ["zsh"]
    code:   string
    stdin:  code
    stdout: string
}

이렇게 하면: CUE 설정 안에 작고 맞춤형 CI 러너가 생깁니다. 이제 다음을 할 수 있습니다:

• Pikchr 다이어그램을 SVG로 렌더링합니다.
• Haskell 코드를 즉석에서 컴파일하고 실행합니다.
• Bash 또는 Zsh 스크립트를 안전하게 실행합니다.

테스트 및 CI

이제 다이어그램이나 코드 출력물을 포함하고 싶을 때, 해당 스니펫을 적절한 렌더러에 넘기기만 하면 됩니다. CUE는 셸을 호출하고, stdin을 통해 입력을 파이프하고, stdout을 캡처하는 무거운 작업을 대신 수행합니다. 문서를 살아있는 프로그램으로 바꾸어 줍니다.

가장 좋은 점은? 글을 **“테스트”**할 수 있다는 것입니다. cue cmd example을 실행하면 CUE가 실제로 셸 명령을 실행하고, Haskell을 컴파일하며, Pikchr 다이어그램을 렌더링하고, 최종 파일을 생성합니다.

• 코드 스니펫에 문법 오류가 있으면 생성이 실패합니다.
• Haskell 코드가 컴파일되지 않으면 생성이 실패합니다.
• 잘못된 좌표로 Pikchr 다이어그램을 만들려고 하면 생성이 실패합니다.

이것은 “블로그 포스트 작성”을 “CI/CD 파이프라인 통과”로 바꾸어 줍니다.

마치 매우 엄격한 컴파일러이자 교정자와 같은 존재입니다 2. 내 포스트의 모든 다이어그램이 바로 옆에 있는 코드에서 실제로 렌더링된 것임을 보장합니다—구식 이미지도 없고, 수동 내보내기도 없으며, 내가 적어두지 않은 “마법” 단계도 없습니다. 특정 편집기 생태계에 의존하지 않으며, 문서화에서 흔히 겪는 “내 컴퓨터에서는 동작한다” 문제를 효과적으로 해결합니다. 단순히 글을 쓰는 것이 아니라 텍스트를 설계하고 있는 것입니다.

혹은 레고 위에 메가블록을 놓으려는 경우. CUE는 높은 기준을 가지고 있어 구조적 선택이 부실하면 주저 없이 판단합니다. ↩

그리고 인간 교정자와 달리 CUE는 급여를 요구하지도, 커피를 다 마시지도, 과도한 말장난 사용에 대해 불평하지도 않습니다. ↩

요약

• CUE는 문서를 일류 빌드 아티팩트로 다룰 수 있게 해줍니다.
• 본문에 표시하는 코드는 실제로 실행되는 코드임이 보장됩니다.
• cue cmd를 사용하고 파일명을 *_tool.cue로 지정하면 재현 가능하고 부작용을 인식하는 파이프라인을 얻을 수 있습니다.
• tool/exec로 CUE를 확장하면 필요한 모든 언어나 도구를 래핑할 수 있어, 문학적 프로그래밍 워크플로우를 이식 가능하고 신뢰할 수 있게 유지합니다.

각주

1. “구조적으로 불안정한 것을 만들 때 브릭이 맞물리지 않는 레고 세트”는 CUE 검증의 비유입니다: 기본 조각들이 제약을 만족하지 않으면 파일을 생성하지 못하게 합니다.