jpFun 语法规范

1. 核心思想

函数式语法，常用操作提供简写。

函数索引

分类	函数
基础设置	@key @tempo @program @meter @set
页面与谱头	@page @head
音符	@note
时值与小节线	@div @dot @dash @bar
文本与符号	@text @symbol
换行	@br @pagebreak / @pb
声部与歌词	@voice @voices
堆叠与和弦	@stack @up @down
琶音倚音与连音	@arp @grace @tuplet
外框与微调	@box @adjust
关系型：连线、反复房子、八度号、渐强渐弱	@beam @tie @gliss @volta @ottava @dyn

2. 基本类型

• 字符串：双引号 "..."，无歧义时可省；含分隔符须加引号，如 @note("b6,")。
  • 可跨行；引号须配对，孤立 " 按普通字符处理。
  • \ 转义后一个字符，如 \"；不支持 \n 等语义转义。
• 布尔值：true / false。
• 数字：有限整数或小数。
• 长度：数字加 px（默认）或 em（相对当前字号）。
• 内容块：{...}，无歧义时可省括号。
• 标签：1@a 声明；不紧接 ( 的 @名称 按标签解析。
  • 绑定前方最近的可标注对象，可穿透 @div、@box、@text 等透明节点。
  • 目标已有标签或复合体无可标注对象时，失效并警告。

调用：@func(...)，函数名须紧接 (，参数用逗号分隔。

3. 主要函数

基础设置

• @key(tonality, size=1em) / @1(...)：设置后续 1= 音高基准，初始 C4。
  • 格式：音名 + 可选单个 #/b + 八度。音名为 AG 或 17，八度默认 4。
  • 非规范输入按音高归一化，无法识别则回退 C4；警告 W_KEY_TONALITY，严格模式报错 E_KEY_TONALITY。
• @tempo(bpm, size=1em)：设置后续速度，每分钟四分音符数。
• @program(program) / @instrument(...)：设置当前音轨后续 MIDI 音色；整数 0~127，初始 0（大钢琴）。
• @meter(num, den, size=0.7em)：拍号 num/den。
  • 分子、分母均为正整数；小节时长 4 × num / den 个四分音符，不改变音符基本时值。
  • 首小节允许弱起，不可超拍；后续在小节线、拍号变更或曲末校验满拍。
• @set(key=value, ...)：从当前位置设置本级及子作用域默认值；退出 {} 恢复外层设置。优先级见参数规则。
  • 函数名.参数名=值：支持别名，未知目标警告并忽略。
  • 系统项：fontsize 基准字号，font 文本字体，numberfont 数字字体。
  • strict：默认 false；开启后未知函数及部分可恢复问题改为报错。

页面与谱头

• @page(width, height, top, bottom, left, right, gap, numbering, font, fillRatio)：页面布局。

  • 仅顶层首次声明有效，其余警告并忽略；em 按声明时字号计算。
  • 默认：宽 794px、高 0px、上 45px、下 48px、左右 40px、行距 1em、fillRatio=0.5。
  • height <= 0 不自动分页，仍可手动换页；正值按整行分页，单行超高报错。自动封页均分剩余高度，末页保持最小行距。
  • fillRatio：自然宽度达到版心宽度的该比例时撑满；负值始终撑满，>= 1 不自动拉开。
  • numbering：页码格式，如 "1/1"，默认 "" 不显示；font：页码字体，默认 "" 沿用当前字体。

• @head(left={}, center={}, right={}, gap=5px)：谱头，gap 为栏内行距。

  • 只接受零时长内容；可嵌套，不自动换行。
  • 每栏第一层元素各占一行：left={"甲" "乙"} 分行，left={{"甲" "乙"}} 同行。
  • 行声明：H.title: / H.subtitle: 居中，H.author: 居右，H.signature: 1=C 4/4 / H.tempo: 94 居左。
  • H.left: / H.center: / H.right: 自定义各栏，裸文本转为 @text。
  • 连续声明合为一个谱头，每条一行；空行或普通内容结束组合。

音符

• @note(name, acc="", octave, color="#000") / @n(...)：音符。
  • 1～7：相对音级，octave 默认 0；后缀 ' 升八度、, 降八度，如 1'、6,,。
  • A～G：绝对音名，octave 默认 4，如 C4、F#5；实际音高不随调性变化。
  • acc：# 升半音、b 降半音、n 还原，可重复；简写如 #1'、b6,、C#4。
  • 0 / Z 休止，8 隐形静音占位，9 / X 打击节拍记号；均忽略升降号与八度。
  • JE 兼容：(、] 降八度，[、) 升八度；可嵌套，不越过当前 {}。

时值与小节线

• 基本时值：一个四分音符（1 QN）；先减时线、后附点，与嵌套顺序无关。

• @div(内容, n=1, autobeam=true) / @/(...)：减时线，后缀 /；每条时值减半。

  • 内部始终连梁；独立 div 在同轨、同谱面行、同一拍内连续且短于一拍时自动连梁（未设拍号、散板或分母 $\le 4$ 按 1 QN；分母 $\ge 8$ 且分子为 3 的倍数按 3 个分母单位；其余分母 $> 4$ 按 1 个分母单位）。
  • 拍边界、小节线、拍号变更、换行、时间间隙、非候选可见元素、开关变化或手工 @beam 截断自动连接。
  • autobeam=false 只关闭与周围 div 的自动连接。

• @dot(内容, n=1) / @.(...)：附点，后缀 .；单附点 ×1.5，双附点 ×1.75，如 1/.。

  • 内容须恰好产生一个事件，和弦整体算一个，如 {1^2}.。

• @dash() / @-()：增时线，简写 -；独占 1 QN 并延续前音，可加减时线或附点。

• @rest(n=1, width=3em, size=1em)：整小节休止，必须先声明拍号。所有声部必须同时使用。

• @bar(type=0, length=1.25em) / @|(...)：小节线，多声部间强制时间对齐。

  • type：0 普通 |，1 双竖线 ||，2 终止 |||，3 反复起点 |:，4 反复终点 :|，5 双向反复 :|:。
  • :| 回到此前最近的 |:，无起点则回曲首；每条只回跳一次，多条可增加遍数。

文本与符号

• @text(字符串, size=1em, lineheight=1.25, align=left)：文本标记。

  • 简写 "渐强"；可直接换行，lineheight 为自身字号的倍数。
  • align=left/center/right：左对齐 / 居中 / 右对齐，锚点为首行首字中心 / 整块中心 / 首行末字中心。

• @symbol(name, size=0.5em) / @$(...)：乐谱符号，简写 $name。

  • 名称按小写精确查表，未命中时尝试各符号的可选正则，要求完整匹配；未知名称警告，严格模式报错。
  • $ 后连续的非空白文本作为完整名称，直到空白或当前内容区间末尾。
  • 装饰：$tr 颤音、$prall 上波音、$mordent 下波音、$turn 回音、$iturn 逆回音。
  • 奏法：$accent 重音、$marcato 强调音、$staccato 断奏、$tenuto 保持音。
  • 技法：$tremolo 轮指、$harmonic 泛音。
  • 颤音尾巴：$tr+、$tr++、$tr+++ 等。
  • 延长：$fermata 延长号。
  • 力度：$ppp、$pp、$p、$mp、$mf、$f、$ff、$fff 等。
  • 跳转：$dc 回曲首、$ds 回标记、$segno 标记、$fine 终止。

换行

• @pagebreak(justify=true) / @pb(...)：结束当前页

  • 有限页高下默认分配当前页的剩余空间；justify=false 只保留最小行距。无限页高按自然高度结束，不拉伸。
  • 同时刻的并行调用只换一次页，任一 justify=false 则不拉伸；同轨连续调用分别执行。

• @br(offset=1)：后续内容偏移指定谱面行数。

  • 顶层空行（连续至少两个换行）等价于一次 @br()；普通源码换行及块内空行不换谱面行。
  • offset 向下取整，负值按 0；@br(0) 不换行，@br(2) 留一空行，多次调用累加。

声部与歌词

• @voice(content, name="", 歌词..., 歌词名=歌词) / @v(...)：声部及歌词。

  • 简写：N(声部名): 内容、L(歌词行名): 歌词，名称均可省。
  • N: 到同层换行、下一条 N/L/V 或块末结束；跨源码行须用 {} 包裹。
  • name 后每个字符串参数或 L: 对应一行歌词；命名参数名为歌词行名。L: 属于前一声部，无所属声部则报错。
  • 按空格、连字符和非 ASCII 字符分词；{你好} 合为一个音符槽，显示时去掉花括号。

• @voices(...声部, connect="[-]") / @vs(...)：声部按书写顺序自上而下并行。

  • 位置参数须为 @voice，各占独立音轨；连续 N: 及所属 L: 自动成组，空行、作用域结束或普通非成员内容结束组。
  • connect（仅命名传参）：只改外观。"[-]" 全组带钩括线，"{-}" 全组大括号，"" 或纯空白字符串仅公共细连谱线；单声部组不画连接。
    • 范围可组合，如 "[1-4]{5-7}"；从 1 编号，只数直接声部，含两端，省略端点取首 / 末声部。
    • 端点为正整数，不可反向或越界；单成员可写 [3] 或 {3}，分别等价于 [3-3] 或 {3-3}；可重叠，不自动嵌套或避让。
  • 连接声明：V{}: 大括号、V[]: 带钩括线、V|: 仅细线；不限行首，后须有 N:，可同行或换行。
    • 到下一 V 或组末结束，不拆分并行组；相邻同形声明仍独立，L: 不跨声明寻找声部。
  • 默认值：省略 connect 时取 @set 预设或内置 "[-]"；显式参数或本组 V 声明优先。任一 V 完整替换本组预设，未声明部分仅细线，不影响后续组。

堆叠与和弦

• @stack(...)：临时多声部，简写 &。

  • 各分支同时开始、独立计时，可含旋律；首分支留在宿主轨，其余使用分支轨并依次向上排列。
  • 与 @up 不同，整体不能作为单个连音线端点。

• @up(...)：和弦，简写 ^，自下而上排列。

  • 折叠为一个事件，时值、对齐和减时线取首成员（宿主）；每个参数须恰好产生一个可见对象。
  • 至少一个成员可标注时，整体才可标注；{1@x ^ 3} 定位成员，{1 ^ 3}@x 定位整体，后者的连音线从最上方成员起跳。

• @down(...)：向下堆叠，简写 _，与 ^ 共用宿主及折叠规则。

  • 1^2_3^4_5：宿主 1，上方 2 4，下方 3 5；横向占位取宿主，附属成员撑开行高。
  • 1 ^ $accent、1 _ $accent 均修饰宿主，$accent ^ 1 无效。
  • 1 ^ $p、1 _ $p 从宿主生效；$p ^ 1 的宿主力度不变，之后的音才改变。

琶音倚音与连音

• @arp(content, direction) / @arpeggio(...)：琶音。

  • 内容须为同轨、至少两个成员的 up/down，如 @arp({1 ^ 3 ^ 5})。
  • up/down 按视觉位置向上 / 向下起音并画箭头；省略时向上起音，不画箭头。
  • 不增总时值；每成员占一槽，默认间隔 1/8 QN，短和弦压缩至末槽不晚于总时值一半。

• @grace(宿主, 倚音, side=pre)：倚音。

  • 2>1 前倚音（pre），1<2 后倚音（post），箭头指向宿主；多倚音用 {3 2}>1。
  • 宿主须为一个可见事件；倚音至少一个可见对象，可含和弦、连音、多声部及状态设置，不可换行。
  • 倚音默认八分音符，后缀 / 变十六分；相邻减时线自动连接。
  • 不增正文时值；借宿主实际时值的比例为 min(倚音字面总时长 / 1 QN, 0.75)，多声部取最长分支，在宿主轨同步起奏。
  • 可嵌套，> 左结合、< 右结合，字号逐层缩小；成员标签保留，调用后的标签绑定宿主。

• @tuplet(content, normal)：多连音。

  • 显示数字 actual = 原总时值 / 最短正时值，须为不小于 2 的整数；所有时值乘以 normal / actual。
  • 如 @tuplet({1/ 2 3}, 4) 显示 5，总长 2 QN。
  • 内容须同轨、同谱面行；可嵌套。

外框与微调

• @box(content, padding=0em, stroke=1px, width=-1px)：矩形外框，不改变时值或播放。

  • content 必填且不能跨谱面行，空内容不绘制。
  • padding 内边距、stroke 线宽，负值按 0；stroke=0px 隐藏框。
  • width <= 0 自然宽度，正值限定内容宽度（不含内边距与线宽），同时间列保持对齐。
  • 包围框内声明的关系对象，不纳入框外声明的关系线；定宽框可嵌套，宽度不足、约束冲突或部分交叉报错。

• @adjust(内容, dx=0px, dy=0px, dw=0px, dh=0px) / @adj(...)：微调排版。

  • dx/dy 平移，邻居不避让，关系线跟随；dw/dh 改占位，邻居随之移动，宽高下限为 0。
  • dw 按左右占位比例分配，dh 只改下方；多个对象逐个生效，可调整和弦、倚音成员或单根关系线。

• @slide(内容, side=pre, direction=up)：纯视觉的滑入／滑出箭头。

  • pre 修饰首个可绘制对象，post 修饰末个可绘制对象；多音内容只绘制一个记号。
  • up/down 表示随时间上行／下行；四种组合分别为低处滑入、高处滑入、向高处滑出、向低处滑出。

关系型

• @gliss(标签1, 标签2)：滑音斜直箭头，仅绘制，不改变时值或播放；两个位置标签必填，不接受命名参数。
  • 标签顺序不限，按谱面时间自动确定起点和终点；@gliss(a,b) 与 @gliss(b,a) 等价，同时刻端点不合法。
  • 端点不限对象类型，但须具有排版盒子。优先读取端点自身的 resolvedMidi；没有该属性时沿同轨向前找第一个带该属性的对象，可跨时间缺口和谱面行，找到后即停止，空值不继续追溯。
  • 两端音高均为有限数值时，同轨按音高绘制；无法比较音高时发出 W_GLISS_NO_PITCH 警告并画水平箭头，每条关系只警告一次。
  • 从被标记对象右侧连接到终点左侧，避让附点与升降号，不自动移至最后一根增时线。
  • 如 1 - -@a 5@b @gliss(a,b)；增时线缺少自身音高时，由 gliss 查找前方音高，不改变增时线本身或播放行为。
  • 同一谱面行内可跨轨；跨轨始终连接实际端点，斜率不代表音高方向。不支持跨行、跨页、同一倚音组内部连接或复杂绕障。
• @beam(...端点标签)：手工连梁，不受 div.autobeam 影响。
  • 端点须按时间顺序指向同轨、同谱面行的相邻可见元素，可跨零时长小节线；和弦仅宿主参与。
• @tie(...端点标签, height=0)：连音线 / 延音线。
  • 按传入顺序连接相邻端点；不足两个时，向前寻找最近的可标注对象补足。
  • height 仅命名；非正数为自动模式，按水平跨度平滑递增，在 2.5em 跨度处达到 0.5em 上限（em 相对调用处字号）；正数指定固定高度。
  • 跨行分段，自动模式下各段统一使用 0.45em 高度，不随局部跨度变化；跨轨可画线。
  • 仅同轨、同音高、时间连续时合并发声，否则只画线。
• @volta(from, to, pass, ...)：反复房子，限定区间演奏遍数。
  • 首末标签可相同、顺序不限；遍数为必填正整数，可多个，如 @volta(a,b,1,2)，自动排序去重。
  • 区间位置决定所属反复段，各段独立计遍；重叠房子限定互斥遍数时警告，重叠列不演奏。
• @ottava(a, b, shift=1)：八度号，前两个标签仅支持位置传参；shift 为非零整数八度数，正数为高、负数为低，可命名传参。
  • 标签按 7 * abs(shift) + 1 显示：±1 为 8、±2 为 15、±3 为 22，以此类推；使用 numberfont 的斜体。
  • 只改变区间内同轨的播放音高（12 * shift 半音，须为安全整数），不改变记谱音符、八度点或时值；其他音轨和打击节拍不受影响。
• @dyn(from, to, dv)：渐强渐弱。
  • 标签须同轨、不同时间，顺序不限，可指向增时线；按时间从早到晚生效。
  • dv：非零力度增量，正强负弱；超出 -127..127 的有限值限制并警告。
  • 增量从 0 线性变至 dv，叠加原力度，终点后保持至下一原始力度变化；最终限制为 1..127。
  • 缺少保持所需的基准力度时警告，保留图形但跳过播放修正。
  • 楔形在音符上方，避让区间对象，不自动移动 $p、$f。

4. 参数规则

位置参数须在命名参数之前：

参数类型	传参方式	示例
仅位置	按顺序传入	@text 的正文
位置或命名	按顺序或 参数名=值	@meter 的 num、den
仅命名	参数名=值，不占位置序号	@tie 的 height、@voices 的 connect

• 优先级：显式命名值 → 显式位置值 → @set → 内置默认值；仅命名参数跳过位置查找，无名称参数只查位置和内置默认值。
• 0、false、"" 均视为已提供；额外参数由各函数解释。
• 字符串内 {}、[] 为字面量，不解析为内容，如 connect="{1-2}"。

5. 预处理规则（换行与注释）

• 注释：字符串外 % 至行末；\% 不能阻止注释。
• 换行：支持 \n、\r\n，兼容 \r。
• 续行：忽略行尾空白后，末尾连续 \ 每对保留一个；总数为奇数则合并下一行，偶数则保留换行。