mapshaper 0.7.2 → 0.7.3

package/www/docs/guides/expressions.html.md

@@ -1,376 +0,0 @@
----
-title: JavaScript expressions
-description: Reference for the JS expressions used in -each, -filter, -calc, -where, -sort, -if, -run and other Mapshaper commands.
----
-
-# JavaScript expressions
-
-Many Mapshaper commands take a **JS expression** as an argument or option. Expressions let you read and write per-feature attributes, derive new fields, filter records, sort, generate templated commands, and inspect layer-level metadata. The same expression syntax and execution context are reused across commands, so once you've learned the shape of a `-each` expression you can use it almost everywhere.
-
-```bash
-mapshaper counties.shp \
-  -each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2),
-         AREA_KM2 = this.area / 1e6' \
-  -o out.shp
-```
-
-Expressions are plain JavaScript. They can use any built-in language feature (arithmetic, string methods, conditionals, regex, etc.). Some commands also expect the expression to return a particular kind of value — `-filter` and `-inspect` expect `true` or `false`, `-sort` expects a sort key, `-split` expects a group identifier, and so on.
-
-## Where expressions appear
-
-| Command | Expression role | Type |
-| --- | --- | --- |
-| [`-each`](/docs/reference.html.md#-each) | Run side-effects per feature, including assignments to data fields | feature |
-| [`-filter`](/docs/reference.html.md#-filter) | Boolean test, kept if `true` | feature, returns boolean |
-| [`-sort`](/docs/reference.html.md#-sort) | Returns the sort key for each feature | feature |
-| [`-inspect`](/docs/reference.html.md#-inspect) | Boolean test, prints matching feature(s) | feature, returns boolean |
-| [`-split`](/docs/reference.html.md#-split) | Returns the value used to group features into output layers | feature |
-| [`-subdivide`](/docs/reference.html.md#-subdivide) | Boolean test driving recursive partitioning, can call group functions like `sum()` | feature, returns boolean |
-| [`-calc` and `calc=` options](/docs/reference.html.md#-calc) | Aggregations across a group of features (`sum`, `count`, `median`, etc.) | calc |
-| `where=` (on `-filter`, `-each`, `-affine`, `-dashlines`, `-dissolve`, `-innerlines`, `-join`, `-style`, `-symbols`, `-calc`) | Sub-filter applied before the main operation | feature, returns boolean |
-| `weight=` on `-dissolve`/`-points` | Weighting expression for centroid calculation | feature |
-| Attribute options on [`-style`](/docs/reference.html.md#-style) and [`-symbols`](/docs/reference.html.md#-symbols) | Most values (`fill=`, `stroke=`, `stroke-width=`, `opacity=`, `r=`, `label-text=`, `dx=`, `dy=`, `font-size=`, etc.) accept either a literal or a JS expression evaluated per feature | feature |
-| [`-lines where=` and `each=`](/docs/reference.html.md#-lines) | Operates on **pairs** of features either side of a path, exposed as `A` and `B` | pair |
-| [`-if` / `-elif`](/docs/reference.html.md#-if) | Boolean test on layer-level metadata | layer |
-| [`-define`](/docs/reference.html.md#-define) | Stores variables and helper functions in a global namespace shared by later expressions | layer |
-| [`-run`](/docs/reference.html.md#-run) | Generates command strings, with embedded `{...}` template substitutions | template |
-
-<!-- | `bbox=` on `-rectangles` | Returns a `[xmin, ymin, xmax, ymax]` per feature | feature | -->
-These five flavors &mdash; **feature**, **calc**, **pair**, **layer** and **template** &mdash; share most of their context but differ in which variables are available and which functions are in scope.
-
-## The execution context
-
-Inside any feature-level expression you have access to:
-
-- **Field names as bare variables.** Reading a field name returns its value. Assigning to a field name updates the current feature's record (and creates the field on first use). If a field name is not a valid JavaScript identifier (e.g. it contains spaces or starts with a digit), use `d["field name"]` to reference it.
-- **`this`**, the feature proxy. Provides geometry-derived properties (`this.area`, `this.bbox`, etc.) and read/write access to the feature's `properties`, `geojson` and `coordinates`.
-- **`d`**, a reference to the data record (the same object as `this.properties`).
-- **`global`**, an object that persists across commands. Variables created by `-define`, by assignment in a `-calc` expression, or by writing to `global.foo = ...` inside `-each` end up here. Values set by [`-vars`](/docs/reference.html.md#-vars) and [`-defaults`](/docs/reference.html.md#-defaults) live in a separate *templating* scope (read by `{{X}}` substitution) and are **not** visible by bare name in expressions; use `-define` if you want a value reachable from both `{{X}}` and JS expressions.
-- **`console.log()`** for printing values to stderr while debugging.
-- **Built-in helpers** (see [Helper functions](#helper-functions) below).
-- **User helpers** loaded by [`-define`](/docs/reference.html.md#-define), [`-include`](/docs/reference.html.md#-include) or [`-require`](/docs/reference.html.md#-require).
-
-If a name is referenced but not present in any of the above, JavaScript treats it as `undefined`, *not* an error. This is convenient when chaining expressions across heterogeneous datasets but can mask typos &mdash; double-check field names with `mapshaper -info` if a `-filter` returns a suspiciously empty result.
-
-### Field assignment
-
-Assigning to a bare name creates or updates a data field on the current feature:
-
-```bash
-mapshaper counties.shp -each 'POP_DENSITY = POPULATION / (this.area / 1e6)' -o
-```
-
-Bare assignments like `POP_DENSITY = ...` will create the data table if the layer doesn't already have one. Assignments routed through `this.properties.X = ...` or `d.X = ...` only update an existing data table &mdash; prefer a bare assignment if you're not sure the layer has one yet.
-
-To delete a field, use the JS `delete` operator:
-
-```bash
-mapshaper states.shp -each 'delete STATE_NAME, delete GEOID' -o
-```
-
-To replace the entire record, assign to `this.properties`:
-
-```bash
-mapshaper states.shp -each 'this.properties = {FID: this.id, NAME: NAME}' -o
-```
-
-### Multiple statements
-
-Use commas to evaluate multiple sub-expressions. The value of the whole expression is the value of the last sub-expression (relevant for `-filter`, `-sort`, `-split`):
-
-```bash
-mapshaper data.csv -each 'A = parseInt(A), B = A * 2, C = A + B'
-```
-
-Inside command files, you can also break a long expression across lines with `\`:
-
-```
--each '
-  STATE_FIPS = COUNTY_FIPS.substr(0, 2),  \
-  AREA_KM2   = this.area / 1e6,           \
-  CENTROID_X = this.centroidX,            \
-  CENTROID_Y = this.centroidY
-'
-```
-
-## Feature properties (`this`)
-
-`this` is a proxy for the current feature. It gives you geometry-derived properties and a few editing affordances. The properties below are read-only unless the description says otherwise.
-
-### All layer types
-
-| Name | Description |
-| --- | --- |
-| `this.id` | 0-based numerical id of the feature |
-| `this.layer_name` | Name of the layer (or empty string) |
-| `this.properties` | Data record. Read/write &mdash; assign a new object to replace all attributes. |
-| `this.layer` | Layer proxy &mdash; see [Layer-level properties](#layer-level-properties-thislayer) |
-| `this.geojson` | GeoJSON Feature (geometry + properties). Read/write &mdash; assign a new Feature to replace this one. |
-| `this.geometry` | Just the GeoJSON geometry. Read/write. |
-
-### Polygon, polyline and point layers (with geometry)
-
-| Name | Description |
-| --- | --- |
-| `this.partCount` | 1 for single-part features, >1 for multi-part, 0 for null |
-| `this.isNull` | `true` if `partCount === 0` |
-| `this.bbox` | `[xmin, ymin, xmax, ymax]` |
-| `this.width`, `this.height` | Bounding-box width and height |
-| `this.bboxContainsPoint(x, y)` | `true` if the bbox covers the point |
-| `this.bboxIntersectsRectangle(a, b, c, d)` | `true` if the bbox overlaps the rectangle |
-| `this.bboxContainsRectangle(a, b, c, d)` | `true` if the bbox fully contains the rectangle |
-| `this.bboxContainedByRectangle(a, b, c, d)` | `true` if the bbox is fully inside the rectangle |
-
-### Polygon-only
-
-| Name | Description |
-| --- | --- |
-| `this.area` | Area in source units (square meters for unprojected lat/long, computed on a sphere) |
-| `this.planarArea` | Treats lat/long as planar &mdash; useful inside expressions that already account for projection |
-| `this.originalArea` | Area before any `-simplify` was applied |
-| `this.perimeter` | Perimeter length (meters for unprojected lat/long) |
-| `this.compactness` | Polsby-Popper compactness ratio (0&ndash;1) |
-| `this.innerPct` | Fraction of the perimeter that is shared with neighboring polygons |
-| `this.centroidX`, `this.centroidY` | Centroid coordinates (computed from the largest ring; ignores holes) |
-| `this.innerX`, `this.innerY` | An interior point useful for placing a label or symbol |
-
-### Polyline-only
-
-| Name | Description |
-| --- | --- |
-| `this.length` | Total length (meters for unprojected lat/long) |
-
-### Point-only
-
-| Name | Description |
-| --- | --- |
-| `this.coordinates` | The full nested coordinate array, or `null`. Read/write &mdash; assign `null` to drop the geometry. |
-| `this.x`, `this.y` | Coordinates of the first point of the (possibly multi-) feature. Read/write. |
-
-> **Why it matters for unprojected data:** `this.area` and `this.length` use *spherical* (not planar or ellipsoidal) geometry on lat/long datasets. Results are in square meters / meters and accurate to within ~0.5% for most use cases. If you need ellipsoidal accuracy, project first with `-proj`.
-
-## Layer-level properties (`this.layer`)
-
-`this.layer` exposes information about the layer the feature belongs to. Useful in expressions that need to know about other features:
-
-| Name | Description |
-| --- | --- |
-| `this.layer.name` | Layer name |
-| `this.layer.type` | `'polygon'`, `'polyline'`, `'point'` or `null` |
-| `this.layer.size` | Feature count |
-| `this.layer.empty` | `true` if `size === 0` |
-| `this.layer.bbox` | `[xmin, ymin, xmax, ymax]`, with extra `cx`, `cy`, `width`, `height`, `left`, `right`, `top`, `bottom` properties |
-| `this.layer.data` | The full array of data records (use sparingly inside per-feature loops) |
-| `this.layer.field_exists(name)` | Returns `true` if a field exists |
-| `this.layer.field_type(name)` | Returns `'string'`, `'number'`, `'object'` etc., or `null` |
-| `this.layer.field_includes(name, value)` | Returns `true` if any record's `name` field equals `value` |
-
-## Helper functions
-
-These are always in scope inside feature expressions:
-
-- `round(num [, decimals])` &mdash; Round to N decimal places (default 0). Faster and easier than `Math.round`.
-- `sprintf(fmt, ...)` &mdash; printf-style formatter (uses [printj](https://github.com/SheetJS/printj) syntax).
-- `format_dms(coord [, fmt])` &mdash; Format a number as a degrees/minutes/seconds string. Common formats: `'DD° MM′ SS.SSSSS″ [NS]'`, `'DdMmSs [EW]'`, `'[+-]DDDMM.MMMMM'`, `'[-]DD.DDDDD°'`.
-- `parse_dms(string [, fmt])` &mdash; Parse a DMS string back to a number.
-- `blend(c1, c2, ...)` &mdash; Mix CSS color strings together (returns a hex string).
-- `console.log(...)` &mdash; Write to stderr.
-
-JavaScript's built-in `Math`, `JSON`, `Number`, `String`, `Array`, `Date`, `Object` etc. are all available. Node-specific globals like `process`, `require` and `setTimeout` are not.
-
-## Calc expressions
-
-`-calc` and any command's `calc=` option use the same context as `-each` plus a set of *aggregate* functions that operate over the entire group of features (or the entire layer for `-calc`). Each aggregate function takes a per-feature expression and reduces it to a single value across the group.
-
-| Function | Description |
-| --- | --- |
-| `count()` | Number of records in the collection |
-| `sum(<expr>)` | Sum of the per-feature expression |
-| `mean(<expr>)`, `average(<expr>)` | Arithmetic mean |
-| `median(<expr>)` | Median value |
-| `mode(<expr>)` | Most common value (first one wins ties) |
-| `min(<expr>)`, `max(<expr>)` | Extremes |
-| `quartile1(<expr>)`, `quartile2(<expr>)`, `quartile3(<expr>)` | Quartiles |
-| `iqr(<expr>)` | Interquartile range |
-| `quantile(<expr>, <pct>)` | Arbitrary percentile (0&ndash;1) |
-| `collect(<expr>)` | Array of all values (preserves order) |
-| `collectIds()` | Array of feature ids |
-| `first(<expr>)`, `last(<expr>)` | First / last value seen |
-| `every(<expr>)`, `some(<expr>)` | Boolean reductions |
-
-Argument expressions use the same syntax as `-each`, so per-feature properties and helpers are available:
-
-```bash
-mapshaper counties.shp \
-  -calc 'TOTAL_POP = sum(POP),
-         MEAN_AREA_KM2 = sum(this.area / 1e6) / count(),
-         TOP_DENSITY = max(POP / this.area)'
-```
-
-Calc expressions can also use assignments to expose values to subsequent commands via the `global` namespace (see [Sharing state across commands](#sharing-state-across-commands) below).
-
-## Pair expressions (`A` and `B`)
-
-The `-lines where=` and `each=` options operate on path segments shared between two adjacent features. Inside these expressions:
-
-- `A` is the feature on one side of the path
-- `B` is the feature on the other side, or `null` for outer boundaries
-
-Both `A` and `B` give you the full set of feature properties (`A.properties`, `A.area`, `A.id`, etc.).
-
-```bash
-# Keep only inner boundaries between two different states
-mapshaper counties.shp \
-  -lines where='B && A.STATE != B.STATE' \
-  -o state-borders.shp
-```
-
-## Layer-level expressions (`-if`, `-define`)
-
-The `-if` family and `-define` evaluate against the *current command's target layer(s)*, not per feature. The context exposes:
-
-- `target` &mdash; the proxy for the single target layer (only set when there's exactly one target)
-- `targets` &mdash; an array-like of layer proxies, also indexable by name (`targets.states`)
-- `layer_name`, `data`, `type`, `size`, `empty`, `bbox`
-- `field_exists(name)`, `field_type(name)`, `field_includes(name, value)`
-- `layer_exists(name [, geometry_type])`
-- `file_exists(path)`
-- `global` &mdash; the shared variable namespace
-
-```bash
-mapshaper data.csv \
-  -calc 'N = count()' \
-  -if 'global.N < 5' -print 'LOW SAMPLE SIZE, STOPPING' -stop -endif
-```
-
-Each entry in `targets` exposes useful summary stats from `-info`: `layer_name`, `feature_count`, `null_shape_count`, `null_data_count`, `bbox`, `proj4`. Reading `targets[0].geojson` returns the layer as a GeoJSON FeatureCollection; assigning to it replaces the layer with the FeatureCollection you provide.
-
-## Template expressions (`-run`)
-
-`-run` accepts either a path to a [command file](/docs/reference.html.md#command-files) or a string containing one or more curly-brace template expressions. Each `{...}` is evaluated as a JS expression and substituted into the resulting command string before Mapshaper parses it.
-
-```bash
-# Project to a transverse Mercator centred on the layer
-mapshaper -i country.shp -require projection.js \
-  -run '-proj {tmerc(target.bbox)}' -o
-```
-
-Inside the curly braces you have:
-
-- `target` and `targets` (same as `-if`)
-- `io.ifile(filename, data)` &mdash; spill data to a temp file and yield its path, useful for piping computed JSON back into `-i`
-- Anything loaded by `-require` or `-define`
-
-Bare function calls outside curly braces are also evaluated directly, so `-run 'tmerc(target.bbox)'` works the same as `-run '{tmerc(target.bbox)}'` when the function name was loaded via `-require`.
-
-## Loading helpers
-
-Three commands extend the expression context with your own variables and helpers:
-
-- [`-define`](/docs/reference.html.md#-define) takes an inline JS expression and stores any assignments on the global namespace. Good for one-liners.
-- [`-include`](/docs/reference.html.md#-include) loads a `.js` file containing a single object literal; each property of that object becomes a variable in subsequent expressions.
-- [`-require`](/docs/reference.html.md#-require) loads an installed npm module or a local module file. With `alias=foo` the module is bound to that name; without an alias, the module's exported names are added directly to the context.
-
-```bash
-mapshaper data.json \
-  -require ./helpers.mjs \
-  -each 'displayname = formatName(d)' \
-  -o data.json
-```
-
-```bash
-mapshaper -define 'KM_PER_MILE = 1.609344' \
-  routes.geojson \
-  -each 'KM = MILES * global.KM_PER_MILE' \
-  -o
-```
-
-## Sharing state across commands
-
-Mapshaper has two scopes for values that persist between commands. They share a name lookup for `{{X}}` substitution but are otherwise independent.
-
-- **Expression scope (`global`)** &mdash; written by `-define`, `-include`, `-require`, `-colorizer`, and `-calc` assignments (e.g. `N = count()`) or any `global.foo = ...` inside `-each`. Values can be any JavaScript value (numbers, strings, functions, objects). Read by JS expressions as bare names, and as `global.X` everywhere. `{{X}}` substitution falls back to this scope, so `-define base = "out"` &rarr; `-o {{base}}.geojson` and `-calc 'N = count()'` &rarr; `-if '{{N}} > 100'` work as you'd expect.
-- **Templating scope** &mdash; written by [`-vars`](/docs/reference.html.md#-vars) and [`-defaults`](/docs/reference.html.md#-defaults). Values must be primitives (string / number / boolean / null) and are validated at write time. Read by `{{X}}` substitution; `{{X}}` checks the templating scope first, then falls back to the expression scope. **Not** visible by bare name in JS expressions &mdash; that's deliberate, so a string set by `-vars N=5` can't silently coerce into arithmetic.
-
-If you want one value usable in both contexts, set it once with `-define`. If you only need it in command strings, use `-vars` (or `-defaults` for command-file overridable defaults).
-
-```bash
-mapshaper counties.shp \
-  -calc 'BIG = count("POP > 1000000")' \
-  -if 'global.BIG > 0' \
-    -filter 'POP > 1000000' \
-    -o big-counties.shp \
-  -endif
-```
-
-## Common pitfalls
-
-- **Quoting.** In bash/zsh, wrap expressions in single quotes so the shell doesn't expand `!`, `$` or backticks. In Windows `cmd.exe`, use double quotes and escape inner quotes with backslashes. In PowerShell, prefer single quotes, or escape `$` with a backtick.
-- **Type coercion from CSVs.** Numeric-looking strings in CSVs are parsed as numbers by default; identifier-like strings (FIPS, ZIP) need `string-fields=` on `-i` to preserve leading zeros. See [CSV practical notes](/docs/formats/csv.html.md#practical-notes).
-- **Field name collisions.** A field called `area`, `length`, `id` etc. shadows the built-in property of the same name. Mapshaper prints a warning. Either rename the field with `-rename-fields`, or read the property via `this.area` rather than the bare name.
-- **Lat/long area surprises.** `this.area` on an unprojected polygon returns *square meters on a sphere*, not square degrees. To get square kilometres, divide by `1e6`. To get planar square degrees (e.g. for sanity checks), use `this.planarArea`.
-- **Centroids ignore holes.** `this.centroidX/Y` is the centroid of the largest ring. For a labelling point that's guaranteed inside the polygon, use `innerX`/`innerY`.
-- **`-each` doesn't return values.** Its expression is evaluated for side-effects only. Use `-filter`, `-sort` or `-calc` if you want the return value to drive behavior.
-- **Reserved names.** `this`, `d`, `_`, `global`, `console`, `target`, `targets` and the helper function names listed above are not safe to use as field names.
-- **Auto-vivification of fields.** Assigning to a name that isn't a known field creates a new field on every record. If you only want to set a field on *some* records, wrap it in a conditional and assign explicit `null` for the others, otherwise downstream readers may see `undefined` instead of a real null.
-
-## Examples
-
-```bash
-# Add two derived fields
-mapshaper counties.shp \
-  -each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2),
-         AREA_KM2 = round(this.area / 1e6, 2)' \
-  -o out.shp
-
-# Drop features outside a date window
-mapshaper events.csv \
-  -filter 'new Date(DATE) >= new Date("2020-01-01")' \
-  -o recent.csv
-
-# Sort polygons largest-first
-mapshaper countries.geojson \
-  -sort '-this.area' \
-  -o sorted.geojson
-
-# Look up one feature
-mapshaper states.geojson -inspect 'NAME == "Delaware"'
-
-# Aggregate stats during a dissolve
-mapshaper counties.shp \
-  -dissolve STATE calc='N = count(),
-                        POP = sum(POP),
-                        MEDIAN_INC = median(MEDIAN_INC)' \
-  -o states.shp
-
-# Conditional pipeline based on a calc result
-mapshaper data.csv \
-  -calc 'N = count()' \
-  -if 'global.N == 0' -stop -endif \
-  -o data.csv
-
-# Filter shared boundaries
-mapshaper counties.shp \
-  -lines where='B && A.STATE != B.STATE' \
-  -o state-borders.shp
-
-# Per-feature styling: circle radius from POP, fill from an expression
-mapshaper cities.geojson \
-  -style r='Math.sqrt(POP) / 40' \
-         fill='POP > 1e6 ? "#c33" : "#39c"' \
-         opacity=0.7 \
-  -o cities.svg
-
-# Project to a layer-specific CRS
-mapshaper -i country.shp -require ./projection.js \
-  -run '-proj {tmerc(target.bbox)}' -o
-```
-
-## See also
-
-- [`-each`](/docs/reference.html.md#-each) &mdash; the canonical feature-expression command
-- [`-filter`](/docs/reference.html.md#-filter)
-- [`-calc`](/docs/reference.html.md#-calc)
-- [`-define`](/docs/reference.html.md#-define), [`-include`](/docs/reference.html.md#-include), [`-require`](/docs/reference.html.md#-require)
-- [`-run`](/docs/reference.html.md#-run)
-- [Basics](/docs/examples/basics.html.md) &mdash; recipes that put expressions to work

package/www/docs/guides/programmatic.html

@@ -1,117 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Using Mapshaper from Node.js &middot; mapshaper docs</title>
-<meta name="description" content="Integrating Mapshaper into JavaScript builds and applications via its Node.js API.">
-<link rel="icon" type="image/png" href="/images/icon.png">
-<link rel="stylesheet" href="/docs/_assets/highlight.css">
-<link rel="stylesheet" href="/docs/_assets/docs.css">
-</head>
-<body class="">
-
-<header class="page-header">
-  <a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
-  <span class="header-section-label">Docs</span>
-  <nav class="header-nav">
-    <a href="/">Web app</a>
-    <a href="https://github.com/mbloch/mapshaper">GitHub</a>
-    <a href="/sponsor.html" class="sponsor-link"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg> Become a sponsor</a>
-  </nav>
-</header>
-
-<div class="docs-layout">
-
-  <aside class="docs-sidebar">
-    <div class="sidebar-inner">
-      <nav class="docs-nav"><ul class="top-links"><li><a href="/docs/">Home</a></li><li><a href="/docs/whats-new.html">What&#39;s new</a></li><li><a href="/docs/reference.html">Command reference</a></li><li><a href="/docs/gallery/">Gallery</a></li></ul><h2>Getting started</h2><ul><li><a href="/docs/essentials/command-line.html">The command-line tool</a></li><li><a href="/docs/essentials/web-app.html">The web app</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/guides/simplification.html">Simplification</a></li><li><a href="/docs/guides/expressions.html">JavaScript expressions</a></li><li><a href="/docs/guides/projections.html">Projections</a></li><li><a href="/docs/guides/topology.html">Topology and cleaning</a></li><li><a href="/docs/guides/combining-layers.html">Combining two layers</a></li><li><a href="/docs/guides/programmatic.html" class="is-active">Using Mapshaper from Node.js</a></li></ul><h2>Formats</h2><ul><li><a href="/docs/formats/overview.html">Overview</a></li><li><a href="/docs/formats/shapefile.html">Shapefile</a></li><li><a href="/docs/formats/geojson.html">GeoJSON</a></li><li><a href="/docs/formats/topojson.html">TopoJSON</a></li><li><a href="/docs/formats/geopackage.html">GeoPackage</a></li><li><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></li><li><a href="/docs/formats/kml.html">KML / KMZ</a></li><li><a href="/docs/formats/csv.html">CSV / TSV</a></li><li><a href="/docs/formats/dbf.html">DBF</a></li><li><a href="/docs/formats/json.html">JSON records</a></li><li><a href="/docs/formats/svg.html">SVG</a></li><li><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></li></ul><h2>Examples</h2><ul><li><a href="/docs/examples/basics.html">Basics</a></li><li><a href="/docs/examples/globe.html">Globe</a></li><li><a href="/docs/examples/us-states.html">U.S. state map</a></li></ul></nav>
-    </div>
-  </aside>
-
-  <main class="docs-main">
-    <article class="docs-article">
-      <div class="docs-breadcrumbs"><a href="/docs/">Docs</a> &rsaquo; Guides &rsaquo; Using Mapshaper from Node.js</div>
-      <h1 id="using-mapshaper-from-nodejs">Using Mapshaper from Node.js</h1>
-<p>This page is for developers who want to use Mapshaper&#39;s geoprocessing functions inside their own programs &mdash; either by shelling out to the CLI from a build tool, or by calling Mapshaper&#39;s API from Node.js code directly.</p>
-<h2 id="calling-the-cli-from-a-build-tool">Calling the CLI from a build tool</h2>
-<p>The simplest way to script Mapshaper is to invoke the <code>mapshaper</code> (or <code>mapshaper-xl</code>) command from <code>make</code> or a shell script.</p>
-<p>Example <code>Makefile</code> target:</p>
-<pre><code class="hljs language-make"><span class="hljs-section">europe.topojson: shp/world_countries.shp</span>
-	mapshaper <span class="hljs-variable">{{CONTENT}}lt;</span> \
-	  -filter <span class="hljs-string">&quot;CONTINENT == &#x27;Europe&#x27;&quot;</span> \
-	  -simplify interval=100m keep-shapes \
-	  -o <span class="hljs-variable">$@</span>
-</code></pre>
-<p>An alternative to embedding a long series of Mapshaper commands on the command line is to put them in a <code>.txt</code> file and pass the file to <code>mapshaper</code>. See <a href="/docs/reference.html#command-files">command files</a> and <a href="/docs/reference.html#variable-interpolation">variable interpolation</a> in the reference.</p>
-<h2 id="the-nodejs-api">The Node.js API</h2>
-<p>Mapshaper exposes three top-level functions for running editing commands programmatically. All three accept the same command-line string format as the <code>mapshaper</code> CLI.</p>
-<h3 id="runcommandscommands-input-callback"><code>runCommands(commands[, input][, callback])</code></h3>
-<p>Runs a command line against files on disk (or in-memory). The <code>-o</code> command(s) write their output to disk.</p>
-<ul>
-<li><code>commands</code> &mdash; a command-line string.</li>
-<li><code>input</code> (optional) &mdash; an object whose keys are filenames and whose values are file contents. Files referenced by <code>-i</code> are looked up here first, then on the filesystem.</li>
-<li><code>callback</code> (optional) &mdash; a Node-style <code>function(err)</code>. Without a callback, <code>runCommands</code> returns a Promise.</li>
-</ul>
-<pre><code class="hljs language-javascript"><span class="hljs-keyword">import</span> mapshaper <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;mapshaper&#x27;</span>;
-
-<span class="hljs-keyword">await</span> mapshaper.<span class="hljs-title function_">runCommands</span>(<span class="hljs-string">&#x27;-i shapefiles/*.shp -o geojson/ format=geojson&#x27;</span>);
-</code></pre>
-<h3 id="applycommandscommands-input-callback"><code>applyCommands(commands[, input][, callback])</code></h3>
-<p>Same signature as <code>runCommands</code>, but instead of writing files to disk, the contents produced by <code>-o</code> are returned to the caller as a <code>{ filename: Buffer }</code> object. Useful for processing data without touching the filesystem.</p>
-<pre><code class="hljs language-javascript"><span class="hljs-keyword">import</span> mapshaper <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;mapshaper&#x27;</span>;
-
-<span class="hljs-keyword">const</span> input = { <span class="hljs-string">&#x27;input.csv&#x27;</span>: <span class="hljs-string">&#x27;lat,lng,value\n40.3,-72.3,1000&#x27;</span> };
-<span class="hljs-keyword">const</span> cmd   = <span class="hljs-string">&#x27;-i input.csv -points x=lng y=lat -o output.geojson&#x27;</span>;
-
-<span class="hljs-keyword">const</span> output = <span class="hljs-keyword">await</span> mapshaper.<span class="hljs-title function_">applyCommands</span>(cmd, input);
-<span class="hljs-comment">// output[&#x27;output.geojson&#x27;] is a Buffer containing GeoJSON</span>
-</code></pre>
-<h3 id="runcommandsxlcommands-options-callback"><code>runCommandsXL(commands[, options][, callback])</code></h3>
-<p>Like <code>runCommands</code>, but the work runs in a child Node process configured with a larger maximum heap (8 GB by default). Equivalent to running <code>mapshaper-xl</code> from the command line. Override the heap size with the <code>xl</code> option:</p>
-<pre><code class="hljs language-javascript"><span class="hljs-keyword">await</span> mapshaper.<span class="hljs-title function_">runCommandsXL</span>(commands, { <span class="hljs-attr">xl</span>: <span class="hljs-string">&#x27;16gb&#x27;</span> });
-</code></pre>
-<p>This function reads input only from the filesystem &mdash; there&#39;s no <code>input</code> argument as on <code>runCommands</code>/<code>applyCommands</code>.</p>
-<h2 id="working-with-shapefiles-in-applycommands">Working with Shapefiles in <code>applyCommands</code></h2>
-<p>Shapefiles are really a set of component files. To import one through <code>applyCommands</code>, pass the contents of all the parts you care about:</p>
-<ul>
-<li><code>.shp</code> &mdash; geometry (Buffer or ArrayBuffer)</li>
-<li><code>.dbf</code> &mdash; attribute table (Buffer or ArrayBuffer)</li>
-<li><code>.prj</code> &mdash; coordinate system (string)</li>
-</ul>
-<p>Without <code>.dbf</code> you&#39;ll get geometry but no attributes; without <code>.prj</code>, projection-dependent commands won&#39;t have a coordinate system to work from.</p>
-<pre><code class="hljs language-javascript"><span class="hljs-keyword">const</span> input = {
-  <span class="hljs-string">&#x27;world.shp&#x27;</span>: shpBuffer,
-  <span class="hljs-string">&#x27;world.dbf&#x27;</span>: dbfBuffer,
-  <span class="hljs-string">&#x27;world.prj&#x27;</span>: prjString
-};
-<span class="hljs-keyword">const</span> output = <span class="hljs-keyword">await</span> mapshaper.<span class="hljs-title function_">applyCommands</span>(
-  <span class="hljs-string">&#x27;-i world.shp -simplify 10% -o world.geojson&#x27;</span>, input
-);
-</code></pre>
-<h2 id="versioning">Versioning</h2>
-<p>The Node API is stable across minor Mapshaper releases, but new options and commands appear regularly. The full set of accepted command-line options is the same as the CLI&#39;s, so the <a href="/docs/reference.html">command reference</a> is the authoritative list of what you can put into the <code>commands</code> string.</p>
-
-      <div class="edit-link">
-        <a href="https://github.com/mbloch/mapshaper/edit/master/docs/guides/programmatic.md">Edit this page on GitHub</a>
-      </div>
-    </article>
-  </main>
-
-  <aside class="docs-toc">
-    <div class="docs-toc-title">On this page</div><ul><li class="lvl-2"><a href="#calling-the-cli-from-a-build-tool">Calling the CLI from a build tool</a></li><li class="lvl-2"><a href="#the-nodejs-api">The Node.js API</a></li><li class="lvl-3"><a href="#runcommandscommands-input-callback">runCommands(commands[, input][, callback])</a></li><li class="lvl-3"><a href="#applycommandscommands-input-callback">applyCommands(commands[, input][, callback])</a></li><li class="lvl-3"><a href="#runcommandsxlcommands-options-callback">runCommandsXL(commands[, options][, callback])</a></li><li class="lvl-2"><a href="#working-with-shapefiles-in-applycommands">Working with Shapefiles in applyCommands</a></li><li class="lvl-2"><a href="#versioning">Versioning</a></li></ul>
-  </aside>
-
-</div>
-
-<script src="/docs/_assets/docs.js" defer></script>
-
-<footer class="docs-footer">
-  <div class="docs-footer-inner">
-    <span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
-    <span><a href="/privacy.html">Privacy</a> &middot; <a href="/terms.html">Terms</a> &middot; <a href="/sponsor.html">Support mapshaper</a></span>
-  </div>
-</footer>
-
-</body>
-</html>

package/www/docs/guides/programmatic.html.md

@@ -1,91 +0,0 @@
----
-title: Using Mapshaper from Node.js
-description: Integrating Mapshaper into JavaScript builds and applications via its Node.js API.
----
-
-# Using Mapshaper from Node.js
-
-This page is for developers who want to use Mapshaper's geoprocessing functions inside their own programs — either by shelling out to the CLI from a build tool, or by calling Mapshaper's API from Node.js code directly.
-
-## Calling the CLI from a build tool
-
-The simplest way to script Mapshaper is to invoke the `mapshaper` (or `mapshaper-xl`) command from `make` or a shell script.
-
-Example `Makefile` target:
-
-```make
-europe.topojson: shp/world_countries.shp
-	mapshaper $< \
-	  -filter "CONTINENT == 'Europe'" \
-	  -simplify interval=100m keep-shapes \
-	  -o $@
-```
-
-An alternative to embedding a long series of Mapshaper commands on the command line is to put them in a `.txt` file and pass the file to `mapshaper`. See [command files](/docs/reference.html.md#command-files) and [variable interpolation](/docs/reference.html.md#variable-interpolation) in the reference.
-
-## The Node.js API
-
-Mapshaper exposes three top-level functions for running editing commands programmatically. All three accept the same command-line string format as the `mapshaper` CLI.
-
-### `runCommands(commands[, input][, callback])`
-
-Runs a command line against files on disk (or in-memory). The `-o` command(s) write their output to disk.
-
-- `commands` &mdash; a command-line string.
-- `input` (optional) &mdash; an object whose keys are filenames and whose values are file contents. Files referenced by `-i` are looked up here first, then on the filesystem.
-- `callback` (optional) &mdash; a Node-style `function(err)`. Without a callback, `runCommands` returns a Promise.
-
-```javascript
-import mapshaper from 'mapshaper';
-
-await mapshaper.runCommands('-i shapefiles/*.shp -o geojson/ format=geojson');
-```
-
-### `applyCommands(commands[, input][, callback])`
-
-Same signature as `runCommands`, but instead of writing files to disk, the contents produced by `-o` are returned to the caller as a `{ filename: Buffer }` object. Useful for processing data without touching the filesystem.
-
-```javascript
-import mapshaper from 'mapshaper';
-
-const input = { 'input.csv': 'lat,lng,value\n40.3,-72.3,1000' };
-const cmd   = '-i input.csv -points x=lng y=lat -o output.geojson';
-
-const output = await mapshaper.applyCommands(cmd, input);
-// output['output.geojson'] is a Buffer containing GeoJSON
-```
-
-### `runCommandsXL(commands[, options][, callback])`
-
-Like `runCommands`, but the work runs in a child Node process configured with a larger maximum heap (8 GB by default). Equivalent to running `mapshaper-xl` from the command line. Override the heap size with the `xl` option:
-
-```javascript
-await mapshaper.runCommandsXL(commands, { xl: '16gb' });
-```
-
-This function reads input only from the filesystem &mdash; there's no `input` argument as on `runCommands`/`applyCommands`.
-
-## Working with Shapefiles in `applyCommands`
-
-Shapefiles are really a set of component files. To import one through `applyCommands`, pass the contents of all the parts you care about:
-
-- `.shp` &mdash; geometry (Buffer or ArrayBuffer)
-- `.dbf` &mdash; attribute table (Buffer or ArrayBuffer)
-- `.prj` &mdash; coordinate system (string)
-
-Without `.dbf` you'll get geometry but no attributes; without `.prj`, projection-dependent commands won't have a coordinate system to work from.
-
-```javascript
-const input = {
-  'world.shp': shpBuffer,
-  'world.dbf': dbfBuffer,
-  'world.prj': prjString
-};
-const output = await mapshaper.applyCommands(
-  '-i world.shp -simplify 10% -o world.geojson', input
-);
-```
-
-## Versioning
-
-The Node API is stable across minor Mapshaper releases, but new options and commands appear regularly. The full set of accepted command-line options is the same as the CLI's, so the [command reference](/docs/reference.html.md) is the authoritative list of what you can put into the `commands` string.