mdwire

Documentation

Overview

Package mdwire 는 에이전트가 만든 마크다운을 채팅 채널로 안전하게 내보낸다.

Rust 코어(crates/mdwire-core)의 Go 이식이다. **코퍼스가 정본이다** — 두 구현은 같은 corpus/cases 를 통과해야 하고, 규칙이 갈리면 코퍼스가 판정한다. 의존은 표준 라이브러리뿐이다.

Index

• Constants
• func CharWidth(c rune) int
• func Render(input string, ch Channel) []string
• func StrWidth(s string) int
• type Channel
  • func Channels() []Channel
  • func ParseChannel(name string) (Channel, bool)
  • func (c Channel) Limit() int
  • func (c Channel) Name() string
• type Dialect
  • func ParseDialect(name string) (Dialect, bool)
  • func (d Dialect) Name() string
• type HTMLOptions
• type Images
• type LineBreaks
• type Options
• type Rendered
  • func RenderWith(input string, ch Channel, o Options) Rendered
• type Repairs
• type Streamer
  • func NewStreamer(ch Channel) *Streamer
  • func NewStreamerWith(ch Channel, o Options) *Streamer
  • func (s *Streamer) CloseOpen() string
  • func (s *Streamer) CloseOpenTo(dst *[]byte)
  • func (s *Streamer) Finish() string
  • func (s *Streamer) FinishTo(dst *[]byte)
  • func (s *Streamer) Preview() string
  • func (s *Streamer) PreviewTo(dst *[]byte)
  • func (s *Streamer) Push(chunk string) string
  • func (s *Streamer) PushTo(chunk string, dst *[]byte)
  • func (s *Streamer) Repairs() Repairs
  • func (s *Streamer) Revised() bool

Constants

const MinLimit = 256

MinLimit 은 호출자가 줄 수 있는 가장 작은 조각 한도다. 조각마다 마크업을 닫고 다시 열 자리가 있어야 한다 — 한도가 태그보다 작으면 분할기가 태그 글자 사이를 가른다(텔레그램 **x** 를 한도 1 로 나누면 < · b · ></b>). 러스트 쪽 MIN_LIMIT 과 같다.

Functions

func CharWidth

func CharWidth(c rune) int

CharWidth 는 한 글자의 표시 폭이다. 0, 1, 2 중 하나.

func Render

func Render(input string, ch Channel) []string

Render 는 완성된 문서를 한 번에 변환한다. 한도를 넘으면 안전한 지점에서 나눈다 — 나누는 자리는 렌더 결과가 아니라 구조에서 고른다. 블록이 끝나 열린 마크업이 없는 지점만 경계가 된다. 변환 후에 문자 수로 자르면 `<code>` 가 열린 채 잘리고 채널은 400 을 준다.

func StrWidth

func StrWidth(s string) int

StrWidth 는 문자열의 표시 폭이다. 이모지 결합 연쇄(ZWJ)는 구성 요소를 각각 세므로 실제보다 넓게 나올 수 있다 — 표를 어긋나게 하는 쪽이 아니라 여유를 주는 방향이라 그대로 둔다.

Types

type Channel

type Channel int

Channel 은 내보낼 채널이다. 받는 문법이 채널마다 다르고, 출력이 좁은 쪽이 파싱 범위를 정한다.

const (
	// TelegramHTML 은 Telegram parse_mode=HTML. 허용 태그 9개, 표·헤딩 없음, 4096자.
	TelegramHTML Channel = iota
	// SlackMarkdown 은 Slack markdown_text. 표준 마크다운을 슬랙이 직접 변환한다. 12,000자.
	SlackMarkdown
	// Plain 은 모든 마크업 제거. 폴백 경로.
	Plain
	// GithubMarkdown 은 GitHub 코멘트·PR 본문(GFM). 65,536자. 슬랙과 같은 마크다운을 내되,
	// GFM 이 구문으로 읽는 글자 둘(`~` `<`)을 탈출한다. 값이 밀리지 않게 끝에 둔다.
	GithubMarkdown
	// HTML 은 브라우저에 넣을 HTML 조각. 헤딩·목록·표·코드블록을 태그로 그린다. 한도 없음.
	//
	// innerHTML 로 바로 넣는 것을 전제로 한다 — 글자는 전부 escape 하고, 원문의 HTML 은
	// 속성을 버린 인라인 태그만 살리며, 링크는 http(s)·mailto 만 <a> 로 낸다. 스트리밍
	// 누적본에 Streamer.CloseOpen 을 붙이면 그대로 넣어도 되는 모양이 된다. 값이 밀리지 않게 끝에 둔다.
	HTML
)

func Channels

func Channels() []Channel

Channels 는 내보낼 수 있는 채널 전부다. 코퍼스와 하네스가 이 목록을 돈다.

func ParseChannel

func ParseChannel(name string) (Channel, bool)

ParseChannel 은 이름으로 채널을 찾는다. 없으면 ok 가 false 다.

func (Channel) Limit

func (c Channel) Limit() int

Limit 은 이 채널의 메시지 길이 한도(문자 수)다. 분할의 기준이다.

func (Channel) Name

func (c Channel) Name() string

Name 은 코퍼스 디렉토리와 CLI 인자에서 쓰는 이름이다. 채널을 문자열로 다루는 곳의 정본이다.

type Dialect

type Dialect int

Dialect 는 입력 방언 — 에이전트가 무슨 표기로 썼는가다. 기본은 표준 마크다운이다. 슬랙에 답하는 에이전트는 흔히 레거시 mrkdwn(`*굵게*` · `_기울임_` · `~취소~`)으로 쓴다.

const (
	// Markdown 은 표준 마크다운(CommonMark · GFM)이다.
	Markdown Dialect = iota
	// SlackMrkdwn 은 슬랙 레거시 mrkdwn 이다. 별표는 몇 개든 굵게, 물결은 하나든 둘이든
	// 취소선이다. 표준 표기가 섞여도 같은 뜻으로 읽는다.
	SlackMrkdwn
)

func ParseDialect

func ParseDialect(name string) (Dialect, bool)

ParseDialect 는 이름으로 방언을 찾는다.

func (Dialect) Name

func (d Dialect) Name() string

Name 은 CLI 인자와 바인딩에서 쓰는 이름이다.

type HTMLOptions

type HTMLOptions struct {
	LineBreaks LineBreaks
	Images     Images
	// Schemes 는 링크·이미지 주소로 받는 스킴이다("https" 처럼 콜론 없이). nil 이면 http·https·
	// mailto. 목록을 주면 그것만 받는다 — 기본값에 더하는 것이 아니다. 빈 슬라이스(nil 이 아닌)는
	// 아무 스킴도 받지 않는다.
	Schemes []string
}

HTMLOptions 는 브라우저 채널의 정책이다. 영값이 가장 보수적이다 — <br> 줄바꿈, 이미지는 링크로만, 링크는 http·https·mailto 만.

type Images

type Images int

Images 는 이미지 `` 을 어떻게 낼지다.

const (
	// ImagesLink 는 <a href>alt</a> 다 — 누르기 전에는 아무것도 불러오지 않는다(추적 픽셀이 없다).
	ImagesLink Images = iota
	// ImagesLoad 는 <img src alt> 다 — 주소가 허용 스킴일 때만. 아니면 ImagesLink 처럼 낸다.
	ImagesLoad
)

type LineBreaks

type LineBreaks int

LineBreaks 는 블록 안의 줄바꿈을 어떻게 낼지다.

const (
	// LineBreaksBR 은 <br> 이다 — 채팅·메모처럼 저자의 줄바꿈이 뜻인 글. 다른 채널이 다
	// 줄바꿈을 살린다.
	LineBreaksBR LineBreaks = iota
	// LineBreaksSpace 는 줄바꿈 글자만 낸다 — 브라우저가 공백으로 접는다. 80열로 wrap 된 문서를
	// 문단으로 읽을 때.
	LineBreaksSpace
)

type Options

type Options struct {
	From Dialect
	// Limit 은 한 조각의 한도(렌더한 출력의 글자 수)다. 0 이면 채널의 Limit().
	//
	// 한도는 보내는 쪽이 정한다 — plain 은 어디로 가는지 모르는 폴백이라 텔레그램으로 보내면
	// 4096 이어야 한다(12,000 으로 나눈 7,153자 조각이 400 을 받았다).
	// 스트리밍은 나누지 않으므로 이 값을 보지 않는다. 브라우저 채널(HTML)도 나누지 않는다 — 분할기가
	// 블록 태그를 여닫지 않아 태그 한가운데서 갈린다. MinLimit 보다 작은 값은 그만큼 올린다.
	Limit int
	// HTML 은 브라우저 채널(HTML)의 정책이다. 다른 채널은 보지 않는다.
	HTML HTMLOptions
}

Options 는 변환 옵션이다 — 입력 방언, 조각 한도, 브라우저 채널의 정책. 영값이 기본값이다.

type Rendered

type Rendered struct {
	Parts   []string
	Repairs Repairs
}

Rendered 는 RenderWith 의 결과 — 조각과 고친 것이다.

func RenderWith

func RenderWith(input string, ch Channel, o Options) Rendered

RenderWith 는 Render 에 옵션을 주고, 정규화가 고친 것도 같이 돌려준다.

type Repairs

type Repairs struct {
	// ClosedEmphasis 는 블록이 끝나도록 안 닫혀서 닫아 준 강조다.
	ClosedEmphasis int
	// ClosedFence 는 문서 끝까지 안 닫혀서 닫아 준 코드펜스다.
	ClosedFence int
	// RevertedCodeSpan 은 짝이 없어 코드가 아니라 글자로 되돌린 백틱 런이다.
	RevertedCodeSpan int
	// DroppedMarker 는 짝 잃은 채 버린 `**` 다.
	DroppedMarker int
}

Repairs 는 정규화가 고친 것의 개수다. 모델이 얼마나 자주 서식을 깨는지 재는 데 쓴다.

type Streamer

type Streamer struct {
	// contains filtered or unexported fields
}

Streamer 는 스트리밍 변환기다. 조각을 넣으면 지금 안전하게 내보낼 수 있는 만큼만 돌려준다. 경계에 걸린 마크업(`**굵` 에서 끊긴 것)은 안에 남겨 두고 다음 조각을 기다린다.

func NewStreamer

func NewStreamer(ch Channel) *Streamer

NewStreamer 는 채널 하나에 묶인 변환기를 만든다.

func NewStreamerWith

func NewStreamerWith(ch Channel, o Options) *Streamer

NewStreamerWith 는 옵션을 주고 만든다 — 입력 방언 따위.

func (*Streamer) CloseOpen

func (s *Streamer) CloseOpen() string

CloseOpen 은 CloseOpenTo 의 편의 서명이다.

func (*Streamer) CloseOpenTo

func (s *Streamer) CloseOpenTo(dst *[]byte)

CloseOpenTo 는 지금까지 받은 것을 그대로 보내도 되게 만든다. 상태는 건드리지 않으므로 붙인 뒤에도 스트리밍은 이어진다. 누적본을 중간에 채널로 보내는 쪽(토큰이 오는 대로 메시지를 편집하는 경우)은 보내기 직전에 이걸 덧붙인다 — 누적본 자체에는 넣지 않는다.

func (*Streamer) Finish

func (s *Streamer) Finish() string

Finish 는 FinishTo 의 편의 서명이다.

func (*Streamer) FinishTo

func (s *Streamer) FinishTo(dst *[]byte)

FinishTo: 입력이 끝났다. 남은 것을 전부 dst 에 내보낸다(열린 마크업은 닫는다).

func (*Streamer) Preview

func (s *Streamer) Preview() string

Preview 는 PreviewTo 의 편의 서명이다.

func (*Streamer) PreviewTo

func (s *Streamer) PreviewTo(dst *[]byte)

PreviewTo 는 지금 입력이 끝났다면 확정분 뒤에 붙을 꼬리를 dst 에 붙인다 — 러스트 쪽 Streamer::preview. CloseOpenTo 와 같은 자리에 들어가지만 붙들고 있던 것까지 그린다: 열린 강조는 닫아서, 표는 지금까지 온 행으로, 코드 스팬은 닫아서. 누적본을 통째로 다시 그리는 쪽 (텔레그램 editMessageText, 슬랙 chat.update)의 기본값이다.

꼬리는 일괄 렌더와 같은 finish 경로라 문법은 늘 맞지만 추측이다 — 뒤의 조각이 모양을 바꿀 수 있다. 끝난 뒤 마지막 미리보기와 달라졌는지는 Revised 가 알려 준다. 비용은 열린 블록 크기에 비례한다(엔진을 복제한다). 조각마다 말고 화면을 그릴 때 부른다.

func (*Streamer) Push

func (s *Streamer) Push(chunk string) string

Push 는 PushTo 의 편의 서명이다. 새 문자열을 돌려준다.

func (*Streamer) PushTo

func (s *Streamer) PushTo(chunk string, dst *[]byte)

PushTo 는 조각을 밀어 넣고 지금 내보낼 수 있는 출력을 dst 에 붙인다. 정본 서명 — 호출자 버퍼에 직접 쓰므로 조각당 할당이 없다.

func (*Streamer) Repairs

func (s *Streamer) Repairs() Repairs

Repairs 는 지금까지 정규화가 고친 것이다. Finish 뒤에 보면 문서 전체의 값이다.

func (*Streamer) Revised

func (s *Streamer) Revised() bool

Revised 는 완성본이 마지막 미리보기와 다른가다 — Finish 뒤에 본다. 거짓이면 마지막으로 그린 화면(누적본 + Preview)이 곧 완성본이라 다시 그릴 필요가 없다. 텔레그램은 같은 내용으로 편집하면 400("message is not modified")을 주므로 이걸 보고 마지막 편집을 건너뛴다. 미리보기를 안 했거나 그 뒤에 조각이 더 왔으면 참이다 — 참은 "다를 수 있다"는 뜻이다. 편집을 솎아 보내 마지막 미리보기가 마지막 조각보다 앞서면 완성본이 같아도 참이니, 그런 쪽은 보낸 문자열과 직접 비교한다.