@sheetxl/skills 0.0.0-stage → 0.8.0-beta.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -0
- package/README.md +67 -2
- package/SKILL.md +398 -0
- package/package.json +31 -3
- package/references/analysis.md +532 -0
- package/references/charts.md +173 -0
- package/references/cli.md +287 -0
- package/references/embedding.md +74 -0
- package/references/financial-models.md +364 -0
- package/references/interactive.md +194 -0
- package/references/reading.md +708 -0
- package/references/scripting.md +198 -0
- package/references/sessions.md +225 -0
- package/references/setup.md +74 -0
- package/references/showcase.md +32 -0
- package/references/udf.md +400 -0
- package/references/vector.md +129 -0
- package/references/writing.md +368 -0
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: charts
|
|
3
|
+
description: "SheetXL charts: reading what a chart plots, inserting one, and editing it — type, data, title, legend, axes, series, points, data labels, trendlines, error bars — through the chart API, Office Scripts' names. Load when a task mentions a chart. Triggers on: chart, getCharts, IChart, series, axis, legend, data labels, trendline, error bars, plot, graph."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Charts — Read, Insert, Edit
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing. Code below
|
|
9
|
+
> is run-context code (`scripting.md`): snippet form — no `await` needed on the
|
|
10
|
+
> statements shown as plain calls (every statement auto-awaits); `getCharts().add`
|
|
11
|
+
> returns a promise and is awaited like any other.
|
|
12
|
+
|
|
13
|
+
**In this file:** What a chart is here · Reading a chart · Inserting one ·
|
|
14
|
+
Editing: the chart, its series, axes, elements · What is refused · Verify
|
|
15
|
+
|
|
16
|
+
## What a chart is here
|
|
17
|
+
|
|
18
|
+
A chart is a movable (`sheet.getMovables()`, type `chart`) whose content is an
|
|
19
|
+
`IChart`. It plots cells: every series states its name, categories and values as
|
|
20
|
+
formulas (`Data!$B$2:$B$7`), the way Excel's own dialog does. The API follows
|
|
21
|
+
Office Scripts' names (`getSeries`, `setChartType`, `getAxes().getValueAxis()`,
|
|
22
|
+
`getDataLabels`, `addChartTrendline`), so what you know from `ExcelScript.Chart`
|
|
23
|
+
carries over; VBA's names are noted where they differ.
|
|
24
|
+
|
|
25
|
+
Every setter writes exactly what Excel writes for the same change and is one step
|
|
26
|
+
to undo. A chart edited here opens in Excel as if Excel had made the edit.
|
|
27
|
+
|
|
28
|
+
## Reading a chart
|
|
29
|
+
|
|
30
|
+
The reports already say what a chart plots: the sheet report's `Charts` section
|
|
31
|
+
lists each chart with `series`, `names`, `categories`; a chart's own report
|
|
32
|
+
(`renderMovable`) adds its title, legend, axes and the analysis on its series
|
|
33
|
+
(`reading.md`). For more, ask the chart:
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
const chart = sheet.getCharts().getItems()[0]; // or sheet.getCharts().getByName('Chart 2')
|
|
37
|
+
chart.getChartType(); // 'columnClustered', 'line', 'pie', 'combo', …
|
|
38
|
+
chart.getChartTitle(); // the text, a cell's text when it reads one
|
|
39
|
+
chart.getSeries().map(s => [s.getName(), s.getValuesFormula(), s.getCategoriesFormula()]);
|
|
40
|
+
chart.getAxes().getItems().map(a => [a.getKind(), a.getTitle().getText(), a.getNumberFormat()]);
|
|
41
|
+
chart.getLegend().getPosition(); // 'bottom' | 'right' | 'top' | 'left' | 'corner'
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
A series' `getValuesRange()` is the cells, or `null` when the formula names
|
|
45
|
+
none (`#REF!`, a name, a literal `{1,2,3}`). A pivot chart (`getPivotSource()`)
|
|
46
|
+
states its table; its ranges are wherever the table last put its cells.
|
|
47
|
+
|
|
48
|
+
## Inserting a chart
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
const chart = await sheet.getCharts().add('A1:D7', { type: 'line' });
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The cells are read by Excel's rules: a header row names the series, the first
|
|
55
|
+
column holds the categories, and the series are the columns unless there are more
|
|
56
|
+
columns than rows (`seriesBy: 'rows' | 'columns'` to say). `type` is any type
|
|
57
|
+
Excel's gallery offers — `columnClustered`, `columnStacked`, `columnStacked100`,
|
|
58
|
+
`bar…`, `line`, `lineMarkers`, `area…`, `pie`, `doughnut`, `xyscatter…`,
|
|
59
|
+
`bubble`, `radar…`, `stockVHLC`…, the 3-D forms (`3DColumnClustered`, `3DPie`…),
|
|
60
|
+
the surfaces, and the 2016 types (`waterfall`, `treemap`, `sunburst`, `histogram`,
|
|
61
|
+
`pareto`, `boxwhisker`, `funnel`, `regionMap`), which are made and saved as Excel
|
|
62
|
+
makes them but drawn as a placeholder for now. The chart is 5 by 3 inches in the
|
|
63
|
+
middle of the window unless `bounds` says otherwise.
|
|
64
|
+
|
|
65
|
+
## Editing
|
|
66
|
+
|
|
67
|
+
### The chart
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
chart.setChartType('lineMarkers'); // every series; a combo becomes one group
|
|
71
|
+
chart.setData('Data!A1:E7', 'columns'); // other cells, same formatting where series take their place
|
|
72
|
+
chart.setSeriesBy('rows'); // Switch Row/Column
|
|
73
|
+
chart.update({ title: 'Sales by Month', legend: { position: 'right' } });
|
|
74
|
+
chart.getTitle().setText('=Data!$A$1'); // a title that follows a cell
|
|
75
|
+
chart.setElement('legendTop'); // any Add Chart Element pick, by VBA's msoElement… name
|
|
76
|
+
chart.update({ style: { fill: '#F2F2F2', font: { family: 'Arial', size: 11 } }, roundedCorners: true });
|
|
77
|
+
chart.getDataTable().update({ visible: true, showLegendKey: true });
|
|
78
|
+
chart.getDataLabels().setVisible(true); // every series' labels
|
|
79
|
+
chart.getMovable().setBounds({ x: 480, y: 20, width: 480, height: 288 }); // px; placement is the movable's
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`update` takes several properties at once as one undo step. `setElement` takes
|
|
83
|
+
the element names of `MsoChartElementType` without the prefix, in lower camel
|
|
84
|
+
case: `chartTitleAboveChart`, `dataLabelOutsideEnd`, `primaryValueGridLinesMinor`,
|
|
85
|
+
`primaryCategoryAxisTitleBelowAxis`, `trendlineAddLinear`, `errorBarStandardError`,
|
|
86
|
+
`upDownBarsShow`, `dataTableWithLegendKeys`, …
|
|
87
|
+
|
|
88
|
+
### Series and points
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
const s = chart.getSeries()[0];
|
|
92
|
+
s.update({ name: 'Total', values: 'D2:D7' });
|
|
93
|
+
s.setFormula('=SERIES(Data!$D$1,Data!$A$2:$A$7,Data!$D$2:$D$7,1)');
|
|
94
|
+
s.setChartType('line'); s.setAxisGroup('secondary'); // a combo
|
|
95
|
+
s.update({ style: { fill: '#FF0000', stroke: { width: 2 } }, gapWidth: 50, smooth: true });
|
|
96
|
+
s.getDataLabels().update({ visible: true, position: 'outsideEnd', numberFormat: '0.0', showPercentage: true });
|
|
97
|
+
s.getPoints()[2].update({ style: { fill: '#00B050' }, explosion: 20, hasDataLabel: true });
|
|
98
|
+
s.addChartTrendline('polynomial').update({ polynomialOrder: 3, showEquation: true, showRSquared: true });
|
|
99
|
+
s.getYErrorBars().update({ type: 'stDev', amount: 1 });
|
|
100
|
+
s.getMarker().update({ symbol: 'diamond', size: 8 });
|
|
101
|
+
chart.addSeries('East').update({ values: 'D2:D7' });
|
|
102
|
+
s.delete();
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
A series' categories are shared by every series on its axis: setting them on one
|
|
106
|
+
sets them all (as Excel does). `setFormula` takes Excel's `=SERIES(name, categories,
|
|
107
|
+
values, order[, sizes])`, every part optional.
|
|
108
|
+
|
|
109
|
+
### Axes
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
const value = chart.getAxes().getValueAxis(); // the primary; getChartAxis('value', 'secondary') for the other
|
|
113
|
+
value.update({ minimum: 0, maximum: 40, majorUnit: 10, minorUnit: 2, numberFormat: '#,##0', title: 'Units' });
|
|
114
|
+
value.update({ scaleType: 'logarithmic', logBase: 10, displayUnit: 'thousands', showDisplayUnitLabel: true });
|
|
115
|
+
value.update({ reversePlotOrder: true, crosses: 'maximum', majorTickMark: 'cross', tickLabelPosition: 'high' });
|
|
116
|
+
const category = chart.getAxes().getCategoryAxis();
|
|
117
|
+
category.update({ majorGridlines: true, textOrientation: 45, categoryNames: 'H2:I7', multiLevel: true });
|
|
118
|
+
category.update({ categoryType: 'dateAxis', baseTimeUnit: 'days', majorUnit: 1, majorTimeUnitScale: 'months' });
|
|
119
|
+
value.getTitle().update({ text: 'Units', textOrientation: 0, style: { font: { bold: true } } });
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`minimum`, `maximum` and the units read as the layout draws them and take
|
|
123
|
+
`'auto'` to be automatic again.
|
|
124
|
+
|
|
125
|
+
### Elements
|
|
126
|
+
|
|
127
|
+
Every part of a chart is an element with a path, and the chart answers the path
|
|
128
|
+
with the same object for as long as the part is there:
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
chart.getElements().map(e => e.getPath()); // what the chart shows: 'title', 'axes/primary/value', 'series/0', …
|
|
132
|
+
const t = chart.getElement('axes/primary/value/title'); // null where there is none
|
|
133
|
+
t?.getElementType(); // 'axisTitle'
|
|
134
|
+
chart.getElement('series/0/points/2')?.getStyle?.()?.setFill('#00B050');
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Paths: `chartArea`, `title`, `legend`, `legend/entries/<n>`, `plotArea`,
|
|
138
|
+
`dataTable`, `axes/<primary|secondary>/<category|value|series>` (with `/title`,
|
|
139
|
+
`/majorGridlines`, `/minorGridlines`), `series/<key>` (with `/marker`,
|
|
140
|
+
`/dataLabels`, `/errorBars/<x|y>`, `/trendlines/<n>`, `/points/<n>`,
|
|
141
|
+
`/points/<n>/marker`, `/points/<n>/dataLabel`), `groups/<n>` (with
|
|
142
|
+
`/upDownBars`, `/hiLoLines`, `/dropLines`, `/seriesLines`). A series' key is its
|
|
143
|
+
`c:idx`; points, trendlines and groups go by their place, from 0. Each element
|
|
144
|
+
has a type flag (`isISeries`, `isIAxis`, `isITitle`, …) and, where it is drawn,
|
|
145
|
+
`getStyle()`: fill and line (`IShapeStyle`), and on a part with text (chart area,
|
|
146
|
+
title, axis title, legend, legend entry, axis, data labels, data table) also
|
|
147
|
+
`getStyle().getFont()` (`ITextBoxStyle`, `isITextBoxStyle`). There is no
|
|
148
|
+
`getFont()` on a part. The font is an `IFontStyle` (family, size, bold, italic,
|
|
149
|
+
underline, strike, color, letter spacing, baseline), the same interface a cell's
|
|
150
|
+
`range.getStyle().getFont()` answers, so the same code formats either; `update`
|
|
151
|
+
nests it the same way: `title.update({ style: { fill: 'white', font: { bold: true } } })`.
|
|
152
|
+
`chart.getStyle().getFont()` sets every text in the chart. A legend entry's fill
|
|
153
|
+
and line are the legend's; setting them throws. A theme font is the family
|
|
154
|
+
`'theme:body'` or `'theme:heading'`.
|
|
155
|
+
|
|
156
|
+
## What is refused
|
|
157
|
+
|
|
158
|
+
Each refusal is an `ExpectedError` saying why; nothing is written.
|
|
159
|
+
|
|
160
|
+
- A 2016 type (waterfall, histogram, pareto, box and whisker, treemap, sunburst,
|
|
161
|
+
funnel, region map): its title, legend and type are edited; the rest is not yet,
|
|
162
|
+
and it is drawn as a placeholder.
|
|
163
|
+
- A pivot chart: it changes with its table.
|
|
164
|
+
- A property Excel refuses for the type: a trendline on a pie, drop lines on a
|
|
165
|
+
column chart, a bubble size label on a line, `setChartType` to a stock type.
|
|
166
|
+
- An address that is not one. A reference to cells that are gone (`#REF!`) is kept,
|
|
167
|
+
as Excel keeps it, and the series plots nothing.
|
|
168
|
+
|
|
169
|
+
## Verify
|
|
170
|
+
|
|
171
|
+
Read back what you set — `chart.getChartType()`, `series.getValuesFormula()`,
|
|
172
|
+
`axis.getMinimum()` — and the chart's report (`renderMovable`). Saved to `.xlsx`, a
|
|
173
|
+
chart reads back as the same chart and opens in Excel without repair.
|
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cli
|
|
3
|
+
description: "SheetXL terminal commands: executing SDK code against a workbook file, grep, info, setup, and the interactive session. Flags (-e, -c, -f, -i, --out, --save, --json, --md.features), chaining scripts, shell composition, CI. Triggers on: npx sheetxl, sheetxl grep, sheetxl info, -e, -c, -f, --out, --save, --json, REPL, terminal, command line, automate."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CLI — Terminal Commands
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
|
|
9
|
+
> How to *write* the code you run is `scripting.md`; this is how to invoke it.
|
|
10
|
+
|
|
11
|
+
**In this file:** The grammar · compile — typecheck without running · Large
|
|
12
|
+
workbooks — parsing repeats · Structured questions are one-liners · grep ·
|
|
13
|
+
Interactive sessions · Composition
|
|
14
|
+
|
|
15
|
+
| Command | Purpose |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `sheetxl [options] [workbook]` | The main event: execute SDK TypeScript against a workbook — including every structured question. Return `getRegions()`, `getStats()`, a range, and the report renders. With no code, an interactive session. |
|
|
18
|
+
| `sheetxl info` | Read-only environment report: versions, skills, MCP status. Once per session. |
|
|
19
|
+
| `sheetxl setup` | Converge the environment (skills, engine, MCP registration) — consent at each step. |
|
|
20
|
+
| `sheetxl grep <pattern>` | Find cells by content or pattern. |
|
|
21
|
+
| `sheetxl compile <files…>` | Typecheck (and optionally emit) without executing. |
|
|
22
|
+
|
|
23
|
+
Zero-install: prefix any command with `npx -y` (`npx -y sheetxl info`).
|
|
24
|
+
|
|
25
|
+
## The grammar
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
sheetxl [options] [workbook]
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
There is **no `run` verb** — the operation is the default, the way `duckdb -c
|
|
32
|
+
"<sql>" my.db` needs no verb. One rule decides the mode:
|
|
33
|
+
|
|
34
|
+
> Give it code and it runs, prints, and exits. Give it none and you get an
|
|
35
|
+
> interactive session.
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
sheetxl -e "<code>" [workbook] # inline snippet
|
|
39
|
+
sheetxl -f <script.ts> [workbook] # script file; repeat -f to chain on the same workbook
|
|
40
|
+
sheetxl [workbook] < script.ts # code from stdin
|
|
41
|
+
sheetxl [workbook] # no code → interactive session
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The positional argument is the **workbook**, the same slot it fills in `grep`.
|
|
45
|
+
Code is never positional: it arrives through `-e`, `-f`, or stdin. Omit the
|
|
46
|
+
workbook and you get a blank one.
|
|
47
|
+
|
|
48
|
+
Prefer stdin (e.g. with a heredoc) over `-e` when the code is multi-line or
|
|
49
|
+
shell quoting gets awkward. **On PowerShell, make it the default** — a
|
|
50
|
+
single-quoted here-string piped in is literal, where `-e "…"` expands `$` and
|
|
51
|
+
backticks and dies on `!` the moment an inner quote breaks the outer string
|
|
52
|
+
(root `SKILL.md` has the form).
|
|
53
|
+
|
|
54
|
+
Flags:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
-e, -c <code> inline code, snippet or script; the result is rendered.
|
|
58
|
+
Repeatable (-c is an alias, for duckdb/python muscle memory)
|
|
59
|
+
-f <script> script file; repeatable, chained on the same workbook —
|
|
60
|
+
a chain renders the last one's result
|
|
61
|
+
-i, --interactive stay in an interactive session after the code runs
|
|
62
|
+
--out <file> write the workbook here; `-` writes it to stdout, for piping
|
|
63
|
+
--save write back to the workbook that was opened; naming a different
|
|
64
|
+
destination is `--out <file>`. With no input workbook, an error
|
|
65
|
+
--json the result as structured JSON, for piping (default is rendered text)
|
|
66
|
+
--no-delta omit the run delta: what a write changed, printed after the result
|
|
67
|
+
(`Changed:`, `Dependents:`, …). A read-only run prints none, and
|
|
68
|
+
neither does `--json`; a chain labels each target that wrote
|
|
69
|
+
--in.<key>=<value> format options for input (e.g. --in.csv.delimiter=";")
|
|
70
|
+
--out.<key>=<value> format options for output (e.g. --out.format=csv)
|
|
71
|
+
--md.<key>=<value> report options (--md.features=fill,borders, --md.mode=value)
|
|
72
|
+
-- <args…> forwarded to the run (in scope as `args`)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`-v` prints the CLI, engine and node versions on one line; `sheetxl info` is the full handshake.
|
|
76
|
+
`-h` is a short help, `--help` the complete one.
|
|
77
|
+
|
|
78
|
+
Anything else beginning with `-` is an error, suggesting the flag you probably meant. A script's
|
|
79
|
+
own arguments go after `--` — there is no implicit passthrough.
|
|
80
|
+
|
|
81
|
+
`--md.<key>` configures the *report*, not the query — the expression already says what was asked
|
|
82
|
+
for — which is why it is grouped under `--md` the way input and output options are grouped under
|
|
83
|
+
`--in.*` and `--out.*`. `--md.features` is what makes a formatting audit readable on a heavily styled
|
|
84
|
+
sheet:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
sheetxl -e "wb.getWorksheet()" book.xlsx --md.features=fill,borders
|
|
88
|
+
sheetxl -e "wb.getWorksheet('Model')" book.xlsx --md.features=formula,error # the audit view of one sheet
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The other key is `mode` — `display` (number format applied) or `value` (full precision,
|
|
92
|
+
formatting stripped). An unknown key or feature is an error listing the whole vocabulary, checked
|
|
93
|
+
before the workbook is read. `--json` does not read these and says so rather than ignoring them.
|
|
94
|
+
|
|
95
|
+
**Those two are the whole surface: it selects, it does not size.** There is no option for a longer
|
|
96
|
+
report, because a longer report is never the answer — every listing that truncates names the query
|
|
97
|
+
that returns the rest, and the query is both cheaper and exact:
|
|
98
|
+
|
|
99
|
+
| The report cut | Ask this instead |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `…truncated at N cells` | `--json`, or `getValues()`, or `--out data.csv` |
|
|
102
|
+
| `…truncated at N of M regions` | `getRegions()` and loop them in the run |
|
|
103
|
+
| `…more regions listed but not profiled` | the sheet report, or `getStats()` on the one you want |
|
|
104
|
+
| `…truncated at N of M tokens` | `getTokens()` and search it |
|
|
105
|
+
| `…N branches not shown` | `getPrecedents()` / `getDependents()` — the whole reach, flat (the heading already counts it) |
|
|
106
|
+
|
|
107
|
+
Same for wanting *less*: `--md.features` names the sections you want, which beats capping a count
|
|
108
|
+
you would then have to reason about. A workbook report without the region firehose is a narrower
|
|
109
|
+
question too — `wb.getWorksheets()`, `wb.getNames()`, `wb.getStats()` each answer one part of it
|
|
110
|
+
outright.
|
|
111
|
+
|
|
112
|
+
On MCP the same options are the `run` tool's `md` argument (`{ features: "fill,borders" }`).
|
|
113
|
+
|
|
114
|
+
`-- --region EU report.csv` reaches the run as `args.region === 'EU'` (named flags are also under
|
|
115
|
+
`args.kv`) and `args._ === ['report.csv']`, with the untouched tail in `args.raw`. Reading
|
|
116
|
+
`args.region` is the form that ports unchanged to MCP, where `args` is the caller's object.
|
|
117
|
+
|
|
118
|
+
The root `SKILL.md` shows the basic forms; these are the ones it doesn't:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
sheetxl book.xlsx --out book.sxl # convert format (no code)
|
|
122
|
+
sheetxl -f normalize.ts -f validate.ts raw.xlsx --out out.xlsx # pipeline
|
|
123
|
+
sheetxl -e "wb.getWorksheet().getRange('A1:C9').getValues()" \
|
|
124
|
+
data.csv --in.csv.delimiter=";" # format options
|
|
125
|
+
sheetxl book.xlsx --save <<'EOF' # stdin: multi-line code
|
|
126
|
+
const sheet = wb.getWorksheet();
|
|
127
|
+
sheet.getRange('B2').setValue('42%');
|
|
128
|
+
sheet.getRange('B3').setValue('=SUM(B1:B2)');
|
|
129
|
+
EOF
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Formats (inferred from extension): `.xlsx`, `.sxl` (native — smaller, faster),
|
|
133
|
+
`.csv` (configurable delimiter), `.json`.
|
|
134
|
+
|
|
135
|
+
## compile — typecheck without running
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
sheetxl compile <files…> [--out <path>] [--json] [--quiet]
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Compiles and typechecks without executing anything. Diagnostics are positioned,
|
|
142
|
+
so they point at the source line; the exit code is non-zero when there are
|
|
143
|
+
errors, which makes it a usable CI gate.
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
sheetxl compile audit.ts # typecheck one script
|
|
147
|
+
sheetxl compile src/*.ts # or a set
|
|
148
|
+
sheetxl compile audit.ts --out dist/audit.sxlm # also emit the compiled module
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Reach for `compile` when there is no workbook in play — a CI gate, or a check on
|
|
152
|
+
a script a human will run later. **You do not need it before executing code**: a
|
|
153
|
+
run that fails to compile returns the same positioned diagnostics, so the run
|
|
154
|
+
*is* the typecheck. Likewise `-f` is not a way to run code you just wrote — that
|
|
155
|
+
goes through `-e` or stdin; what a file is for is `scripting.md`.
|
|
156
|
+
|
|
157
|
+
## Large workbooks — the CLI is stateless, so parsing repeats
|
|
158
|
+
|
|
159
|
+
Every invocation parses the workbook from scratch. A 50 MB workbook that opens in a
|
|
160
|
+
few seconds costs those seconds *again* on the next call, so a ten-call
|
|
161
|
+
explore-then-edit loop pays them ten times. Three fixes:
|
|
162
|
+
|
|
163
|
+
**Move the iteration inside one run.** A loop that would be N invocations is one
|
|
164
|
+
script and one parse. This is where `log` earns its keep — report per item as you
|
|
165
|
+
go, return the summary:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
sheetxl -f audit.ts big.xlsx # log() per finding, return the tally
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
**Convert once, then work on `.sxl`.** The native format is 50–500x smaller and
|
|
172
|
+
significantly faster to load, lossless both ways — so pay the xlsx parse a single
|
|
173
|
+
time and export at the end:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
sheetxl big.xlsx --out scratch.sxl # pay xlsx once
|
|
177
|
+
sheetxl -e "wb.getWorksheet('Assumptions').getRegions()" scratch.sxl # …fast from here
|
|
178
|
+
sheetxl -f fix.ts scratch.sxl --out out.xlsx # deliver xlsx
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
**Or use an MCP session**, where the engine stays warm across calls and forking,
|
|
182
|
+
undo and restore are in-memory operations rather than file rewrites
|
|
183
|
+
(`sessions.md`). For a large workbook and a long edit–verify loop, this is the
|
|
184
|
+
right answer.
|
|
185
|
+
|
|
186
|
+
## Structured questions are one-liners
|
|
187
|
+
|
|
188
|
+
There is no query command, because every result renders: name the subject and its
|
|
189
|
+
report comes back. Which subject answers which question is `reading.md`; the
|
|
190
|
+
order to take them in is the root `SKILL.md`. On a terminal that looks like:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
sheetxl -e "wb" book.xlsx # the workbook report
|
|
194
|
+
sheetxl -e "wb.getWorksheet('Sheet1').getRegions('formula')" book.xlsx # the formula blocks
|
|
195
|
+
sheetxl -e "wb.getWorksheet('Sheet1').getRegions('anomalies')" book.xlsx # what breaks a pattern, ranked
|
|
196
|
+
sheetxl -e "wb.getAnomalies({ focus: 'unitMismatch', limit: 25 })" book.xlsx # ordered for one kind of defect, every sheet
|
|
197
|
+
sheetxl -e "wb.getRange('B2:B847').getStats()" book.xlsx # aggregates + typed counts
|
|
198
|
+
sheetxl -e "wb.getCell('WACC!H2')" book.xlsx # one cell, every facet
|
|
199
|
+
sheetxl -e "wb.createFormula('=NPV(0.08,B2:B9)')" # a formula, unwritten
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
A script's own plain objects render too — `sheets.map(s => ({ name: …, rows: … }))`
|
|
203
|
+
comes back as a table — so a probe needs no formatting code. `--json` emits the
|
|
204
|
+
same result as structured JSON, for piping to `jq` and friends.
|
|
205
|
+
|
|
206
|
+
## grep
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
sheetxl grep <pattern> [file]
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
The pattern is a **regex by default** (JS syntax); `-F` makes it literal.
|
|
213
|
+
Excel-style `?`/`*` wildcards are not supported. Matches are per-cell, in
|
|
214
|
+
reading order, each tagged with the layer it matched; truncation is always
|
|
215
|
+
reported.
|
|
216
|
+
|
|
217
|
+
Text that is in no cell is searched too, by default: comments ride their cell;
|
|
218
|
+
a sheet's shapes and charts follow its cells, addressed by the range they are
|
|
219
|
+
anchored over; defined names follow every sheet, addressed by the name.
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
grep "Fund Size" · workbook · fields display,formula,comment,shape,chart,name · 1 cell · 2 objects in 1 of 3 sheets
|
|
223
|
+
Summary!B4 display Fund Size
|
|
224
|
+
Summary!F2:H6 shape Fund Size is committed capital, not NAV.
|
|
225
|
+
Summary!J4:P20 chart Fund Size by Vintage
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
--fields <list> layers to search: display (as shown, format applied),
|
|
230
|
+
value (the stored scalar, what getValue() returns — 0.4
|
|
231
|
+
behind 40%, dates as serials; suppressed per cell when
|
|
232
|
+
identical to display),
|
|
233
|
+
formula (leading = restored), hyperlink (the target),
|
|
234
|
+
numberFormat (the format code, e.g. "0.00%"),
|
|
235
|
+
comment (comments, notes, replies), shape (text on a shape,
|
|
236
|
+
alt text), chart (title, axis titles, series names written
|
|
237
|
+
into the chart, alt text), name (defined names and tables:
|
|
238
|
+
the name, what it refers to, its comment)
|
|
239
|
+
[default: display,formula,comment,shape,chart,name]
|
|
240
|
+
-F, --fixed-strings literal string, not a regex
|
|
241
|
+
-i, --ignore-case case-insensitive (case-sensitive by default, like rg)
|
|
242
|
+
-w, --word match on word boundaries (text edges count as edges)
|
|
243
|
+
-v, --invert cells and objects where no requested field matched
|
|
244
|
+
--scope <scope> a sheet name (globs allowed: "Q*"), Sheet1!A1:D9, or a bare
|
|
245
|
+
range (applied to every sheet) [default: every used range].
|
|
246
|
+
A range narrows shapes and charts to those anchored over it;
|
|
247
|
+
a name is reached by the sheet it is scoped to or the cells
|
|
248
|
+
it designates
|
|
249
|
+
--hidden search hidden rows/columns/sheets, shapes and names (excluded
|
|
250
|
+
by default; naming a hidden sheet in --scope always searches it)
|
|
251
|
+
-C, --context [mode] annotate + group matches by their enclosing block:
|
|
252
|
+
contentful (bare -C) | table — not a ±N line count
|
|
253
|
+
-m, --max-count <n> stop after n matches, cells and objects together
|
|
254
|
+
[default: 200; 0 = unlimited]
|
|
255
|
+
--output <mode> content | addresses | count (per sheet) | sheets
|
|
256
|
+
[default: content]
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Error tokens are display text, so they grep directly: `sheetxl grep "#REF!" book.xlsx`.
|
|
260
|
+
"Which cells are percentages" is a format question, not a text question:
|
|
261
|
+
`sheetxl grep "%" --fields numberFormat book.xlsx`.
|
|
262
|
+
|
|
263
|
+
## Interactive sessions
|
|
264
|
+
|
|
265
|
+
No code means an interactive session — there is no `repl` verb either. `sheetxl`
|
|
266
|
+
opens one on a blank workbook; `sheetxl <file.xlsx>` preloads the file into `wb`.
|
|
267
|
+
Use `-i` to run code first and stay (`sheetxl -i -f fixtures.ts book.xlsx`).
|
|
268
|
+
|
|
269
|
+
Useful dot commands: `.help`, `.api` (the API help screen), `.md [expr]`
|
|
270
|
+
(render a result as markdown), `.info`, `.skills`, `.write <file>` (persist —
|
|
271
|
+
workbook mode only), `.exit`.
|
|
272
|
+
|
|
273
|
+
Every read command is also a dot command, generated from the same descriptors —
|
|
274
|
+
`.grep <pattern> [--flag …]`, with the session's workbook implied. Each is a
|
|
275
|
+
context **function** too (`grep('shipped', { ignoreCase: true })`), which returns
|
|
276
|
+
the data rather than the rendered text, so it composes with everything else at
|
|
277
|
+
the prompt: `(await grep('TODO')).cellCount`.
|
|
278
|
+
|
|
279
|
+
Two session-only globals: `read('<file-or-url>')` loads a workbook (paths resolve
|
|
280
|
+
against the shell directory) and `write(wb [, target])` persists one — bare
|
|
281
|
+
promises are auto-awaited, so neither needs `await`. They exist only in the
|
|
282
|
+
interactive session; a one-shot run receives `wb` and persists via `--save`.
|
|
283
|
+
|
|
284
|
+
## Composition
|
|
285
|
+
|
|
286
|
+
Everything is a normal process: exit codes, stdout, stdin. Chain with shell
|
|
287
|
+
pipes, run in CI, script with `npx -y sheetxl …` for zero-install environments.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: embedding
|
|
3
|
+
description: "Building an application with SheetXL — embedding the engine or UI, using @sheetxl/sdk as a library: packages, imports, entry setup, file IO in code, constructing workbooks. Use when writing the user's application code, or a standalone program outside `run`. Triggers on: embed, application, build an app, @sheetxl/sdk, @sheetxl/io, import, WorkbookIO, IOPlugin, new Workbook, library, Studio."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Embedding SheetXL — Building an App on the SDK
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
|
|
9
|
+
|
|
10
|
+
This is ordinary software development in the user's repo — no agent modes, no
|
|
11
|
+
sessions, no run context. Import normally and follow the app's conventions.
|
|
12
|
+
|
|
13
|
+
It is also the path for a **standalone program** when the run context cannot
|
|
14
|
+
express a task (e.g. operating on two workbooks at once) — same imports, same
|
|
15
|
+
setup, just your own small program instead of `run`.
|
|
16
|
+
|
|
17
|
+
## Packages
|
|
18
|
+
|
|
19
|
+
| Package | Purpose |
|
|
20
|
+
|---|---|
|
|
21
|
+
| `@sheetxl/sdk` | Core engine: workbook, sheets, ranges, cells, formulas |
|
|
22
|
+
| `@sheetxl/io` | Format plugins — register once at app entry |
|
|
23
|
+
| `@sheetxl/primitives` | The complete (and only) import surface for formula/UDF authoring |
|
|
24
|
+
| `sheetxl` | The CLI: run, grep, info, setup, MCP |
|
|
25
|
+
|
|
26
|
+
## Entry setup
|
|
27
|
+
|
|
28
|
+
```typescript
|
|
29
|
+
import { WorkbookIO } from '@sheetxl/sdk';
|
|
30
|
+
import { IOPlugin } from '@sheetxl/io';
|
|
31
|
+
|
|
32
|
+
WorkbookIO.install(IOPlugin); // once, before any file read/write
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Files in code
|
|
36
|
+
|
|
37
|
+
`IOPlugin` registers the default supported formats (the table below). Format is
|
|
38
|
+
inferred from the file extension; options go in the third argument:
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
const wb = await WorkbookIO.read('data.xlsx');
|
|
42
|
+
const csv = await WorkbookIO.read({ source: 'data.csv' }, { delimiter: ';' });
|
|
43
|
+
|
|
44
|
+
await WorkbookIO.writeFile('output.sxl', wb); // recalcs pending formulas first
|
|
45
|
+
await WorkbookIO.writeFile('out.csv', wb, { delimiter: '\t' });
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
| Extension | Format | Notes |
|
|
49
|
+
|---|---|---|
|
|
50
|
+
| `.xlsx` | Excel Open XML | Full read/write, Excel compatible |
|
|
51
|
+
| `.sxl` | SXL (native) | 50–500x smaller, significantly faster, lossless round-trip |
|
|
52
|
+
| `.csv` | CSV | Configurable delimiter |
|
|
53
|
+
| `.json` | JSON | SheetXL array format |
|
|
54
|
+
|
|
55
|
+
The format trade-off (`.sxl` for working copies, `.xlsx` when Excel opens the
|
|
56
|
+
file) is the root `SKILL.md`; it reads the same from application code.
|
|
57
|
+
|
|
58
|
+
The shipped type definitions are the authoritative API surface —
|
|
59
|
+
`node_modules/@sheetxl/sdk/types/index.d.ts`.
|
|
60
|
+
|
|
61
|
+
## Constructing a workbook
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
import { Workbook } from '@sheetxl/sdk';
|
|
65
|
+
|
|
66
|
+
const wb = new Workbook();
|
|
67
|
+
const sheet = wb.getWorksheet();
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Embedding the UI
|
|
71
|
+
|
|
72
|
+
Studio — the production React UI with full Excel shortcuts and visual
|
|
73
|
+
fidelity — embeds alongside the engine. See https://www.sheetxl.com/docs for
|
|
74
|
+
components and integration guides.
|