编程接口

EKP 可以完全脱离缓冲区使用。字符串接口把文本当作值来接收、把排版好的文本当作值返回，从不触碰当前缓冲区或窗口：应用把它嵌进来排版一段即将显示的正文，其它包调用它为自己渲染器准备文本。本章定义这条边界：两个排版调用、它们背后的语义方案，以及与之配套的缓存控制。

断行模型见断行原理；把同一批方案投影到编辑缓冲区的命令见交互使用。控制宽度选择、断字、禁则与超宽 token 策略的选项都是用户选项，汇总在参数参考一章；本章在函数结果取决于它们时点名。

字符串边界

一个字符串参数是由换行符分隔的一个或多个段落。每个换行分隔的片段作为独立段落规划，空片段保持为空：空行保留在输入放置它们的位置，任何断行决定都不跨越换行。段落层面没有单独的宽度参数——宽度参数就是段落规划所依据的整个行宽。

输入上的文本属性与在缓冲区里一样被尊重：刚性不可断原子保持完整，携带断行策略的区间保住策略，因此纯字符串的一段文字也能被强制断字或禁止断字。逐字保护属于缓冲区层——字符串接口会规划收到的每一个段落——所以想原样保留段落的调用方，直接不要把它传进来。

排版的结果是一个新字符串，而不是对参数的改动。它包含源字符，加上让段落两端对齐的合成间距与断行；被替换掉的源片段记录为文本属性，供包自己的缓冲区层在同一个字符串插入缓冲区时反变换。因此需要未改动源文本的调用方保留输入；对结果去掉属性并不能还原它。调用是确定性的：同样的字符串与宽度产生相等的（含属性的）结果。

原生模块已加载且输入多于一个非空段落时，字符串排版会先并行规划各段落再渲染，这正是由许多短段落组成的宽文档能快起来的原因；结果不取决于是否走了这条路径。本层里有一个策略有可见的捷径：ekp-overlong-token-policy 为 natural 且段落里含有宽过行宽的普通拉丁式 token 时，该段落原样返回而不做规划，整段交给 Emacs 换行。

排版字符串

Function: ekp-pixel-justify (string line-pixel)

把多行 STRING 排版到 LINE-PIXEL 像素宽。

参数。 STRING 是文本，每个换行分隔的片段是一个段落。LINE-PIXEL 是目标像素宽，必须是正整数。

语义。 每个非空段落按 LINE-PIXEL 规划并渲染；空片段原样复制。STRING 上的文本属性按字符串边界所述充当排版输入，被超宽 token 策略判为自然的段落原样返回。原生模块可用且输入含多个段落时，规划并行进行。结果是全新的确定性字符串：同样的输入与宽度总产生相等的结果。

返回。 排版后的字符串。它的可见形式就是两端对齐的段落；每次合成所替换的源文本片段记录在它的文本属性里，供包自己的渲染层使用。

错误。 STRING 不是字符串时 error→ wrong-type-argument，数据点名 stringp。LINE-PIXEL 不是正整数时 error→ user-error，消息为 Line width must be a positive integer, got PIXEL。规划本身的错误原样传播，例如选中的字典不可用时抛 ekp-hyphen-unsupported-pattern。

示例。

(ekp-pixel-justify "one two three four five six seven eight nine ten" 60)
     ⇒ the same words laid out at a 60-pixel measure
(length (split-string
         (ekp-pixel-justify "one two three four five six seven eight nine ten" 60)
         "\n"))
     ⇒ 1 with automatic spacing, 2 after (ekp-param-set 4 8 2 3 6 2 0 4 0)

参见。 ekp-pixel-range-justify、ekp-layout-plan、ekp-clear-caches。

Function: ekp-pixel-range-justify (string min-pixel max-pixel)

在 MIN-PIXEL 与 MAX-PIXEL 之间为 STRING 找出最优宽度。

参数。 STRING 是文本，规划方式与 ekp-pixel-justify 完全一致。MIN-PIXEL 与 MAX-PIXEL 是限定候选宽度的正整数，且 MIN-PIXEL 不得大于 MAX-PIXEL。

语义。 函数在区间内搜索使各段平均代价最低的宽度——代价是段落支付的代价，对非空段落取平均，因此很长的输入不会压过很短的输入。搜索是三分搜索加一次局部扫描，得到的是好的局部最优而不是保证：所选行数一变，代价关于宽度就会跳变，曲线并非严格单峰。区间只有一个宽度是合法的，直接按该宽度排版。返回的文本正好等于按返回宽度调用 ekp-pixel-justify 的结果。

返回。 一个 cons 单元 (JUSTIFIED . PIXEL)：排版后的字符串与从区间中选出的宽度。

错误。 STRING 不是字符串时 error→ wrong-type-argument，数据点名 stringp。任一界限不是正整数时 error→ user-error，消息为 Line width must be a positive integer, got WIDTH；界限颠倒时消息为 Min-pixel (MIN) must be <= max-pixel (MAX)。

示例。

(ekp-pixel-range-justify
 "Pack my box with five dozen liquor jugs. The five boxing wizards jump quickly."
 60 120)
     ⇒ (justified-text . 116)

参见。 ekp-pixel-justify、ekp-layout-plan。

布局方案

字符串接口渲染它的方案，缓冲区接口投影它，而调用方也可以直接索取方案本身。方案是「决定」与「显示」之间的表示边界：它描述段落长什么样——哪些源盒子同处一行、胶放在哪里放多少、可选连字符取在何处——而不承诺空格、换行、文本属性或任何其它输出形式。它既是包自己的渲染器消费的对象，也是未来消费者用来在别处显示同一布局的对象。

方案要么是 planned，要么是 natural。规划好的方案携带各行；自然方案不带任何行，并记录该段落因超宽 token 策略而交给 Emacs 换行。驱动字符串排版的那组策略输入同样驱动方案，因此方案就是某个宽度上一次布局决定的完整描述。

Function: ekp-layout-plan (string line-pixel)

返回 STRING 在 LINE-PIXEL 宽下的语义 KP 布局方案。

参数。 STRING 是一个或多个段落的文本，与排版调用一样按换行切分。LINE-PIXEL 是目标像素宽。

语义。 方案记录段落的源偏移、各行、每行的胶目标、缩进与剥掉的行缘，以及该行是否以可选连字符结尾。布局是完整的，但没有显示表示：方案里没有任何东西说明空格就是空格字符、断行就是换行。被超宽 token 策略判为自然的段落方案没有行，状态为 natural；否则状态为 planned。方案按段落与布局上下文缓存，命中时返回调用方拥有的副本，因此改动收到的东西不会影响之后的方案。与两个排版调用不同，本函数不校验宽度：小到放不下一个盒子的宽度也会被接受，并产生每个盒子一行的方案。

返回。 一份布局方案记录。经 ekp-layout-plan-string、ekp-layout-plan-lines 与 ekp-layout-plan-state 读取它，再用 ekp-layout-line-* 行读取器与 ekp-layout-gap-* 胶读取器读取细节。

错误。 STRING 既不是字符串也不是缓冲区时 error→ wrong-type-argument，数据点名 buffer-or-string-p。不校验宽度：任何整数都会被接受。

示例。

(ekp-layout-plan "aaaa bbbb cccc dddd eeee ffff gggg" 30)
     ⇒ a plan with two lines, the first ending after "ffff"

参见。 ekp-pixel-justify、ekp-clear-caches。

Function: ekp-layout-plan-string (plan)

返回 PLAN 计划时所依据的清理后源文本。

语义。 方案的源偏移索引这个字符串，所以某一行的源范围切出的就是它渲染的确切文本。

返回。 源字符串。

错误。 error→ wrong-type-argument (ekp-layout-plan PLAN)：PLAN 是另一种值时。

参见。 ekp-layout-plan、ekp-layout-line-source-start。

Function: ekp-layout-plan-lines (plan)

把 PLAN 的显示行作为行记录向量返回。

语义。 每行带它渲染的源范围、前后像素、可选连字符标志与语义胶。状态为 natural 的方案返回空向量。

返回。 行记录向量。

错误。 error→ wrong-type-argument (ekp-layout-plan PLAN)：PLAN 是另一种值时。

参见。 ekp-layout-plan-state、ekp-layout-line-source-start。

Function: ekp-layout-plan-state (plan)

返回 PLAN 的状态：planned，或被超宽 token 策略判为不打断的 natural。

语义。 读行之前先读它：natural 方案保持字符串不打断、没有行，渲染器应把源文本显示在测量宽度之外，而不是使用计划好的断点。

返回。 状态符号。

错误。 error→ wrong-type-argument (ekp-layout-plan PLAN)：PLAN 是另一种值时。

参见。 ekp-layout-plan-lines。