템플릿 함수 목록

템플릿 함수 목록 (Template Function List)

헬름 템플릿에서 쓸 수 있는 함수들을 종류별로 정리한 레퍼런스 문서예요. 헬름에는 스프리그(Sprig)와 Go 템플릿 라이브러리를 기반으로 한 수많은 함수가 포함되어 있고, 여기서 논리·문자열·변환·암호화·날짜·딕셔너리·리스트·수학·리플렉션·시맨틱 버전·URL·쿠버네티스 등 다양한 범주로 나눠 소개해요.

출처: 문서

본문

⚠️ 참고: 이 페이지는 아직 헬름 4 버전으로 업데이트되지 않았어요. 일부 내용이 헬름 4와 맞지 않거나 적용되지 않을 수 있으니, 헬름 4의 새 기능·개선·호환성 깨짐에 대한 자세한 내용은 Helm 4 Overview를 확인해 주세요.

헬름에는 템플릿에서 활용할 수 있는 많은 함수가 포함되어 있어요. 이 문서에서는 그것들을 다음 범주로 나눠 설명해요.

• 논리 및 흐름 제어 (Logic and Flow Control)
• 문자열 (String)
• 타입 변환 (Type Conversion)
• 정규 표현식 (Regular Expressions)
• 암호화·보안 (Cryptographic and Security)
• 날짜 (Date)
• 딕셔너리 (Dictionary/Dict)
• 인코딩 (Encoding)
• 리스트 (List)
• 수학 (Math)
• 부동소수점 수학 (Float Math)
• 네트워크 (Network)
• 파일 경로 (File Path)
• 리플렉션 (Reflection)
• 시맨틱 버전 (Semantic Version)
• URL
• UUID
• 쿠버네티스·차트 (Kubernetes and Chart)

논리 및 흐름 제어 함수 (Logic and Flow Control Functions)

헬름에는 논리 및 흐름 제어 함수가 여러 가지 포함되어 있어요. 대표적으로 all, and, any, or, not, eq, ne, lt, le, gt, ge, default, required, empty, fail, coalesce, ternary 등이 있어요.

all

주어진 값이 모두 비어 있지 않으면(empty) true를 반환해요. 비어 있음의 정의는 default 쪽에서 쓰는 것과 같아요.

all .Arg1 .Arg2 .Arg3

and

두 개 이상 인자의 논리 AND(첫 번째 빈 인자, 또는 마지막 인자)를 반환해요.

and .Arg1 .Arg2

any

주어진 값 중 하나라도 비어 있지 않으면 true를 반환해요 (비어 있음의 정의는 default에서 쓰는 것과 같아요).

any .Arg1 .Arg2 .Arg3

or

두 개 이상 인자의 논리 OR(첫 번째 비어 있지 않은 인자, 또는 마지막 인자)를 반환해요.

or .Arg1 .Arg2

not

인자의 논리 부정(negation)을 반환해요.

not .Arg

eq

인자들의 boolean 동등성(예: Arg1 == Arg2)을 반환해요.

eq .Arg1 .Arg2

ne

인자들의 boolean 부등식(예: Arg1 != Arg2)을 반환해요.

ne .Arg1 .Arg2

lt

첫 번째 인자가 두 번째보다 작으면 true를 반환하고, 그렇지 않으면 false를 반환해요 (예: Arg1 < Arg2).

lt .Arg1 .Arg2

le

첫 번째 인자가 두 번째보다 작거나 같으면 true를 반환하고, 그렇지 않으면 false를 반환해요 (예: Arg1 <= Arg2).

le .Arg1 .Arg2

gt

첫 번째 인자가 두 번째보다 크면 true를 반환하고, 그렇지 않으면 false를 반환해요 (예: Arg1 > Arg2).

gt .Arg1 .Arg2

ge

첫 번째 인자가 두 번째보다 크거나 같으면 true를 반환하고, 그렇지 않으면 false를 반환해요 (예: Arg1 >= Arg2).

ge .Arg1 .Arg2

default

간단한 기본값을 설정하려면 default를 써요.

default "foo" .Bar

위에서 .Bar가 비어 있지 않은 값으로 평가되면 그 값이 쓰이고, 비어 있으면 foo가 대신 반환돼요.

"비어 있음(empty)"의 정의는 타입에 따라 달라요:

• 숫자(Numeric): 0
• 문자열(String): ""
• 리스트(Lists): []
• 딕셔너리(Dicts): {}
• 불리언(Boolean): false
• 그리고 항상 nil(일명 null)

구조체(struct)에는 empty의 정의가 없어서, 구조체는 결코 default를 반환하지 않아요.

required

반드시 설정해야 하는 값을 required로 지정할 수 있어요.

required "A valid foo is required!" .Bar

.Bar가 비어 있거나 정의되지 않았다면(평가 방법은 위에서 설명한 바와 같아요), 템플릿은 렌더링되지 않고 대신 제공된 오류 메시지를 반환해요.

empty

empty 함수는 주어진 값이 비어 있는 것으로 간주되면 true를, 그렇지 않으면 false를 반환해요. 비어 있는 값의 목록은 default 섹션에 나와 있어요.

empty .Foo

참고로 Go 템플릿 조건문에서는 비어 있음이 자동으로 계산돼요. 그래서 if not empty .Foo처럼 쓸 일은 거의 없고, 그냥 if .Foo라고 쓰면 돼요.

fail

조건 없이 빈 string과 지정된 텍스트를 담은 error를 반환해요. 다른 조건문들이 템플릿 렌더링을 실패시켜야 한다고 판단한 시나리오에서 유용해요.

fail "Please accept the end user license agreement"

coalesce

coalesce 함수는 값 목록을 받아 첫 번째 비어 있지 않은 값을 반환해요.

coalesce 0 1 2

위 코드는 1을 반환해요.

이 함수는 여러 변수나 값을 훑어볼 때 유용해요.

coalesce .name .parent.name "Matt"

위 코드는 먼저 .name이 비어 있는지 확인해요. 비어 있지 않으면 그 값을 반환하고, 비어 있으면 coalesce가 .parent.name의 비어 있음을 평가해요. 마지막으로 .name과 .parent.name이 모두 비어 있으면 Matt를 반환해요.

ternary

ternary 함수는 두 값과 테스트 값을 받아요. 테스트 값이 true면 첫 번째 값을, 테스트 값이 비어 있으면 두 번째 값을 반환해요. C나 다른 프로그래밍 언어의 삼항 연산자와 비슷해요.

true 테스트 값

ternary "foo" "bar" true

또는

true | ternary "foo" "bar"

위 코드는 "foo"를 반환해요.

false 테스트 값

ternary "foo" "bar" false

또는

false | ternary "foo" "bar"

위 코드는 "bar"를 반환해요.

문자열 함수 (String Functions)

헬름에는 다음 문자열 함수들이 포함되어 있어요: print, println, printf, trim, trimAll, trimPrefix, trimSuffix, lower, upper, title, untitle, repeat, substr, nospace, trunc, abbrev, abbrevboth, initials, randAlphaNum, randAlpha, randNumeric, randAscii, wrap, wrapWith, contains, hasPrefix, hasSuffix, quote, squote, cat, indent, nindent, replace, plural, snakecase, camelcase, kebabcase, swapcase, shuffle 등이 있어요.

print

여러 부분을 조합해 문자열을 반환해요.

print "Matt has " .Dogs " dogs"

문자열이 아닌 타입은 가능한 경우 문자열로 변환돼요.

참고로, 서로 인접한 두 인자가 모두 문자열이 아니면 그 사이에 공백이 추가돼요.

println

print와 똑같이 동작하지만, 끝에 새 줄(new line)을 추가해요.

printf

포맷 문자열과 그 안에 순서대로 전달할 인자들을 바탕으로 문자열을 반환해요.

printf "%s has %d dogs." .Name .NumberDogs

사용할 플레이스홀더는 전달되는 인자의 타입에 따라 달라요. 그 종류는 다음과 같아요.

일반 용도:

• %v 기본 포맷의 값

• 딕셔너리를 출력할 때는 플러스 플래그(%+v)가 필드 이름을 추가해 줘요

• %% 리터럴 퍼센트 기호; 값을 소비하지 않음

불리언:

• %t true 또는 false라는 단어

정수:

• %b 2진수

• %c 해당 유니코드 코드포인트가 나타내는 문자

• %d 10진수

• %o 8진수

• %O 0o 접두어가 붙은 8진수

• %q 안전하게 이스케이프된 단일 인용 문자 리터럴

• %x 16진수, a-f는 소문자

• %X 16진수, A-F는 대문자

• %U 유니코드 포맷: U+1234; "U+%04X"와 동일

부동소수점·복소수 구성 요소:

• %b 지수가 2의 거듭제곱인 소수 점 없는 과학적 표기, 예: -123456p-78

• %e 과학적 표기, 예: -1.234456e+78

• %E 과학적 표기, 예: -1.234456E+78

• %f 지수 없는 소수점 표기, 예: 123.456

• %F %f와 동의어

• %g 큰 지수에선 %e, 그 외엔 %f

• %G 큰 지수에선 %E, 그 외엔 %F

• %x 16진수 표기(소수 2의 거듭제곱 지수 포함), 예: -0x1.23abcp+20

• %X 대문자 16진수 표기, 예: -0X1.23ABCP+20

문자열·바이트 슬라이스(이 동사들에서는 동일하게 취급):

• %s 문자열 또는 슬라이스의 해석되지 않은 바이트

• %q 안전하게 이스케이프된 큰따옴표 문자열

• %x 16진수, 소문자, 바이트당 두 문자

• %X 16진수, 대문자, 바이트당 두 문자

슬라이스:

• %p 16진수 표기의 0번째 요소 주소, 앞에 0x가 붙음

trim

trim 함수는 문자열 양쪽의 공백을 제거해요.

trim "   hello    "

위 코드는 hello를 만들어요.

trimAll

문자열의 앞과 뒤에서 지정한 문자들을 제거해요.

trimAll "$" "$5.00"

위 코드는 5.00(문자열로)을 반환해요.

trimPrefix

문자열에서 접두어만 제거해요.

trimPrefix "-" "-hello"

위 코드는 hello를 반환해요.

trimSuffix

문자열에서 접미어만 제거해요.

trimSuffix "-" "hello-"

위 코드는 hello를 반환해요.

lower

문자열 전체를 소문자로 변환해요.

lower "HELLO"

위 코드는 hello를 반환해요.

upper

문자열 전체를 대문자로 변환해요.

upper "hello"

위 코드는 HELLO를 반환해요.

title

타이틀 케이스로 변환해요.

title "hello world"

위 코드는 Hello World를 반환해요.

untitle

타이틀 케이스를 제거해요. untitle "Hello World"는 hello world를 만들어요.

repeat

문자열을 여러 번 반복해요.

repeat 3 "hello"

위 코드는 hellohellohello를 반환해요.

substr

문자열에서 부분 문자열을 가져와요. 세 개의 매개변수를 받아요.

• start (int)
• end (int)
• string (string)

substr 0 5 "hello world"

위 코드는 hello를 반환해요.

nospace

문자열에서 모든 공백을 제거해요.

nospace "hello w o r l d"

위 코드는 helloworld를 반환해요.

trunc

문자열을 자릅니다(truncate).

trunc 5 "hello world"

위 코드는 hello를 만들어요.

trunc -5 "hello world"

위 코드는 world를 만들어요.

abbrev

줄임표(...)로 문자열을 자릅니다.

매개변수:

• 최대 길이
• 문자열

abbrev 5 "hello world"

위 코드는 he...를 반환해요. 최대 길이에 줄임표의 너비가 포함되기 때문이에요.

abbrevboth

양쪽을 모두 축약해요.

abbrevboth 5 10 "1234 5678 9123"

위 코드는 ...5678...을 만들어요.

받는 인자는:

• 왼쪽 오프셋
• 최대 길이
• 문자열

initials

여러 단어가 주어지면 각 단어의 첫 글자를 가져와 결합해요.

initials "First Try"

위 코드는 FT를 반환해요.

randAlphaNum, randAlpha, randNumeric, randAscii

이 네 함수는 암호학적으로 안전한(crypto/rand 사용) 랜덤 문자열을 생성하되, 기본 문자 집합이 각각 달라요.

• randAlphaNum은 0-9a-zA-Z 사용
• randAlpha는 a-zA-Z 사용
• randNumeric은 0-9 사용
• randAscii는 모든 출력 가능한 ASCII 문자 사용

각각 하나의 매개변수, 즉 문자열의 정수 길이를 받아요.

randNumeric 3

위 코드는 세 자리 숫자로 된 랜덤 문자열을 만들어요.

wrap

주어진 컬럼 수에서 텍스트를 줄바꿈해요.

wrap 80 $someText

위 코드는 $someText의 문자열을 80컬럼에서 줄바꿔줘요.

wrapWith

wrapWith는 wrap처럼 동작하되, 줄바꿈에 사용할 문자열을 직접 지정할 수 있어요. (wrap은 \n을 사용해요.)

wrapWith 5 "\t" "Hello World"

위 코드는 Hello World를 만들어요 (여기서 공백은 ASCII 탭 문자예요).

contains

한 문자열이 다른 문자열 안에 포함되어 있는지 검사해요.

contains "cat" "catch"

위 코드는 catch가 cat을 포함하므로 true를 반환해요.

hasPrefix and hasSuffix

hasPrefix와 hasSuffix 함수는 문자열이 주어진 접두어·접미어를 가지는지 검사해요.

hasPrefix "cat" "catch"

위 코드는 catch가 접두어 cat을 가지므로 true를 반환해요.

quote and squote

이 함수들은 문자열을 큰따옴표(quote) 또는 작은따옴표(squote)로 감싸줘요.

cat

cat 함수는 여러 문자열을 하나로 이어붙이되, 공백으로 구분해요.

cat "hello" "beautiful" "world"

위 코드는 hello beautiful world를 만들어요.

indent

indent 함수는 주어진 문자열의 모든 줄을 지정한 들여쓰기 폭만큼 들여써요. 여러 줄 문자열을 정렬할 때 유용해요.

indent 4 $lots_of_text

위 코드는 텍스트의 모든 줄을 공백 4개로 들여써요.

nindent

nindent 함수는 indent 함수와 같지만, 문자열 시작 부분에 새 줄을 추가해요.

nindent 4 $lots_of_text

위 코드는 텍스트의 모든 줄을 공백 4개로 들여쓰고 시작 부분에 새 줄을 추가해요.

replace

간단한 문자열 치환을 수행해요.

세 인자를 받아요:

• 치환할 문자열
• 치환할 대상 문자열
• 원본 문자열

"I Am Henry VIII" | replace " " "-"

위 코드는 I-Am-Henry-VIII를 만들어요.

plural

문자열을 복수형으로 만들어요.

len $fish | plural "one anchovy" "many anchovies"

위에서 문자열의 길이가 1이면 첫 번째 인자(one anchovy)가 출력되고, 그렇지 않으면 두 번째 인자(many anchovies)가 출력돼요.

인자는 다음과 같아요.

• 단수 문자열
• 복수 문자열
• 길이 정수

참고: 헬름은 현재 더 복잡한 복수화 규칙을 가진 언어를 지원하지 않아요. 그리고 0도 영어 관례상 복수로 취급돼요 (zero anchovies).

snakecase

camelCase 문자열을 snake_case로 변환해요.

snakecase "FirstName"

위 코드는 first_name을 만들어요.

camelcase

snake_case 문자열을 CamelCase로 변환해요.

camelcase "http_server"

위 코드는 HttpServer를 만들어요.

kebabcase

camelCase 문자열을 kebab-case로 변환해요.

kebabcase "FirstName"

위 코드는 first-name을 만들어요.

swapcase

단어 기반 알고리즘을 사용해 문자열의 대소문자를 서로 바꿔요.

변환 알고리즘:

• 대문자는 소문자로 변환
• 타이틀 케이스 문자는 소문자로 변환
• 공백 뒤 또는 시작에 있는 소문자는 타이틀 케이스로 변환
• 기타 소문자는 대문자로 변환
• 공백은 unicode.IsSpace(char)로 정의됨

swapcase "This Is A.Test"

위 코드는 tHIS iS a.tEST를 만들어요.

shuffle

문자열을 섞어요.

shuffle "hello"

위 코드는 hello의 글자들을 무작위로 섞어, 어쩌면 oelhl을 만들어요.

타입 변환 함수 (Type Conversion Functions)

헬름이 제공하는 타입 변환 함수는 다음과 같아요.

• atoi: 문자열을 정수로 변환해요.
• float64: float64로 변환해요.
• int: 시스템 폭의 int로 변환해요.
• int64: int64로 변환해요.
• toDecimal: 유닉스 8진수를 int64로 변환해요.
• toString: 문자열로 변환해요.
• toStrings: 리스트·슬라이스·배열을 문자열 리스트로 변환해요.
• toJson (mustToJson): 리스트·슬라이스·배열·딕셔너리·객체를 JSON으로 변환해요.
• toPrettyJson (mustToPrettyJson): 리스트·슬라이스·배열·딕셔너리·객체를 들여쓰기된 JSON으로 변환해요.
• toRawJson (mustToRawJson): 리스트·슬라이스·배열·딕셔너리·객체를 HTML 문자가 이스케이프되지 않은 JSON으로 변환해요.
• fromYaml: YAML 문자열을 객체로 변환해요.
• fromJson: JSON 문자열을 객체로 변환해요.
• fromJsonArray: JSON 배열을 리스트로 변환해요.
• toYaml: 리스트·슬라이스·배열·딕셔너리·객체를 들여쓰기된 yaml로 변환해요. 어떤 소스에서든 yaml 덩어리를 복사하는 데 쓸 수 있어요. 이 함수는 GoLang yaml.Marshal 함수와 동등해요. 자세한 문서는 https://pkg.go.dev/gopkg.in/yaml.v2#Marshal에서 볼 수 있어요.
• toYamlPretty: 리스트·슬라이스·배열·딕셔너리·객체를 들여쓰기된 yaml로 변환해요. toYaml과 같지만 리스트를 추가로 2칸 들여써요.
• toToml (mustToToml): 리스트·슬라이스·배열·딕셔너리·객체를 toml로 변환해요. 어떤 소스에서든 toml 덩어리를 복사하는 데 쓸 수 있어요.
• fromYamlArray: YAML 배열을 리스트로 변환해요.

입력 타입이 특정해야 하는 건 atoi뿐이에요. 나머지는 어떤 타입에서든 목적 타입으로 변환을 시도해요. 예를 들어 int64는 float를 int로 변환할 수 있고, 문자열도 int로 변환할 수 있어요.

toStrings

리스트 같은 컬렉션이 주어지면 문자열 슬라이스를 만들어요.

list 1 2 3 | toStrings

위 코드는 1을 "1"로, 2를 "2"로 변환한 뒤 그것들을 리스트로 반환해요.

toDecimal

유닉스 8진수 권한이 주어지면 10진수를 만들어요.

"0777" | toDecimal

위 코드는 0777을 511로 변환해 int64 값으로 반환해요.

toJson, mustToJson

toJson 함수는 항목을 JSON 문자열로 인코딩해요. 항목을 JSON으로 변환할 수 없으면 빈 문자열을 반환해요. mustToJson는 항목을 JSON으로 인코딩할 수 없을 때 오류를 반환해요.

toJson .Item

위 코드는 .Item의 JSON 문자열 표현을 반환해요.

toPrettyJson, mustToPrettyJson

toPrettyJson 함수는 항목을 예쁘게(들여쓰기된) JSON 문자열로 인코딩해요.

toPrettyJson .Item

위 코드는 .Item의 들여쓰기된 JSON 문자열 표현을 반환해요.

toRawJson, mustToRawJson

toRawJson 함수는 항목을 HTML 문자가 이스케이프되지 않은 JSON 문자열로 인코딩해요.

toRawJson .Item

위 코드는 .Item의 이스케이프되지 않은 JSON 문자열 표현을 반환해요.

fromYaml

fromYaml 함수는 YAML 문자열을 받아 템플릿에서 쓸 수 있는 객체로 반환해요.

파일 위치: yamls/person.yaml

name: Bob
age: 25
hobbies:
  - hiking
  - fishing
  - cooking

{{- $person := .Files.Get "yamls/person.yaml" | fromYaml }}
greeting: |
  Hi, my name is {{ $person.name }} and I am {{ $person.age }} years old.
  My hobbies are {{ range $person.hobbies }}{{ . }} {{ end }}.

fromJson

fromJson 함수는 JSON 문자열을 받아 템플릿에서 쓸 수 있는 객체로 반환해요.

파일 위치: jsons/person.json

{
  "name": "Bob",
  "age": 25,
  "hobbies": [
    "hiking",
    "fishing",
    "cooking"
  ]
}

{{- $person := .Files.Get "jsons/person.json" | fromJson }}
greeting: |
  Hi, my name is {{ $person.name }} and I am {{ $person.age }} years old.
  My hobbies are {{ range $person.hobbies }}{{ . }} {{ end }}.

fromJsonArray

fromJsonArray 함수는 JSON 배열을 받아 템플릿에서 쓸 수 있는 리스트로 반환해요.

파일 위치: jsons/people.json

[
 { "name": "Bob","age": 25 },
 { "name": "Ram","age": 16 }
]

{{- $people := .Files.Get "jsons/people.json" | fromJsonArray }}
{{- range $person := $people }}
greeting: |
  Hi, my name is {{ $person.name }} and I am {{ $person.age }} years old.
{{ end }}

toYaml, toYamlPretty

toYaml과 toYamlPretty 함수는 객체(리스트·슬라이스·배열·딕셔너리·객체)를 들여쓰기된 YAML 문자열로 인코딩해요.

참고로 toYamlPretty는 기능적으로 동등하지만, 리스트 요소에 추가 들여쓰기를 넣어 YAML을 출력해요.

# toYaml
- name: bob
  age: 25
  hobbies:
  - hiking
  - fishing
  - cooking

# toYamlPretty
- name: bob
  age: 25
  hobbies:
    - hiking
    - fishing
    - cooking

fromYamlArray

fromYamlArray 함수는 YAML 배열을 받아 템플릿에서 쓸 수 있는 리스트로 반환해요.

파일 위치: yamls/people.yml

- name: Bob
  age: 25
- name: Ram
  age: 16

{{- $people := .Files.Get "yamls/people.yml" | fromYamlArray }}
{{- range $person := $people }}
greeting: |
  Hi, my name is {{ $person.name }} and I am {{ $person.age }} years old.
{{ end }}

toToml, mustToToml

toToml 함수는 항목을 TOML 문자열로 인코딩해요. 항목을 TOML로 변환할 수 없으면 빈 문자열을 반환해요. mustToToml는 항목을 TOML로 인코딩할 수 없을 때 오류를 반환해요.

toToml .Item

위 코드는 .Item의 TOML 문자열 표현을 반환해요.

정규 표현식 (Regular Expressions)

헬름에는 다음 정규 표현식 함수들이 포함되어 있어요: regexMatch, mustRegexMatch, regexFindAll, mustRegexFindAll, regexFind, mustRegexFind, regexReplaceAll, mustRegexReplaceAll, regexReplaceAllLiteral, mustRegexReplaceAllLiteral, regexSplit, mustRegexSplit 등이 있어요.

regexMatch, mustRegexMatch

입력 문자열이 정규 표현식의 어떤 일치 항목이라도 포함하면 true를 반환해요.

regexMatch "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$" "[email protected]"

위 코드는 true를 만들어요.

regexMatch는 문제가 있으면 패닉(panic)을 일으키고, mustRegexMatch는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

regexFindAll, mustRegexFindAll

입력 문자열에서 정규 표현식의 모든 일치 항목의 슬라이스를 반환해요. 마지막 매개변수 n은 반환할 부분 문자열 수를 결정하며, -1은 모든 일치 항목을 반환한다는 뜻이에요.

regexFindAll "[2,4,6,8]" "123456789" -1

위 코드는 [2 4 6 8]을 만들어요.

regexFindAll은 문제가 있으면 패닉을 일으키고, mustRegexFindAll은 문제가 있으면 템플릿 엔진에 오류를 반환해요.

regexFind, mustRegexFind

입력 문자열에서 정규 표현식의 첫 번째(가장 왼쪽) 일치 항목을 반환해요.

regexFind "[a-zA-Z][1-9]" "abcd1234"

위 코드는 d1을 만들어요.

regexFind는 문제가 있으면 패닉을 일으키고, mustRegexFind는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

regexReplaceAll, mustRegexReplaceAll

입력 문자열의 복사본을 반환하되, Regexp의 일치 항목을 치환 문자열(replacement)로 교체해요. 치환 문자열 안에서 $ 기호는 Expand에서처럼 해석되어, 예를 들어 $1은 첫 번째 부분 일치(submatch)의 텍스트를 나타내요. 첫 번째 인자는 <pattern>, 두 번째는 <input>, 세 번째는 <replacement>예요.

regexReplaceAll "a(x*)b" "-ab-axxb-" "${1}W"

위 코드는 -W-xxW-를 만들어요.

regexReplaceAll은 문제가 있으면 패닉을 일으키고, mustRegexReplaceAll은 문제가 있으면 템플릿 엔진에 오류를 반환해요.

regexReplaceAllLiteral, mustRegexReplaceAllLiteral

입력 문자열의 복사본을 반환하되, Regexp의 일치 항목을 치환 문자열로 교체해요. 치환 문자열은 Expand를 사용하지 않고 직접 대체돼요. 첫 번째 인자는 <pattern>, 두 번째는 <input>, 세 번째는 <replacement>예요.

regexReplaceAllLiteral "a(x*)b" "-ab-axxb-" "${1}"

위 코드는 -${1}-${1}-를 만들어요.

regexReplaceAllLiteral은 문제가 있으면 패닉을 일으키고, mustRegexReplaceAllLiteral은 문제가 있으면 템플릿 엔진에 오류를 반환해요.

regexSplit, mustRegexSplit

입력 문자열을 식으로 구분된 부분 문자열로 나누고, 그 식 일치 항목 사이의 부분 문자열 슬라이스를 반환해요. 마지막 매개변수 n은 반환할 부분 문자열 수를 결정하며, -1은 모든 일치 항목을 반환한다는 뜻이에요.

regexSplit "z+" "pizza" -1

위 코드는 [pi a]를 만들어요.

regexSplit는 문제가 있으면 패닉을 일으키고, mustRegexSplit은 문제가 있으면 템플릿 엔진에 오류를 반환해요.

암호화·보안 함수 (Cryptographic and Security Functions)

헬름은 몇 가지 고급 암호화 함수를 제공해요: sha1sum, sha256sum, sha512sum, adler32sum, htpasswd, randBytes, derivePassword, genPrivateKey, buildCustomCert, genCA, genSelfSignedCert, genSignedCert, encryptAES, decryptAES 등이 있어요.

sha1sum

sha1sum 함수는 문자열을 받아 그 SHA1 다이제스트를 계산해요.

sha1sum "Hello world!"

sha256sum

sha256sum 함수는 문자열을 받아 그 SHA256 다이제스트를 계산해요.

sha256sum "Hello world!"

위 코드는 출력하기에 안전한 "ASCII armored" 포맷으로 SHA 256 합계를 계산해요.

sha512sum

주어진 문자열의 SHA 512 합계를 출력하기에 안전한 "ASCII armored" 포맷으로 계산해요.

sha512sum "Hello world!"

adler32sum

adler32sum 함수는 문자열을 받아 그 Adler-32 체크섬을 계산해요.

adler32sum "Hello world!"

htpasswd

htpasswd 함수는 username과 password를 받아 비밀번호의 bcrypt 해시를 생성해요. 그 결과는 Apache HTTP 서버의 기본 인증에 사용할 수 있어요.

htpasswd "myUser" "myPassword"

주의: 비밀번호를 템플릿에 직접 저장하는 것은 안전하지 않아요.

randBytes

randBytes 함수는 개수 N을 받아 암호학적으로 안전한(crypto/rand 사용) N바이트의 랜덤 시퀀스를 생성해요. 시퀀스는 base64 인코딩된 문자열로 반환돼요.

randBytes 24

derivePassword

derivePassword 함수는 공유 "마스터 비밀번호" 제약을 바탕으로 특정 비밀번호를 도출하는 데 쓸 수 있어요. 이 알고리즘은 잘 명세되어 있어요.

derivePassword 1 "long" "password" "user" "example.com"

주의: 구성 요소를 템플릿에 직접 저장하는 것은 안전하지 않은 것으로 간주돼요.

genPrivateKey

genPrivateKey 함수는 PEM 블록으로 인코딩된 새 개인 키를 생성해요.

첫 번째 매개변수로 다음 값 중 하나를 받아요.

• ecdsa: 타원 곡선 DSA 키(P256) 생성
• dsa: DSA 키(L2048N256) 생성
• rsa: RSA 4096 키 생성

buildCustomCert

buildCustomCert 함수는 인증서를 커스터마이징할 수 있게 해줘요.

다음 문자열 매개변수를 받아요:

• base64 인코딩된 PEM 포맷 인증서
• base64 인코딩된 PEM 포맷 개인 키

다음 속성을 가진 인증서 객체를 반환해요:

• Cert: PEM 인코딩된 인증서
• Key: PEM 인코딩된 개인 키

예시:

$ca := buildCustomCert "base64-encoded-ca-crt" "base64-encoded-ca-key"

참고: 반환된 객체는 genSignedCert 함수에 전달해 이 CA로 인증서를 서명하는 데 쓸 수 있어요.

genCA

genCA 함수는 새롭고 자체 서명된 x509 인증 기관(CA)을 생성해요.

다음 매개변수를 받아요:

• 주체의 공통 이름(cn)
• 인증서 유효 기간(일 단위)

다음 속성을 가진 객체를 반환해요:

• Cert: PEM 인코딩된 인증서
• Key: PEM 인코딩된 개인 키

예시:

$ca := genCA "foo-ca" 365

참고: 반환된 객체는 genSignedCert 함수에 전달해 이 CA로 인증서를 서명하는 데 쓸 수 있어요.

genSelfSignedCert

genSelfSignedCert 함수는 새롭고 자체 서명된 x509 인증서를 생성해요.

다음 매개변수를 받아요:

• 주체의 공통 이름(cn)
• 선택적 IP 목록; nil일 수 있음
• 선택적 대체 DNS 이름 목록; nil일 수 있음
• 인증서 유효 기간(일 단위)

다음 속성을 가진 객체를 반환해요:

• Cert: PEM 인코딩된 인증서
• Key: PEM 인코딩된 개인 키

예시:

$cert := genSelfSignedCert "foo.com" (list "10.0.0.1" "10.0.0.2") (list "bar.com" "bat.com") 365

genSignedCert

genSignedCert 함수는 지정된 CA가 서명한 새 x509 인증서를 생성해요.

다음 매개변수를 받아요:

• 주체의 공통 이름(cn)
• 선택적 IP 목록; nil일 수 있음
• 선택적 대체 DNS 이름 목록; nil일 수 있음
• 인증서 유효 기간(일 단위)
• CA(genCA 참조)

예시:

$ca := genCA "foo-ca" 365
$cert := genSignedCert "foo.com" (list "10.0.0.1" "10.0.0.2") (list "bar.com" "bat.com") 365 $ca

encryptAES

encryptAES 함수는 AES-256 CBC로 텍스트를 암호화하고 base64 인코딩된 문자열을 반환해요.

encryptAES "secretkey" "plaintext"

decryptAES

decryptAES 함수는 AES-256 CBC 알고리즘으로 인코딩된 base64 문자열을 받아 디코딩된 텍스트를 반환해요.

"30tEfhuJSVRhpG97XCuWgz2okj7L8vQ1s6V9zVUPeDQ=" | decryptAES "secretkey"

날짜 함수 (Date Functions)

헬름에는 템플릿에서 쓸 수 있는 날짜 함수들이 포함되어 있어요: ago, date, dateInZone, dateModify, mustDateModify, duration, durationDays, durationHours, durationMicroseconds, durationMilliseconds, durationMinutes, durationNanoseconds, durationRound, durationRoundTo, durationSeconds, durationTruncateTo, durationWeeks, htmlDate, htmlDateInZone, mustToDuration, now, toDate, mustToDate, unixEpoch 등이 있어요.

ago

ago 함수는 현재 시각으로부터의 경과 시간(duration)을 반환해요. 이제 초 단위 해상도예요.

ago .CreatedAt

time.Duration String() 포맷으로 반환해요.

2h34m7s

date

date 함수는 날짜를 포맷해요.

날짜를 연-월-일로 포맷:

now | date "2006-01-02"

Go에서 날짜 포맷은 조금 다르게 동작해요.

간단히, 이 기본 날짜를 기준으로 삼아요:

Mon Jan 2 15:04:05 MST 2006

원하는 포맷으로 적으면 돼요. 위에서 2006-01-02는 같은 날짜지만 우리가 원하는 포맷이에요.

dateInZone

date와 같지만, 시간대가 있어요.

dateInZone "2006-01-02" (now) "UTC"

dateModify, mustDateModify

dateModify는 수정값과 날짜를 받아 타임스탬프를 반환해요.

현재 시각에서 한 시간 삼십 분을 뺀다:

now | dateModify "-1.5h"

수정 포맷이 잘못되면 dateModify는 날짜를 수정하지 않고 반환해요. mustDateModify는 그럴 때 오류를 반환해요.

duration

주어진 초 수를 time.Duration으로 포맷해요.

이것은 1m35s를 반환해요.

duration "95"

durationDays

duration을 일(day) 단위의 부동소수점 숫자로 변환해요.

이것은 1.5를 반환해요.

mustToDuration "36h" | durationDays

durationHours

duration을 시간(hour) 단위의 부동소수점 숫자로 변환해요.

Go 등가: time.Duration.Hours()

이것은 1.5를 반환해요.

mustToDuration "90m" | durationHours

durationMicroseconds

duration을 마이크로초 단위의 정수로 변환해요.

Go 등가: time.Duration.Microseconds()

이것은 1000000을 반환해요.

mustToDuration "1s" | durationMicroseconds

durationMilliseconds

duration을 밀리초 단위의 정수로 변환해요.

Go 등가: time.Duration.Milliseconds()

이것은 1000을 반환해요.

mustToDuration "1s" | durationMilliseconds

durationMinutes

duration을 분 단위의 부동소수점 숫자로 변환해요.

Go 등가: time.Duration.Minutes()

이것은 1.5를 반환해요.

mustToDuration "90s" | durationMinutes

durationNanoseconds

duration을 나노초 단위의 정수로 변환해요.

Go 등가: time.Duration.Nanoseconds()

이것은 1000000을 반환해요.

mustToDuration "1ms" | durationNanoseconds

durationRound

주어진 duration을 가장 중요한 단위로 반올림해요. 문자열과 time.Duration은 duration으로 파싱되고, time.Time은 그 이후 경과 시간으로 계산돼요.

이것은 2h를 반환해요.

durationRound "2h10m5s"

이것은 3mo를 반환해요.

durationRound "2400h10m5s"

durationRoundTo

duration을 다른 duration의 가장 가까운 배수로 반올림해요. 반올림할 duration이 첫 번째 인자이고 배수가 두 번째예요.

Go 등가: time.Duration.Round()

이것은 1h20m0s를 반환해요.

durationRoundTo "1h15m30s" "10m"

이것은 2h0m0s를 반환해요.

durationRoundTo "2h29m" "1h"

durationSeconds

duration을 초 단위의 부동소수점 숫자로 변환해요.

Go 등가: time.Duration.Seconds()

이것은 90을 반환해요.

mustToDuration "1m30s" | durationSeconds

durationTruncateTo

duration을 0 방향으로 다른 duration의 배수로 잘라요(truncate). 잘라낼 duration이 첫 번째 인자이고 배수가 두 번째예요.

Go 등가: time.Duration.Truncate()

이것은 1h10m0s를 반환해요.

durationTruncateTo "1h15m30s" "10m"

이것은 2h0m0s를 반환해요.

durationTruncateTo "2h59m" "1h"

durationWeeks

duration을 주(week) 단위의 부동소수점 숫자로 변환해요.

이것은 2를 반환해요.

mustToDuration "336h" | durationWeeks

htmlDate

htmlDate 함수는 HTML 날짜 선택기 입력 필드에 넣기 위해 날짜를 포맷해요.

now | htmlDate

htmlDateInZone

htmlDate와 같지만 시간대가 있어요.

htmlDateInZone (now) "UTC"

mustToDuration

mustToDuration은 duration 비슷한 값을 time.Duration으로 파싱하고, 오류가 나면 템플릿 실패를 일으켜요.

Go 등가: time.ParseDuration, time.Duration 생성

지원되는 입력에는 Go duration 문자열(예: "2h30m"), 초로 취급되는 숫자 문자열(예: "1.5"), 초로 취급되는 숫자 값이 포함돼요.

이것은 2h30m0s를 반환해요.

mustToDuration "2h30m"

이것은 1.5s를 반환해요.

mustToDuration "1.5"

now

현재 날짜/시각이에요. 다른 날짜 함수와 함께 써요.

toDate, mustToDate

toDate는 문자열을 날짜로 변환해요. 첫 번째 인자는 날짜 레이아웃이고 두 번째는 날짜 문자열이에요. 문자열을 변환할 수 없으면 0 값을 반환해요. mustToDate는 문자열을 변환할 수 없을 때 오류를 반환해요.

문자열 날짜를 다른 포맷으로 변환하고 싶을 때(파이프 사용) 유용해요. 아래 예시는 "2017-12-31"을 "31/12/2017"로 변환해요.

toDate "2006-01-02" "2017-12-31" | date "02/01/2006"

unixEpoch

time.Time의 유닉스 에포크 이후 초 수를 반환해요.

now | unixEpoch

딕셔너리와 딕트 함수 (Dictionaries and Dict Functions)

헬름은 dict(Python의 "dictionary"에서 온 약자)라는 키/값 저장 타입을 제공해요. dict는 순서가 없는 타입이에요.

딕셔너리의 키는 문자열이어야 해요. 하지만 값은 어떤 타입이든 될 수 있고, 심지어 다른 dict나 list도 될 수 있어요.

list와 달리 dict는 불변(immutable)이 아니에요. set과 unset 함수는 딕셔너리 내용을 수정해요.

헬름은 dict를 다루기 위한 다음 함수들을 제공해요: dict, get, set, unset, hasKey, pluck, dig, merge, mustMerge, mergeOverwrite, mustMergeOverwrite, keys, pick, omit, values, deepCopy, mustDeepCopy 등이 있어요.

dict

딕셔너리 생성은 dict 함수를 호출하고 쌍 목록을 전달해 해요.

다음은 세 항목을 가진 딕셔너리를 만들어요.

$myDict := dict "name1" "value1" "name2" "value2" "name3" "value 3"

get

맵과 키가 주어지면 맵에서 값을 가져와요.

get $myDict "name1"

위 코드는 "value1"을 반환해요.

참고: 키를 찾지 못하면 이 연산은 단순히 ""을 반환해요. 오류를 만들지 않아요.

set

새 키/값 쌍을 딕셔너리에 추가하려면 set을 써요.

$_ := set $myDict "name4" "value4"

참고: set은 딕셔너리를 반환하므로(Go 템플릿 함수의 요건), 위에서처럼 $_ 할당으로 값을 받아둬야 할 수 있어요.

unset

맵과 키가 주어지면 맵에서 키를 삭제해요.

$_ := unset $myDict "name4"

set과 마찬가지로 이것은 딕셔너리를 반환해요.

참고: 키를 찾지 못하면 이 연산은 단순히 반환돼요. 오류를 만들지 않아요.

hasKey

hasKey 함수는 주어진 dict가 주어진 키를 포함하면 true를 반환해요.

hasKey $myDict "name1"

키를 찾지 못하면 false를 반환해요.

pluck

pluck 함수는 하나의 키와 여러 맵을 주고, 모든 일치 항목의 리스트를 얻을 수 있게 해줘요.

pluck "name1" $myDict $myOtherDict

위 코드는 발견된 모든 값을 담은 list([value1 otherValue1])를 반환해요.

맵에서 주어진 키를 찾지 못하면 그 맵은 리스트에 항목이 없어요(그리고 반환되는 리스트의 길이는 pluck 호출의 dict 수보다 작아요).

키가 발견됐지만 값이 빈 값이면 그 값이 삽입돼요.

헬름 템플릿의 흔한 관용구는 pluck... | first를 써서 딕셔너리 컬렉션에서 첫 번째 일치 키를 얻는 것이에요.

dig

dig 함수는 중첩된 dict 집합을 탐색하며, 값 목록에서 키를 선택해요. 해당 dict에서 키 중 하나라도 발견되지 않으면 기본값을 반환해요.

dig "user" "role" "humanName" "guest" $dict

다음과 같이 구조화된 dict가 주어지면

{
  user: {
    role: {
      humanName: "curator"
    }
  }
}

위 코드는 "curator"를 반환해요. dict에 user 필드조차 없으면 결과는 "guest"가 돼요.

Dig는 가드 절(guard clauses)을 피하고 싶을 때 매우 유용해요. 특히 Go 템플릿 패키지의 and는 단락(shortcut)하지 않기 때문이에요. 예를 들어 and a.maybeNil a.maybeNil.iNeedThis는 항상 a.maybeNil.iNeedThis를 평가하고, a에 maybeNil 필드가 없으면 패닉을 일으켜요.

dig는 파이프라이닝을 지원하기 위해 dict 인자를 마지막에 받아요. 예를 들어:

merge a b c | dig "one" "two" "three" "<missing>"

merge, mustMerge

둘 이상의 딕셔너리를 하나로 병합하되, 대상(dest) 딕셔너리에 우선권을 줘요:

다음이 주어지면:

dest:
  default: default
  overwrite: me
  key: true

src:
  overwrite: overwritten
  key: false

결과는:

newdict:
  default: default
  overwrite: me
  key: true

$newdict := merge $dest $source1 $source2

이것은 깊은 병합(deep merge) 연산이지만 깊은 복사(deep copy) 연산은 아니에요. 병합되는 중첩 객체는 두 dict에서 같은 인스턴스예요. 병합과 함께 깊은 복사를 원하면 deepCopy 함수를 병합과 함께 써요. 예를 들어,

deepCopy $source | merge $dest

mustMerge는 병합이 실패하면 오류를 반환해요.

mergeOverwrite, mustMergeOverwrite

둘 이상의 딕셔너리를 하나로 병합하되, 오른쪽에서 왼쪽으로 우선권을 줘서 대상 딕셔너리의 값에 효과적으로 덮어써요:

다음이 주어지면:

dest:
  default: default
  overwrite: me
  key: true

src:
  overwrite: overwritten
  key: false

결과는:

newdict:
  default: default
  overwrite: overwritten
  key: false

$newdict := mergeOverwrite $dest $source1 $source2

이것은 깊은 병합 연산이지만 깊은 복사 연산은 아니에요. 병합되는 중첩 객체는 두 dict에서 같은 인스턴스예요. 병합과 함께 깊은 복사를 원하면 deepCopy 함수를 병합과 함께 써요. 예를 들어,

deepCopy $source | mergeOverwrite $dest

mustMergeOverwrite는 병합이 실패하면 오류를 반환해요.

keys

keys 함수는 하나 이상의 dict 타입의 모든 키의 list를 반환해요. 딕셔너리는 순서가 없으므로 키는 예측 가능한 순서가 아니에요. sortAlpha로 정렬할 수 있어요.

keys $myDict | sortAlpha

여러 딕셔너리를 제공하면 키가 이어붙여져요. uniq 함수를 sortAlpha와 함께 써서 고유하고 정렬된 키 목록을 얻어요.

keys $myDict $myOtherDict | uniq | sortAlpha

pick

pick 함수는 딕셔너리에서 주어진 키들만 선택해 새 dict를 만들어요.

$new := pick $myDict "name1" "name2"

위 코드는 {name1: value1, name2: value2}를 반환해요.

omit

omit 함수는 pick과 비슷하지만, 주어진 키들과 일치하지 않는 모든 키를 가진 새 dict를 반환해요.

$new := omit $myDict "name1" "name3"

위 코드는 {name2: value2}를 반환해요.

values

values 함수는 keys와 비슷하지만, 원본 dict의 모든 값을 가진 새 list를 반환해요(하나의 딕셔너리만 지원돼요).

$vals := values $myDict

위 코드는 list["value1", "value2", "value 3"]를 반환해요. 참고로 values 함수는 결과 순서에 대해 보장하지 않아요. 순서가 중요하면 sortAlpha를 써요.

deepCopy, mustDeepCopy

deepCopy와 mustDeepCopy 함수는 값을 받아 값의 깊은 복사를 만들어요. dict와 다른 구조체를 포함해요. deepCopy는 문제가 있으면 패닉을 일으키고, mustDeepCopy는 오류가 있으면 템플릿 시스템에 오류를 반환해요.

dict "a" 1 "b" 2 | deepCopy

Dict 내부에 대한 참고 (A Note on Dict Internals)

dict는 Go에서 map[string]interface{}로 구현돼요. Go 개발자는 map[string]interface{} 값을 컨텍스트에 전달해 템플릿에서 dict로 사용할 수 있게 할 수 있어요.

인코딩 함수 (Encoding Functions)

헬름에는 다음 인코딩·디코딩 함수가 있어요.

• b64enc/b64dec: Base64로 인코딩 또는 디코딩
• b32enc/b32dec: Base32로 인코딩 또는 디코딩

리스트와 리스트 함수 (Lists and List Functions)

헬름은 임의의 순차 데이터를 담을 수 있는 간단한 list 타입을 제공해요. 배열이나 슬라이스와 비슷하지만, 리스트는 불변 데이터 타입으로 사용하도록 설계됐어요.

정수 리스트 만들기:

$myList := list 1 2 3 4 5

위 코드는 [1 2 3 4 5] 리스트를 만들어요.

헬름은 다음 리스트 함수들을 제공해요: first, mustFirst, rest, mustRest, last, mustLast, initial, mustInitial, append, mustAppend, prepend, mustPrepend, concat, reverse, mustReverse, uniq, mustUniq, without, mustWithout, has, mustHas, compact, mustCompact, index, slice, mustSlice, until, untilStep, seq, chunk 등이 있어요.

first, mustFirst

리스트의 머리 항목을 얻으려면 first를 써요.

first $myList는 1을 반환해요.

first는 문제가 있으면 패닉을 일으키고, mustFirst는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

rest, mustRest

리스트의 꼬리(첫 항목을 제외한 나머지)를 얻으려면 rest를 써요.

rest $myList는 [2 3 4 5]를 반환해요.

rest는 문제가 있으면 패닉을 일으키고, mustRest는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

last, mustLast

리스트의 마지막 항목을 얻으려면 last를 써요.

last $myList는 5를 반환해요. 이는 대략 리스트를 뒤집고 first를 호출하는 것과 유사해요.

initial, mustInitial

이것은 last를 보완해 마지막 요소를 제외한 모든 것을 반환해요. initial $myList는 [1 2 3 4]를 반환해요.

initial은 문제가 있으면 패닉을 일으키고, mustInitial은 문제가 있으면 템플릿 엔진에 오류를 반환해요.

append, mustAppend

기존 리스트에 새 항목을 추가해 새 리스트를 만들어요.

$new = append $myList 6

위 코드는 $new를 [1 2 3 4 5 6]으로 설정해요. $myList는 그대로 유지돼요.

append는 문제가 있으면 패닉을 일으키고, mustAppend는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

prepend, mustPrepend

리스트 앞에 요소를 밀어 넣어 새 리스트를 만들어요.

prepend $myList 0

위 코드는 [0 1 2 3 4 5]를 만들어요. $myList는 그대로 유지돼요.

prepend는 문제가 있으면 패닉을 일으키고, mustPrepend는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

concat

임의 개수의 리스트를 하나로 이어붙여요.

concat $myList ( list 6 7 ) ( list 8 )

위 코드는 [1 2 3 4 5 6 7 8]을 만들어요. $myList는 그대로 유지돼요.

reverse, mustReverse

주어진 리스트의 요소를 뒤집은 새 리스트를 만들어요.

reverse $myList

위 코드는 [5 4 3 2 1] 리스트를 생성해요.

reverse는 문제가 있으면 패닉을 일으키고, mustReverse는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

uniq, mustUniq

중복을 모두 제거한 리스트를 생성해요.

list 1 1 1 2 | uniq

위 코드는 [1 2]를 만들어요.

uniq는 문제가 있으면 패닉을 일으키고, mustUniq는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

without, mustWithout

without 함수는 리스트에서 항목들을 걸러내요.

without $myList 3

위 코드는 [1 2 4 5]를 만들어요.

without는 둘 이상의 필터를 받을 수 있어요.

without $myList 1 3 5

그러면 [2 4]가 만들어져요.

without는 문제가 있으면 패닉을 일으키고, mustWithout는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

has, mustHas

리스트에 특정 요소가 있는지 검사해요.

has 4 $myList

위 코드는 true를 반환하고, has "hello" $myList는 false를 반환해요.

has는 문제가 있으면 패닉을 일으키고, mustHas는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

compact, mustCompact

리스트를 받아 빈 값이 있는 항목을 제거해요.

$list := list 1 "a" "foo" ""
$copy := compact $list

compact는 빈(즉, "") 항목이 제거된 새 리스트를 반환해요.

compact는 문제가 있으면 패닉을 일으키고 mustCompact는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

index

리스트의 n번째 요소를 얻으려면 index list [n]을 써요. 다차원 리스트로 인덱싱하려면 index list [n] [m] ...을 써요.

• index $myList 0은 1을 반환해요. myList[0]과 같아요.
• index $myList 0 1은 myList[0][1]과 같아요.

slice, mustSlice

리스트의 부분 요소를 얻으려면 slice list [n] [m]을 써요. list[n:m]과 동등해요.

• slice $myList는 [1 2 3 4 5]를 반환해요. myList[:]와 같아요.
• slice $myList 3은 [4 5]를 반환해요. myList[3:]과 같아요.
• slice $myList 1 3은 [2 3]을 반환해요. myList[1:3]과 같아요.
• slice $myList 0 3은 [1 2 3]을 반환해요. myList[:3]과 같아요.

slice는 문제가 있으면 패닉을 일으키고, mustSlice는 문제가 있으면 템플릿 엔진에 오류를 반환해요.

until

until 함수는 정수 범위를 만들어요.

until 5

위 코드는 [0, 1, 2, 3, 4] 리스트를 생성해요.

이것은 range $i, $e := until 5로 반복할 때 유용해요.

untilStep

until처럼 untilStep은 세는 정수 리스트를 생성해요. 하지만 시작·끝·단계를 정의할 수 있어요.

untilStep 3 6 2

위 코드는 3에서 시작해 6과 같거나 커질 때까지 2를 더해 [3 5]를 만들어요. Python의 range 함수와 비슷해요.

seq

bash seq 명령처럼 동작해요.

• 1개 매개변수 (end) - 1과 end 사이(포함)의 모든 세는 정수를 생성해요.
• 2개 매개변수 (start, end) - start와 end 사이(포함)의 모든 세는 정수를 1씩 증가·감소하며 생성해요.
• 3개 매개변수 (start, step, end) - start와 end 사이(포함)의 모든 세는 정수를 step씩 증가·감소하며 생성해요.

seq 5       => 1 2 3 4 5
seq -3      => 1 0 -1 -2 -3
seq 0 2     => 0 1 2
seq 2 -2    => 2 1 0 -1 -2
seq 0 2 10  => 0 2 4 6 8 10
seq 0 -2 -5 => 0 -2 -4

chunk

리스트를 주어진 크기의 덩어리로 나누려면 chunk size list를 써요. 페이지네이션에 유용해요.

chunk 3 (list 1 2 3 4 5 6 7 8)

이것은 리스트의 리스트 [ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 ] ]를 만들어요.

수학 함수 (Math Functions)

특별히 명시되지 않는 한 모든 수학 함수는 int64 값에 대해 동작해요.

다음 수학 함수들을 사용할 수 있어요: add, add1, sub, div, mod, mul, max, min, len, randInt 등이 있어요.

add

add로 숫자를 더해요. 두 개 이상의 입력을 받아요.

add 1 2 3

add1

1씩 증가하려면 add1을 써요.

sub

빼려면 sub를 써요.

div

정수 나눗셈은 div로 해요.

mod

나머지는 mod로 해요.

mul

mul로 곱해요. 두 개 이상의 입력을 받아요.

mul 1 2 3

max

일련의 정수 중 가장 큰 값을 반환해요.

이것은 3을 반환해요.

max 1 2 3

min

일련의 정수 중 가장 작은 값을 반환해요.

min 1 2 3은 1을 반환해요.

len

인자의 길이를 정수로 반환해요.

len .Arg

randInt

min(포함)부터 max(제외) 사이의 랜덤 정수 값을 반환해요.

randInt 12 30

위 코드는 12와 29 사이의 랜덤 정수를 반환해요.

부동소수점 수학 함수 (Float Math Functions)

모든 수학 함수는 float64 값에 대해 동작해요.

addf

addf로 숫자를 더해요.

이것은 5.5를 반환해요:

addf 1.5 2 2

add1f

1씩 증가하려면 add1f를 써요.

subf

빼려면 subf를 써요.

이것은 7.5 - 2 - 3과 같고 2.5를 반환해요:

subf 7.5 2 3

divf

정수 나눗셈은 divf로 해요.

이것은 10 / 2 / 4와 같고 1.25를 반환해요:

divf 10 2 4

mulf

mulf로 곱해요.

이것은 6을 반환해요:

mulf 1.5 2 2

maxf

일련의 float 중 가장 큰 값을 반환해요:

이것은 3을 반환해요:

maxf 1 2.5 3

minf

일련의 float 중 가장 작은 값을 반환해요.

이것은 1.5를 반환해요:

minf 1.5 2 3

floor

입력 값보다 작거나 같은 최대 float 값을 반환해요.

floor 123.9999는 123.0을 반환해요.

ceil

입력 값보다 크거나 같은 최소 float 값을 반환해요.

ceil 123.001은 124.0을 반환해요.

round

소수점 이하 주어진 자릿수로 나머지를 반올림한 float 값을 반환해요.

round 123.555555 3은 123.556을 반환해요.

네트워크 함수 (Network Functions)

헬름에는 getHostByName이라는 단일 네트워크 함수가 있어요.

getHostByName은 도메인 이름을 받아 IP 주소를 반환해요.

getHostByName "www.google.com"은 www.google.com의 해당 IP 주소를 반환해요.

이 함수는 helm 명령줄에 --enable-dns 옵션을 전달해야 해요.

파일 경로 함수 (File Path Functions)

헬름 템플릿 함수는 파일 시스템에 대한 접근을 제공하진 않지만, 파일 경로 규칙을 따르는 문자열을 다루는 함수들은 제공해요. 여기에는 base, dir, clean, ext, isAbs 등이 있어요.

base

경로의 마지막 요소를 반환해요.

base "foo/bar/baz"

위 코드는 "baz"를 출력해요.

dir

경로의 마지막 부분을 제거한 디렉터리를 반환해요. 그래서 dir "foo/bar/baz"는 foo/bar를 반환해요.

clean

경로를 정리해요.

clean "foo/bar/../baz"

위 코드는 ..을 해석해 foo/baz를 반환해요.

ext

파일 확장자를 반환해요.

ext "foo.bar"

위 코드는 .bar를 반환해요.

isAbs

파일 경로가 절대 경로인지 확인하려면 isAbs를 써요.

리플렉션 함수 (Reflection Functions)

헬름은 기초적인 리플렉션 도구를 제공해요. 고급 템플릿 개발자가 특정 값의 기저 Go 타입 정보를 이해하도록 돕죠. 헬름은 Go로 작성되었고 강타입(strongly typed)이에요. 타입 시스템은 템플릿 안에서도 적용돼요.

Go에는 string, slice, int64, bool 같은 여러 원시 *종류(kind)*가 있어요.

Go에는 개발자가 자신만의 타입을 만들 수 있는 개방형 타입(type) 시스템이 있어요.

헬름은 각각에 대해 kindOf/kindIs와 typeOf/typeIs/typeIsLike 함수 집합을 제공해요. 또한 두 값을 비교하는 함수도 제공해요.

종류 함수 (Kind Functions)

두 개의 Kind 함수가 있어요: kindOf는 객체의 종류를 반환해요.

kindOf "hello"

위 코드는 string을 반환해요. 간단한 테스트(if 블록 같은)에서는 kindIs 함수로 값이 특정 종류인지 확인할 수 있어요.

kindIs "int" 123

위 코드는 true를 반환해요.

타입 함수 (Type Functions)

타입은 다루기가 조금 더 까다로워서 세 가지 함수가 있어요.

• typeOf는 값의 기저 타입을 반환해요: typeOf $foo
• typeIs는 kindIs와 비슷하되 타입용이에요: typeIs "*io.Buffer" $myVal
• typeIsLike는 typeIs처럼 동작하되, 포인터를 추가로 역참조(dereference)해요

참고: 이들 중 어느 것도 어떤 것이 주어진 인터페이스를 구현하는지 검사할 수 없어요. 그러려면 인터페이스를 미리 컴파일해야 하기 때문이에요.

deepEqual

deepEqual은 두 값이 "깊이 동일"하면 true를 반환해요.

비원시 타입에서도 동작해요(내장 eq와 비교해 볼 때).

deepEqual (list 1 2 3) (list 1 2 3)

위 코드는 true를 반환해요.

시맨틱 버전 함수 (Semantic Version Functions)

어떤 버전 체계는 쉽게 파싱하고 비교할 수 있어요. 헬름은 SemVer 2 버전을 다루는 함수를 제공해요. 여기에는 semver와 semverCompare가 포함돼요. 아래에서 범위를 비교하는 방법에 대한 자세한 내용도 찾을 수 있어요.

semver

semver 함수는 문자열을 시맨틱 버전으로 파싱해요.

$version := semver "1.2.3-alpha.1+123"

파서가 실패하면 템플릿 실행이 오류로 중단돼요.

이 시점에서 $version은 다음 속성을 가진 Version 객체의 포인터예요.

• $version.Major: 주 버전(1 위 예시)
• $version.Minor: 부 버전(2 위 예시)
• $version.Patch: 패치 버전(3 위 예시)
• $version.Prerelease: 프리릴리스(alpha.1 위 예시)
• $version.Metadata: 빌드 메타데이터(123 위 예시)
• $version.Original: 원래 버전(문자열)

추가로, Compare 함수를 사용해 Version을 다른 version과 비교할 수 있어요.

semver "1.4.3" | (semver "1.2.3").Compare

위 코드는 -1을 반환해요.

반환 값은:

• -1: 주어진 semver가 Compare 메서드를 호출한 semver보다 크면
• 1: Compare 함수를 호출한 버전이 더 크면
• 0: 두 버전이 같으면

(참고: SemVer에서는 버전 비교 연산 중에 Metadata 필드는 비교되지 않아요.)

semverCompare

더 강력한 비교 함수는 semverCompare로 제공돼요. 이 버전은 버전 범위를 지원해요.

• semverCompare "1.2.3" "1.2.3"은 정확히 일치하는지 확인해요.
• semverCompare "~1.2.0" "1.2.3"은 주·부 버전이 일치하고 두 번째 버전의 패치 번호가 첫 번째 매개변수보다 크거나 같은지 확인해요.

SemVer 함수들은 Sprig 제작자가 만든 Masterminds semver 라이브러리를 사용해요.

기본 비교 (Basic Comparisons)

비교에는 두 가지 요소가 있어요. 첫째, 비교 문자열은 공백이나 쉼표로 구분된 AND 비교 목록이에요. 이것들은 다시 || (OR) 비교로 구분돼요. 예를 들어, ">= 1.2 < 3.0.0 || >= 4.2.3"은 1.2보다 크거나 같고 3.0.0보다 작거나, 4.2.3보다 크거나 같은 비교를 찾는 거예요.

기본 비교는:

• =: 같음 (연산자 없음과 동일)
• !=: 같지 않음
• >: 큼
• <: 작음
• >=: 크거나 같음
• <=: 작거나 같음

프리릴리스 버전 다루기 (Working With Prerelease Versions)

프리릴리스에 익숙하지 않은 분들을 위해, 프리릴리스는 안정적이거나 일반 공개 이전의 소프트웨어 릴리스에 사용돼요. 프리릴리스의 예로는 개발, 알파, 베타, 릴리스 후보 릴리스가 있어요. 프리릴리스는 1.2.3-beta.1 같은 버전일 수 있고, 안정 릴리스는 1.2.3이에요. 우선순위 순서상 프리릴리스는 관련 릴리스보다 앞에 와요. 이 예에서 1.2.3-beta.1 < 1.2.3이에요.

시맨틱 버전 명세에 따르면 프리릴리스는 그에 대응하는 릴리스와 API 호환이 안 될 수 있어요. 명세는 다음과 같이 말해요.

프리릴리스 버전은 버전이 불안정하고 관련 일반 버전이 나타내는 의도된 호환성 요구사항을 충족하지 못할 수 있음을 나타낸다.

프리릴리스 비교자를 사용하지 않는 제약의 SemVer 비교는 프리릴리스 버전을 건너뛰어요. 예를 들어, >=1.2.3은 릴리스 목록을 볼 때 프리릴리스를 건너뛰는 반면, >=1.2.3-0은 평가해 프리릴리스를 찾아요.

예시 비교에서 프리릴리스 버전으로 0을 쓰는 이유는, 명세상 프리릴리스는 ASCII 영숫자와 하이픈(. 구분자 포함)만 포함할 수 있기 때문이에요. 정렬은 명세대로 ASCII 정렬 순서로 이뤄져요. ASCII 정렬 순서에서 가장 낮은 문자는 0이에요(ASCII 표 참조).

ASCII 정렬 순서를 이해하는 것이 중요한 이유는 A-Z가 a-z보다 앞에 오기 때문이에요. 즉 >=1.2.3-BETA는 1.2.3-alpha를 반환해요. 대소문자 민감성에서 기대할 수 있는 것과는 달라요. 이는 명세가 지정한 ASCII 정렬 순서 때문이에요.

하이픈 범위 비교 (Hyphen Range Comparisons)

범위를 처리하는 방법은 여러 가지가 있는데, 첫 번째는 하이픈 범위예요. 다음과 같이 생겼어요.

• 1.2 - 1.4.5은 >= 1.2 <= 1.4.5와 동등해요.
• 2.3.4 - 4.5는 >= 2.3.4 <= 4.5와 동등해요.

비교에서의 와일드카드 (Wildcards In Comparisons)

x, X, * 문자를 와일드카드 문자로 쓸 수 있어요. 모든 비교 연산자에 적용돼요. = 연산자에 쓰면 패치 수준 비교로 대체돼요(아래 틸드 참조). 예를 들어,

• 1.2.x는 >= 1.2.0, < 1.3.0과 동등해요.
• >= 1.2.x는 >= 1.2.0과 동등해요.
• <= 2.x는 < 3과 동등해요.
• *는 >= 0.0.0과 동등해요.

틸드 범위 비교 (패치) (Tilde Range Comparisons - Patch)

틸드(~) 비교 연산자는 부 버전이 지정되면 패치 수준 범위용이고, 부 버전이 없으면 주 수준 변경용이에요. 예를 들어,

• ~1.2.3은 >= 1.2.3, < 1.3.0과 동등해요.
• ~1은 >= 1, < 2와 동등해요.
• ~2.3은 >= 2.3, < 2.4와 동등해요.
• ~1.2.x는 >= 1.2.0, < 1.3.0과 동등해요.
• ~1.x는 >= 1, < 2와 동등해요.

캐럿 범위 비교 (주) (Caret Range Comparisons - Major)

캐럿(^) 비교 연산자는 안정(1.0.0) 릴리스가 발생한 뒤의 주 수준 변경용이에요. 1.0.0 이전 릴리스에서는 부 버전이 API 안정성 수준 역할을 해요. API 버전을 비교할 때 주 변경이 API를 깨는 경우 유용해요. 예를 들어,

• ^1.2.3은 >= 1.2.3, < 2.0.0과 동등해요.
• ^1.2.x는 >= 1.2.0, < 2.0.0과 동등해요.
• ^2.3은 >= 2.3, < 3과 동등해요.
• ^2.x는 >= 2.0.0, < 3과 동등해요.
• ^0.2.3은 >=0.2.3 <0.3.0과 동등해요.
• ^0.2는 >=0.2.0 <0.3.0과 동등해요.
• ^0.0.3은 >=0.0.3 <0.0.4와 동등해요.
• ^0.0은 >=0.0.0 <0.1.0과 동등해요.
• ^0은 >=0.0.0 <1.0.0과 동등해요.

URL 함수 (URL Functions)

헬름에는 URL 부분을 다루게 해주는 urlParse, urlJoin, urlquery 함수가 포함돼 있어요.

urlParse

URL에 대한 문자열을 파싱해 URL 부분이 담긴 dict를 만들어요.

urlParse "http://admin:[email protected]:8080/api?list=false#anchor"

위 코드는 URL 객체를 담은 dict를 반환해요.

scheme:   'http'
host:     'server.com:8080'
path:     '/api'
query:    'list=false'
opaque:   nil
fragment: 'anchor'
userinfo: 'admin:secret'

이것은 Go 표준 라이브러리의 URL 패키지를 사용해 구현됐어요. 자세한 내용은 https://golang.org/pkg/net/url/#URL를 확인해 주세요.

urlJoin

urlParse가 만든 맵을 결합해 URL 문자열을 만들어요.

urlJoin (dict "fragment" "fragment" "host" "host:80" "path" "/path" "query" "query" "scheme" "http")

위 코드는 다음 문자열을 반환해요.

http://host:80/path?query#fragment

urlquery

인자로 전달된 값의 이스케이프된 버전을 반환해, URL의 쿼리 부분에 넣기에 적합하게 해요.

$var := urlquery "string for query"

UUID 함수 (UUID Functions)

헬름은 UUID v4 범용 고유 식별자를 생성할 수 있어요.

uuidv4

위 코드는 v4(무작위 생성) 타입의 새 UUID를 반환해요.

쿠버네티스 및 차트 함수 (Kubernetes and Chart Functions)

헬름에는 lookup과 .Capabilities.APIVersions.Has를 포함한 쿠버네티스 관련 함수와 파일 함수가 있어요.

lookup

lookup은 실행 중인 클러스터에서 리소스를 조회하는 데 쓰여요. helm template 명령과 함께 쓰면 항상 빈 응답을 반환해요.

자세한 내용은 lookup 함수 문서에서 찾을 수 있어요.

.Capabilities.APIVersions.Has

API 버전 또는 리소스가 클러스터에 있는지 여부를 반환해요.

.Capabilities.APIVersions.Has "apps/v1"
.Capabilities.APIVersions.Has "apps/v1/Deployment"

자세한 정보는 내장 객체 문서에서 확인할 수 있어요.

파일 함수 (File Functions)

차트 안의 특수하지 않은 파일에 접근할 수 있게 해주는 함수가 여러 개 있어요. 예를 들어 애플리케이션 설정 파일에 접근하는 데요. 이것들은 템플릿 안에서 파일 접근하기에 문서화되어 있어요.

참고, 이 함수들 중 많은 문서는 Sprig에서 가져온 것이에요. Sprig는 Go 애플리케이션에서 쓸 수 있는 템플릿 함수 라이브러리예요.

더 알아보기 (Learn more)

• 템플릿 함수와 파이프라인: Functions and Pipelines
• 내장 객체: Built-in Objects
• 템플릿 안에서 파일 접근하기: Accessing Files Inside Templates
• Sprig 함수 문서