excel-codegen 0.9.0__py3-none-any.whl

excel_codegen/examples/abs_fpi/generated/WBT7-d20.559-mu90_summary.md

@@ -0,0 +1,30 @@
+| 项目 | 值 | 出处 |
+| --- | --- | --- |
+| case_name | WBT7-d20.559-mu90 | 工况名（Excel 表头） |
+| kind | INT | 规则集（多规则集共用一本工作簿时用 case_filter 分流） |
+| tank_ref | WBT7 | 指向成员表 `Tank Data` 的哪一行（指南 §18） |
+| draft | 20.559 m | 装载工况 |
+| mu_deg | 90 deg | Table 1A D |
+| k_c | 1 | Table 1A C |
+| k_u | 1.1 | 5A-3-2/7, /9 |
+| beta_VAC | 0.66 | 5A-3-A1/3 |
+| beta_LAC | 0.758 | 5A-3-A1/3 |
+| beta_TAC | 0.557 | 5A-3-A1/3 |
+| beta_PMO | 0.686 | 5A-3-A1/3 |
+| beta_RMO | 0.492 | 5A-3-A1/3 |
+| k_esf | 1.1 | 项目 |
+| w_v / w_l / w_t | 0.75 / 0.25 / 0.75 | Table 1A B |
+| xi | 7.25 m | 5.7.2(b) |
+| delta_b / delta_h | 0 m / 0 m | 5.7.2(b) |
+| rho_tank | 1025 kg/m^3 | 成员表 Tank Data |
+| l_tank / b_tank / h_tank | 14.5 m / 10.15 m / 32 m | Fig. 11 |
+| eta_deck / eta_overflow | 0 m / 0 m | Fig. 12 |
+| C_dp / C_ru | 1 / 1 | 5.7.2(d) |
+| p_vp | 0 N/cm^2 | 成员表 Tank Data |
+| GM_full_in / k_r_in | 0 m / 0 m | 稳性计算书 |
+| tank_is_ballast / member_11_17 | 1 / 0 | Table 3 |
+| L / B / D / d_f | 340 m / 64 m / 32 m / 20.559 m | 3-1-1/3 |
+| rho_sea / g / Cb | 1025 kg/m^3 / 9.81 m/s^2 / 1 | 5.7.1 |
+| rho_g_lo / rho_g_hi | 10050 N/m^3 / 11180 N/m^3 | 5.7.2(a) |
+| axis ax | (1, 2, 3) | 模型 |
+| axis neg | ( /  / ) | 模型 |

excel_codegen/examples/abs_fpi/templates/ext_body.js.j2

@@ -0,0 +1,91 @@
+// {{ case_name }}
+// The rules live in the RULE frame: x from the A.P., y from the centre line
+// positive starboard, z above the baseline.  The model usually is not, so the
+// three mapping cells (ax_* / neg_*) convert it.  All three coordinates go
+// through temporaries first: assigning them in place would read a coordinate
+// that has already been overwritten.
+var t1 = x;
+var t2 = y;
+var t3 = z;
+x = {{ neg_x }}t{{ ax_x }};
+y = {{ neg_y }}t{{ ax_y }};
+z = {{ neg_z }}t{{ ax_z }};
+// --- global parameters (same for every case)
+var L = {{ L }};
+var B = {{ B }};
+var D = {{ D }};
+var r_b = {{ r_b }};
+var freeboard = {{ freeboard }};
+var rho_sea = {{ rho_sea }};
+var g = {{ g }};
+var Cb = {{ Cb }};
+// --- this case
+var draft = {{ draft }};
+var mu_deg = {{ mu_deg }};
+var k_c = {{ k_c }};
+var k_f0 = {{ k_f0 }};
+var k_u = {{ k_u }};
+var beta_EPS = {{ beta_EPS }};
+var beta_EPP = {{ beta_EPP }};
+var k_esf = {{ k_esf }};
+var x_o = {{ x_o }};
+// --- the calculation
+var u = mu_deg;   // the heading, as an Angle -- cos/sin take it directly
+var C_1 = 0;   // wave coefficient, 0 until a length bracket matches
+// C_1 brackets of 3-2-1/3.5, closed at both ends; outside them C_1 is zero
+if      (L >= 61 m  && L <= 90 m ) C_1 = 0.044 * (L / 1 m) + 3.75;
+else if (L >  90 m  && L <  300 m) C_1 = 10.75 - Math.pow((300 m - L) / 100 m, 1.5);
+else if (L >= 300 m && L <  350 m) C_1 = 10.75;
+else if (L >= 350 m && L <= 500 m) C_1 = 10.75 - Math.pow((L - 350 m) / 150 m, 1.5);
+else                               C_1 = 0;
+var h_do = 1.36 * C_1 * 1 m;   // reference hydrodynamic head, k = 1 (5.5.1)
+var z_bilge = r_b;   // rule z of the bilge (the bilge radius)
+var z_freeboard = D - freeboard;   // rule z of the highest deck at side
+var xL = x / L;   // x / L, dimensionless
+var k_lo = 1;   // k_lo = 1.0 amidships
+// Fig. 9: k_lo = 1 amidships, rising towards both ends
+if      (xL < 0.2) k_lo = 1.5 - xL * 2.5;
+else if (xL > 0.7) k_lo = 1 + (xL - 0.7) * 5;
+else               k_lo = 1;
+var k_l = 1 + (k_lo - 1) * Math.cos(u);   // k_l = 1 + (k_lo - 1) cos mu; GeniE converts the angle inside cos
+var k_f = k_f0 * (1 - (1 - Math.cos((x - x_o) / L * 360 deg)) * Math.cos(u));   // k_f, the reference station against the wave
+var alpha_1 = (1 - 0.25 * Math.cos(u)) * k_f;   // i = 1, at the waterline, starboard
+var alpha_2 = (0.40 - 0.10 * Math.cos(u)) * k_f;   // i = 2, at the bilge, starboard
+var alpha_3 = (0.30 - 0.20 * Math.sin(u)) * k_f;   // i = 3, at the bottom centre line
+var alpha_5 = (0.75 - 1.25 * Math.sin(u)) * k_f;   // i = 5, at the waterline, port
+var alpha_4 = 2 * alpha_3 - alpha_2;   // i = 4 = 2 alpha_3 - alpha_2, at the bilge, port
+var h_d1 = k_l * alpha_1 * h_do;   // hydrodynamic head at i = 1
+var h_d5 = k_l * alpha_5 * h_do;   // hydrodynamic head at i = 5
+var h_star_s = Math.min(z_freeboard - draft, k_u * h_d1);   // Fig. 10: the head above the waterline, capped at the freeboard, starboard
+var h_star_p = Math.min(z_freeboard - draft, k_u * h_d5);   // Fig. 10: the head above the waterline, capped at the freeboard, port
+var alpha_i = 0;   // alpha at the point evaluated, assigned by the girth branches
+// Fig. 8: alpha at the point evaluated
+if (z >= z_bilge) {
+    if (z <= draft) {
+        // bilge to waterline, on the side of the girth the point is on
+        if (y >= 0 m) alpha_i = alpha_2 + (alpha_1 - alpha_2) * (z - z_bilge) / (draft - z_bilge);
+        else          alpha_i = alpha_4 + (alpha_5 - alpha_4) * (z - z_bilge) / (draft - z_bilge);
+    } else {
+        // above the waterline, faded out over that side's h_star
+        if (y >= 0 m) {
+            if (h_star_s <= 0 m) alpha_i = 0;
+            else                 alpha_i = alpha_1 - (z - draft) / h_star_s * alpha_1;
+        } else {
+            if (h_star_p <= 0 m) alpha_i = 0;
+            else                 alpha_i = alpha_5 - (z - draft) / h_star_p * alpha_5;
+        }
+    }
+} else {
+    // below the bilge: linear across the flat of bottom
+    alpha_i = alpha_4 + (alpha_2 - alpha_4) * (z + z_bilge) / (2 * z_bilge);
+}
+// 5.5.1: which side of the girth, and so which ESF
+// the ESF is a property of the SIDE the point is on: EPS to starboard, EPP to port
+var ESF_side = 0;
+if (y >= 0 m) ESF_side = beta_EPS * k_esf;
+else          ESF_side = beta_EPP * k_esf;
+var h_di = k_l * alpha_i * h_do;   // hydrodynamic head at the point evaluated (5.5.1)
+var h_de = k_c * h_di;   // h_de = k_c h_di (5.5.1 nominal form)
+var p_s = Math.max(rho_sea * g * (draft - z), 0 Pa);   // still-water pressure, zero above the waterline
+var p_d = rho_sea * g * ESF_side * k_u * h_de;   // hydrodynamic pressure, with the ESF of the side the point is on
+return Math.max(p_s + p_d, 0 Pa);   // the pressure the function returns

excel_codegen/examples/abs_fpi/templates/ext_summary.md.j2

@@ -0,0 +1,23 @@
+| 项目 | 值 | 出处 |
+| --- | --- | --- |
+| case_name | {{ case_name }} | 工况名（Excel 表头） |
+| kind | {{ kind }} | 规则集（多规则集共用一本工作簿时用 case_filter 分流） |
+| draft | {{ draft }} | 装载工况 |
+| mu_deg | {{ mu_deg }} | Table 1A D |
+| k_c | {{ k_c }} | Table 1A B |
+| k_f0 | {{ k_f0 }} | Table 1A B |
+| k_u | {{ k_u }} | 5A-3-2/7, /9 |
+| beta_EPS | {{ beta_EPS }} | 5A-3-A1/3 |
+| beta_EPP | {{ beta_EPP }} | 5A-3-A1/3 |
+| k_esf | {{ k_esf }} | 项目 |
+| x_o | {{ x_o }} | Fig. 9 脚注 |
+| L | {{ L }} | 3-1-1/3 |
+| B | {{ B }} | 3-1-1/3 |
+| D | {{ D }} | 3-1-1/3 |
+| r_b | {{ r_b }} | Fig. 11 |
+| freeboard | {{ freeboard }} | Fig. 10 |
+| rho_sea | {{ rho_sea }} | 5.5.1 |
+| g | {{ g }} | 5.5.1 |
+| Cb | {{ Cb }} | 3-1-1/13.3 |
+| axis ax | ({{ ax_x }}, {{ ax_y }}, {{ ax_z }}) | 模型 |
+| axis neg | ({{ neg_x }} / {{ neg_y }} / {{ neg_z }}) | 模型 |

excel_codegen/examples/abs_fpi/templates/int_body.js.j2

@@ -0,0 +1,124 @@
+// {{ case_name }}
+// See ext_body.js.j2 for why the coordinates go through temporaries.
+var t1 = x;
+var t2 = y;
+var t3 = z;
+x = {{ neg_x }}t{{ ax_x }};
+y = {{ neg_y }}t{{ ax_y }};
+z = {{ neg_z }}t{{ ax_z }};
+// --- global parameters (same for every case)
+var L = {{ L }};
+var B = {{ B }};
+var D = {{ D }};
+var rho_sea = {{ rho_sea }};
+var g = {{ g }};
+var Cb = {{ Cb }};
+var d_f = {{ d_f }};
+var rho_g_lo = {{ rho_g_lo }};
+var rho_g_hi = {{ rho_g_hi }};
+// --- this case
+var draft = {{ draft }};
+var mu_deg = {{ mu_deg }};
+var k_c = {{ k_c }};
+var k_u = {{ k_u }};
+var beta_VAC = {{ beta_VAC }};
+var beta_LAC = {{ beta_LAC }};
+var beta_TAC = {{ beta_TAC }};
+var beta_PMO = {{ beta_PMO }};
+var beta_RMO = {{ beta_RMO }};
+var k_esf = {{ k_esf }};
+var w_v = {{ w_v }};
+var w_l = {{ w_l }};
+var w_t = {{ w_t }};
+var xi = {{ xi }};
+var delta_b = {{ delta_b }};
+var delta_h = {{ delta_h }};
+// --- the tank this case names: {{ tank_ref }}
+var rho_tank = {{ rho_tank }};
+var l_tank = {{ l_tank }};
+var b_tank = {{ b_tank }};
+var h_tank = {{ h_tank }};
+var eta_deck = {{ eta_deck }};
+var eta_overflow = {{ eta_overflow }};
+var C_dp = {{ C_dp }};
+var C_ru = {{ C_ru }};
+var p_vp = {{ p_vp }};
+var GM_full_in = {{ GM_full_in }};
+var k_r_in = {{ k_r_in }};
+var tank_is_ballast = {{ tank_is_ballast }};
+var member_11_17 = {{ member_11_17 }};
+// --- the calculation
+var C_theta = 1;   // C_theta, the roll angle factor of 5.7.2(b)
+var C_phi = -0.45;   // C_phi, the pitch angle factor of 5.7.2(b)
+var k_theta = 0.005;   // k_theta of the theta expression (5.7.1(b))
+var C_R = 1.05;   // C_R of the theta expression (5.7.1(b))
+var k_o = 1.34 - 0.47 * Cb;   // k_o (5.7.1(c))
+var a_o = (k_o * (2.4 / Math.pow(L / 1 m, 0.5) + 34 / (L / 1 m) - 600 / Math.pow(L / 1 m, 2))) * 1 m;   // a_o, the vertical acceleration parameter
+var D_1 = (10 / Cb);   // the (10 / C_b) term of phi
+var phi = beta_PMO * k_esf * 1030 * Math.pow(D_1, 0.25) / (L / 1 m) * 1 deg;   // phi, the pitch amplitude
+if (phi > 10 deg) phi = 10 deg;
+else              phi = phi;
+var GM_full = GM_full_in > 0 m ? GM_full_in : 0.12 * B;   // 5.7.1(b): 0.12 B when GM(full) is not available
+var k_r = k_r_in > 0 m ? k_r_in : (draft <= d_f ? 0.35 * B : 0.45 * B);   // roll radius of gyration
+var Delta = 10.05 kN/m^3 * L * B * d_f * Cb;   // displacement, k_d = 10.05 kN/m^3
+var C_di = 1.06 * (draft / d_f) - 0.06;   // C_di = 1.06 (d_i/d_f) - 0.06
+var GM = GM_full;   // GM at the draft evaluated, filled in below
+if      (draft / d_f >= 1)   GM = GM_full;
+else if (draft / d_f >= 0.9) GM = 1.1 * GM_full;
+else if (draft / d_f >= 2/3) GM = 1.5 * GM_full;
+else if (draft / d_f >= 0.5) GM = 2.0 * GM_full;
+else                         GM = GM_full;
+var T_r = 2 * k_r * Math.pow(GM / 1 m, -0.5) / 1 m * 1 s;   // T_r, the roll natural period, in seconds
+var theta = C_R * beta_RMO * k_esf * (35 - k_theta * C_di * Delta / 1000 kN) * 1 deg;   // theta, the roll amplitude
+if      (T_r > 20 s)              theta = theta;
+else if (T_r >= 12.5 s)           theta = theta * (1.5375 - 0.027 * T_r / 1 s);
+else                              theta = theta * (0.8625 + 0.027 * T_r / 1 s);
+if (theta > 30 deg) theta = 30 deg;
+else                theta = theta;
+var k_v = Math.pow(1 + 0.65 * Math.pow(5.3 - 45 / (L / 1 m), 2) * Math.pow(x / L - 0.45, 2), 0.5);   // k_v (5.7.1(c))
+var C_v = Math.cos(mu_deg) + (1 + 2.4 * z / B) * Math.sin(mu_deg) / k_v;   // C_v (5.7.1(c))
+var C_l = 0.35 - 0.0005 * (L / 1 m - 200);   // C_l (5.7.1(c))
+var k_l = 0.5 + 8 * y / L;   // k_l (5.7.1(c)), the VERTICAL distribution
+var C_t = 1.27 * Math.pow(1 + 1.52 * Math.pow(x / L - 0.45, 2), 0.5);   // C_t (5.7.1(c))
+var k_t = 0.35 + y / B;   // k_t (5.7.1(c)), the VERTICAL distribution
+var a_v = C_v * beta_VAC * k_esf * k_v * a_o / 1 m * g;   // a_v, positive downward
+var a_l = C_l * beta_LAC * k_esf * k_l * a_o / 1 m * g;   // a_l, positive forward
+var a_t = C_t * beta_TAC * k_esf * k_t * a_o / 1 m * g;   // a_t, positive starboard
+var rho_g = rho_tank * g;   // the liquid specific weight (5.7.2(a))
+var eta_overflow_add = Math.max(0.6666667 * eta_overflow, 760 mm);   // Fig. 12: 2/3 of the overflow distance, at least 760 mm
+var eta = h_tank + eta_deck + (eta_overflow > 0 m ? eta_overflow_add : 0 m) - z;   // eta, measured down from the tank top
+var k_s = 1;   // k_s, filled in below
+if (tank_is_ballast != 0 || member_11_17 == 0) {
+    k_s = 1;
+} else {
+    k_s = 0.878 + (rho_g - rho_g_lo) / (rho_g_hi - rho_g_lo) * 0.122;
+    if (k_s < 0.878) k_s = 0.878;
+    else             k_s = k_s;
+    if (k_s > 1)     k_s = 1;
+    else             k_s = k_s;
+}
+var p_o = p_vp > 0 N/cm^2 ? Math.max(p_vp - 2.06 N/cm^2, 0 N/cm^2) : 0 N/cm^2;   // p_o = (p_vp - p_n), p_n = 2.06 N/cm^2
+var a_i = 0.71 * C_dp * (w_v * a_v + w_l * (l_tank / h_tank) * a_l + w_t * (b_tank / h_tank) * a_t);   // a_i (5.7.2(a))
+var theta_e = 0.71 * C_theta * theta;   // theta_e (5.7.2(b))
+var phi_e = 0.71 * C_phi * phi;   // phi_e (5.7.2(b))
+var zeta = Math.abs(b_tank / 2 - z);   // zeta, from the tank centre line
+var zeta_e = zeta;   // zeta_e, filled in below
+var eta_e = eta;   // eta_e, filled in below
+var dh_i = 0 m;   // delta h_i, filled in below
+if (phi_e < 0 deg && theta_e > 0 deg) {
+    // branch i of 5.7.2(b)
+    zeta_e = b_tank - zeta;
+    eta_e = eta;
+    dh_i = xi * Math.sin(-phi_e) + C_ru * (zeta_e * Math.sin(theta_e) * Math.cos(phi_e)
+         + eta_e * Math.cos(theta_e) * Math.cos(phi_e) - eta);
+} else {
+    // branch ii of 5.7.2(b)
+    zeta_e = zeta - delta_b;
+    eta_e = eta - delta_h;
+    dh_i = (l_tank - xi) * Math.sin(-phi_e) + C_ru * (zeta_e * Math.sin(theta_e) * Math.cos(phi_e)
+         + eta_e * Math.cos(theta_e) * Math.cos(phi_e) - eta);
+}
+var h_d = k_c * (eta * a_i / g + dh_i);   // h_d = k_c (eta a_i / g + delta h_i) (5.7.2(a))
+var p_s = k_s * rho_g * eta;   // static pressure (5.7.2(a))
+var p_d = k_s * rho_g * k_u * h_d;   // dynamic pressure (5.7.2(a))
+return p_s + p_d + p_o;   // the pressure the function returns

excel_codegen/examples/abs_fpi/templates/int_summary.md.j2

@@ -0,0 +1,30 @@
+| 项目 | 值 | 出处 |
+| --- | --- | --- |
+| case_name | {{ case_name }} | 工况名（Excel 表头） |
+| kind | {{ kind }} | 规则集（多规则集共用一本工作簿时用 case_filter 分流） |
+| tank_ref | {{ tank_ref }} | 指向成员表 `Tank Data` 的哪一行（指南 §18） |
+| draft | {{ draft }} | 装载工况 |
+| mu_deg | {{ mu_deg }} | Table 1A D |
+| k_c | {{ k_c }} | Table 1A C |
+| k_u | {{ k_u }} | 5A-3-2/7, /9 |
+| beta_VAC | {{ beta_VAC }} | 5A-3-A1/3 |
+| beta_LAC | {{ beta_LAC }} | 5A-3-A1/3 |
+| beta_TAC | {{ beta_TAC }} | 5A-3-A1/3 |
+| beta_PMO | {{ beta_PMO }} | 5A-3-A1/3 |
+| beta_RMO | {{ beta_RMO }} | 5A-3-A1/3 |
+| k_esf | {{ k_esf }} | 项目 |
+| w_v / w_l / w_t | {{ w_v }} / {{ w_l }} / {{ w_t }} | Table 1A B |
+| xi | {{ xi }} | 5.7.2(b) |
+| delta_b / delta_h | {{ delta_b }} / {{ delta_h }} | 5.7.2(b) |
+| rho_tank | {{ rho_tank }} | 成员表 Tank Data |
+| l_tank / b_tank / h_tank | {{ l_tank }} / {{ b_tank }} / {{ h_tank }} | Fig. 11 |
+| eta_deck / eta_overflow | {{ eta_deck }} / {{ eta_overflow }} | Fig. 12 |
+| C_dp / C_ru | {{ C_dp }} / {{ C_ru }} | 5.7.2(d) |
+| p_vp | {{ p_vp }} | 成员表 Tank Data |
+| GM_full_in / k_r_in | {{ GM_full_in }} / {{ k_r_in }} | 稳性计算书 |
+| tank_is_ballast / member_11_17 | {{ tank_is_ballast }} / {{ member_11_17 }} | Table 3 |
+| L / B / D / d_f | {{ L }} / {{ B }} / {{ D }} / {{ d_f }} | 3-1-1/3 |
+| rho_sea / g / Cb | {{ rho_sea }} / {{ g }} / {{ Cb }} | 5.7.1 |
+| rho_g_lo / rho_g_hi | {{ rho_g_lo }} / {{ rho_g_hi }} | 5.7.2(a) |
+| axis ax | ({{ ax_x }}, {{ ax_y }}, {{ ax_z }}) | 模型 |
+| axis neg | ({{ neg_x }} / {{ neg_y }} / {{ neg_z }}) | 模型 |

excel_codegen/examples/basic/example.yaml

@@ -0,0 +1,97 @@
+version: 1
+
+# --------------------------------------------------------------------------- #
+# Excel 模板文件的生成配置
+# --------------------------------------------------------------------------- #
+excel:
+  output: "template.xlsx"
+  template_sheet: "Template"     # 隐藏工作表，保存模板原文；设为 null 可关闭
+  sheets:
+    global: "Global Parameter"
+    local: "Local Parameter"
+    outputs: ["Output", "Output Vertical"]
+
+# --------------------------------------------------------------------------- #
+# 变量定义
+#   global : 对所有 Case 生效（Excel 中只有一列取值）
+#   local  : 每个 Case 一份取值。默认一个工况一列（Excel 中从 E 列开始）；
+#            把 excel.local_direction 改成 vertical 就变成一行一个工况（A 列写 Case 名）——
+#            适合把按行给出的工况数据整块粘进表里（指南 §19）
+# --------------------------------------------------------------------------- #
+variables:
+  global:
+    - name: baud
+      description: "波特率"
+      unit: "bps"
+      default: 115200
+      prefix: ""
+      suffix: ""
+      type: int
+      # 取值约束：越界在 validate / render 时就报错，并写成 Excel 的数值范围校验
+      min: 300
+      max: 4000000
+    - name: baud_div
+      description: "分频值 = baud / 16（派生参数：引用另一个参数，不用手填）"
+      derived: "baud / 16"
+      type: float
+    - name: mcu
+      description: "MCU 型号（字符串变量示例）"
+      default: "STM32F103"
+      prefix: ""
+      suffix: ""
+      pattern: "^STM32[A-Z][0-9]{3}[A-Z]{0,2}$"
+
+  local:
+    - name: port
+      description: "端口"
+      default: "A"
+      prefix: "GPIO"
+      suffix: "_PORT"
+      pattern: "^[A-H]$"
+    - name: mode
+      description: "模式（取值约束：Excel 里会变成下拉列表）"
+      default: "TX_RX"
+      prefix: "MODE_"
+      suffix: ""
+      choices: ["TX", "RX", "TX_RX"]
+
+# --------------------------------------------------------------------------- #
+# 输出模板
+# --------------------------------------------------------------------------- #
+templates:
+  # 横向布局：每个 Case 占 Output 表的一列，结果行向下展开
+  #
+  # ⚠ 这里**显式**写 engine: snapshot（默认是 excel / 公式模式）。
+  #   因为下面用了过滤器（{{ port.value | pvs(...) }}），而公式模式表达不了过滤器。
+  #   想体验"改 Excel 就改输出"请看 examples/example_formula.yaml 与
+  #   examples/nastran_case_control.yaml —— 那两个都是默认的公式模式。
+  - name: uart_init
+    description: "UART 初始化代码（快照模式）"
+    output_sheet: "Output"
+    start_cell: "B2"
+    direction: "horizontal"
+    write_case_headers: true
+    engine: "snapshot"
+    filename: "uart_init_{{ case_name }}.c"
+    code: |
+      // Case: {{ case_name }}
+      UART_Init({{ baud }}, {{ port }}, {{ mode }});
+      // 纯值: {{ port.value }}, 前缀: {{ port.prefix }}, 后缀: {{ port.suffix }}
+      // 分频: {{ baud_div }}
+      // 过滤器: {{ port.value | pvs("GPIO", "_PORT") }}
+      // MCU: {{ mcu }}
+
+  # 纵向布局：每个 Case 占一行，结果行向右展开
+  - name: uart_summary
+    description: "UART 配置汇总表（Markdown，快照模式）"
+    output_sheet: "Output Vertical"
+    start_cell: "B2"
+    direction: "vertical"
+    write_case_headers: true
+    engine: "snapshot"
+    filename: "uart_summary_{{ case_name }}.md"
+    code: |
+      | case_name | baud | port | mode |
+      | --- | --- | --- | --- |
+      | {{ case_name }} | {{ baud }} | {{ port }} | {{ mode }} |
+      | 纯值/组合值 | {{ baud.value }} | {{ port.value | wrap("GPIO", "_PORT") }} | 前缀={{ mode.prefix }} 纯值={{ mode.value }} |

excel_codegen/examples/basic/example_formula.yaml

@@ -0,0 +1,86 @@
+version: 1
+
+# --------------------------------------------------------------------------- #
+# 公式模式示例 —— 也是**默认**引擎
+#
+# 这就是本工具推荐的用法：写一个 YAML → 生成一本 Excel → 之后就在 Excel 里干活。
+# Output 表里写进去的是**公式**而不是文本快照 —— 改了 Global / Local 的参数之后，
+# Excel 打开即自动重算，**不需要再跑任何命令**，工作簿脱离命令行也独立可用。
+#
+# （下面每个模板仍然写了 `engine: "excel"`，只是为了让你一眼看到这个字段；
+#   不写也是公式模式。对照示例见 example.yaml，它显式声明了 engine: snapshot。）
+#
+# 代价（务必知悉）：
+#   1. 只支持"占位符替换 + 单行 {% if %}"：{{ x }} / {{ x.value }} / {{ x.prefix }} /
+#      {{ x.suffix }} / {{ case_name }} / {{ template_name }}；{% if %} 会编译成 Excel 的
+#      IF()（指南 §14.1.1）。{% for %} / 过滤器 / 多行 {% if %} 会直接报错（带行号）；
+#   2. 值只存在于 Excel / WPS 里：导出代码文件（--outdir）与 CI 检查（check）仍走命令行；
+#   3. 改模板（这个 YAML）需要重跑一次 --write-excel 刷新公式，改参数不用。
+# --------------------------------------------------------------------------- #
+excel:
+  output: "template_formula.xlsx"
+  template_sheet: "Template"
+  howto_sheet: "HOWTO"
+  sheets:
+    global: "Global Parameter"
+    local: "Local Parameter"
+    outputs: ["Output", "Output Vertical"]
+
+variables:
+  global:
+    - name: baud
+      description: "波特率"
+      default: 115200
+      prefix: ""
+      suffix: ""
+      type: int
+    - name: baud_khz
+      description: "波特率（kHz）= baud / 1000 —— 派生参数示例"
+      derived: "baud / 1000"          # ← 引用另一个参数，不用自己在表里算
+      type: float
+    - name: mcu
+      description: "MCU 型号（字符串变量示例）"
+      default: "STM32F103"
+      prefix: ""
+      suffix: ""
+
+  local:
+    - name: port
+      description: "端口"
+      default: "A"
+      prefix: "GPIO"
+      suffix: "_PORT"
+    - name: mode
+      description: "模式"
+      default: "TX_RX"
+      prefix: "MODE_"
+      suffix: ""
+
+templates:
+  # 横向：一个 Case 一列；每行一个公式，右拉即多一个 Case
+  - name: uart_init
+    description: "UART 初始化代码（公式模式）"
+    output_sheet: "Output"
+    start_cell: "B2"
+    direction: "horizontal"
+    write_case_headers: true
+    engine: "excel"
+    filename: "uart_init_{{ case_name }}.c"
+    code: |
+      // Case: {{ case_name }}
+      UART_Init({{ baud }}, {{ port }}, {{ mode }});
+      // 纯值: {{ port.value }}, 前缀: {{ port.prefix }}, 后缀: {{ port.suffix }}
+      // 派生参数: {{ baud_khz }} kHz
+      // MCU: {{ mcu }}
+
+  # 纵向：一个 Case 一行（公式一样有效，只是右拉会换列）
+  - name: uart_pins
+    description: "端口占用表（公式模式，纵向）"
+    output_sheet: "Output Vertical"
+    start_cell: "B2"
+    direction: "vertical"
+    write_case_headers: true
+    engine: "excel"
+    filename: "uart_pins_{{ case_name }}.csv"
+    code: |
+      {{ case_name }},{{ port }},{{ mode }},{{ baud }}

excel_codegen/examples/basic/generated/uart_init_Case1.c

@@ -0,0 +1,6 @@
+// Case: Case1
+UART_Init(115200, GPIOA_PORT, MODE_TX_RX);
+// 纯值: A, 前缀: GPIO, 后缀: _PORT
+// 分频: 7200
+// 过滤器: GPIOA_PORT
+// MCU: STM32F103

excel_codegen/examples/basic/generated/uart_init_Case2.c

@@ -0,0 +1,6 @@
+// Case: Case2
+UART_Init(115200, GPIOA_PORT, MODE_TX_RX);
+// 纯值: A, 前缀: GPIO, 后缀: _PORT
+// 分频: 7200
+// 过滤器: GPIOA_PORT
+// MCU: STM32F103

excel_codegen/examples/basic/generated/uart_summary_Case1.md

@@ -0,0 +1,4 @@
+| case_name | baud | port | mode |
+| --- | --- | --- | --- |
+| Case1 | 115200 | GPIOA_PORT | MODE_TX_RX |
+| 纯值/组合值 | 115200 | GPIOA_PORT | 前缀=MODE_ 纯值=TX_RX |

excel_codegen/examples/basic/generated/uart_summary_Case2.md

@@ -0,0 +1,4 @@
+| case_name | baud | port | mode |
+| --- | --- | --- | --- |
+| Case2 | 115200 | GPIOA_PORT | MODE_TX_RX |
+| 纯值/组合值 | 115200 | GPIOA_PORT | 前缀=MODE_ 纯值=TX_RX |

excel_codegen/examples/basic/generated_formula/uart_init_Case1.c

@@ -0,0 +1,5 @@
+// Case: Case1
+UART_Init(115200, GPIOA_PORT, MODE_TX_RX);
+// 纯值: A, 前缀: GPIO, 后缀: _PORT
+// 派生参数: 115.2 kHz
+// MCU: STM32F103

excel_codegen/examples/basic/generated_formula/uart_init_Case2.c

@@ -0,0 +1,5 @@
+// Case: Case2
+UART_Init(115200, GPIOA_PORT, MODE_TX_RX);
+// 纯值: A, 前缀: GPIO, 后缀: _PORT
+// 派生参数: 115.2 kHz
+// MCU: STM32F103

excel_codegen/examples/basic/generated_formula/uart_pins_Case1.csv

@@ -0,0 +1 @@
+Case1,GPIOA_PORT,MODE_TX_RX,115200

excel_codegen/examples/basic/generated_formula/uart_pins_Case2.csv

@@ -0,0 +1 @@
+Case2,GPIOA_PORT,MODE_TX_RX,115200

excel_codegen/examples/basic/template_formula_render.bat

@@ -0,0 +1,22 @@
+@echo off
+REM ===========================================================================
+REM  由 excel_codegen 生成 —— 改完参数双击本文件即可把结果写回 Output 表。
+REM  重新生成工作簿（init）时会一并覆盖本文件。
+REM ===========================================================================
+cd /d "%~dp0"
+
+where uv >nul 2>nul
+if %errorlevel%==0 (
+  uv run excel-codegen render -c "example_formula.yaml" -x "template_formula.xlsx" --write-excel
+) else (
+  excel-codegen render -c "example_formula.yaml" -x "template_formula.xlsx" --write-excel
+)
+
+echo.
+if errorlevel 1 (
+  echo [失败] 上面有报错信息。常见原因：依赖没装（跑一次 setup.sh / uv sync）、
+  echo        或者 Excel 正开着这个文件（先关掉再试）。
+) else (
+  echo [完成] 回到 Excel 打开「Output」表看结果。
+)
+pause

excel_codegen/examples/basic/template_formula_render.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# ===========================================================================
+#  由 excel_codegen 生成 —— 改完参数跑一次本文件即可把结果写回 Output 表。
+#  重新生成工作簿（init）时会一并覆盖本文件。
+# ===========================================================================
+set -uo pipefail
+cd "$(dirname "$0")"
+
+if command -v uv >/dev/null 2>&1; then
+  uv run excel-codegen render -c "example_formula.yaml" -x "template_formula.xlsx" --write-excel
+else
+  excel-codegen render -c "example_formula.yaml" -x "template_formula.xlsx" --write-excel
+fi
+status=$?
+
+echo
+if [ "$status" -ne 0 ]; then
+  echo "[失败] 上面有报错信息。常见原因：依赖没装（跑一次 ./setup.sh 或 uv sync）、"
+  echo "       或者 Excel / WPS 正开着这个文件（先关掉再试）。"
+else
+  echo "[完成] 回到 Excel 打开「Output」表看结果。"
+fi
+exit "$status"

excel_codegen/examples/basic/template_render.bat

@@ -0,0 +1,22 @@
+@echo off
+REM ===========================================================================
+REM  由 excel_codegen 生成 —— 改完参数双击本文件即可把结果写回 Output 表。
+REM  重新生成工作簿（init）时会一并覆盖本文件。
+REM ===========================================================================
+cd /d "%~dp0"
+
+where uv >nul 2>nul
+if %errorlevel%==0 (
+  uv run excel-codegen render -c "example.yaml" -x "template.xlsx" --write-excel
+) else (
+  excel-codegen render -c "example.yaml" -x "template.xlsx" --write-excel
+)
+
+echo.
+if errorlevel 1 (
+  echo [失败] 上面有报错信息。常见原因：依赖没装（跑一次 setup.sh / uv sync）、
+  echo        或者 Excel 正开着这个文件（先关掉再试）。
+) else (
+  echo [完成] 回到 Excel 打开「Output」表看结果。
+)
+pause

excel_codegen/examples/basic/template_render.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# ===========================================================================
+#  由 excel_codegen 生成 —— 改完参数跑一次本文件即可把结果写回 Output 表。
+#  重新生成工作簿（init）时会一并覆盖本文件。
+# ===========================================================================
+set -uo pipefail
+cd "$(dirname "$0")"
+
+if command -v uv >/dev/null 2>&1; then
+  uv run excel-codegen render -c "example.yaml" -x "template.xlsx" --write-excel
+else
+  excel-codegen render -c "example.yaml" -x "template.xlsx" --write-excel
+fi
+status=$?
+
+echo
+if [ "$status" -ne 0 ]; then
+  echo "[失败] 上面有报错信息。常见原因：依赖没装（跑一次 ./setup.sh 或 uv sync）、"
+  echo "       或者 Excel / WPS 正开着这个文件（先关掉再试）。"
+else
+  echo "[完成] 回到 Excel 打开「Output」表看结果。"
+fi
+exit "$status"

excel_codegen/examples/nastran/generated/case_control.deck

@@ -0,0 +1,18 @@
+SUBCASE 1
+SUBTITLE = HEAD SEA
+LOAD = 1001
+SPC = 1
+SUBCASE 2
+SUBTITLE = BEAM SEA
+LOAD = 1002
+SPC = 1
+SUBCASE 3
+LABEL = QTR
+SUBTITLE = QUARTERING SEA
+METHOD = 1
+LOAD = 1003
+SPC = 2
+SUBCOM 4
+SUBTITLE = COMBINED 1.0 / 1.2 / 1.3
+SUBSEQ = 1, 1.2, 1.3
+SUBCASE 5

excel_codegen/examples/nastran/generated/cc_01_LC1.inc

@@ -0,0 +1,8 @@
+SUBCASE 1
+
+SUBTITLE = HEAD SEA
+
+
+LOAD = 1001
+SPC = 1
+