From befd675c7d2246eccd402d4f78516301bb11d91f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 6 Oct 2023 17:04:09 +0200 Subject: [PATCH 1/2] restructure README (#51) https://github.com/d3/d3/issues/3775 --- README.md | 113 ++++-------------------------------------------------- 1 file changed, 7 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index a9451a1..38d501b 100644 --- a/README.md +++ b/README.md @@ -1,111 +1,12 @@ # d3-fetch -This module provides convenient parsing on top of [Fetch](https://fetch.spec.whatwg.org/). For example, to load a text file: + -```js -const text = await d3.text("/path/to/file.txt"); -console.log(text); // Hello, world! -``` +This module provides convenient parsing on top of [Fetch](https://fetch.spec.whatwg.org/), with built-in support for parsing JSON, CSV, and TSV. -To load and parse a CSV file: +## Resources -```js -const data = await d3.csv("/path/to/file.csv"); -console.log(data); // [{"Hello": "world"}, …] -``` - -This module has built-in support for parsing [JSON](#json), [CSV](#csv), and [TSV](#tsv). You can parse additional formats by using [text](#text) directly. (This module replaced [d3-request](https://github.com/d3/d3-request).) - -## Installing - -If you use npm, `npm install d3-fetch`. You can also download the [latest release on GitHub](https://github.com/d3/d3-fetch/releases/latest). For vanilla HTML in modern browsers, import d3-fetch from Skypack: - -```html - -``` - -For legacy environments, you can load d3-fetch’s UMD bundle from an npm-based CDN such as jsDelivr; a `d3` global is exported: - -```html - - -``` - -## API Reference - -# d3.blob(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/blob.js "Source") - -Fetches the binary file at the specified *input* URL as a Blob. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. - -# d3.buffer(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/buffer.js "Source") - -Fetches the binary file at the specified *input* URL as an ArrayBuffer. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. - -# d3.csv(input[, init][, row]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/dsv.js "Source") - -Equivalent to [d3.dsv](#dsv) with the comma character as the delimiter. - -# d3.dsv(delimiter, input[, init][, row]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/dsv.js "Source") - -Fetches the [DSV](https://github.com/d3/d3-dsv) file at the specified *input* URL. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. An optional *row* conversion function may be specified to map and filter row objects to a more-specific representation; see [*dsv*.parse](https://github.com/d3/d3-dsv#dsv_parse) for details. For example: - -```js -const data = await d3.dsv(",", "test.csv", (d) => { - return { - year: new Date(+d.Year, 0, 1), // convert "Year" column to Date - make: d.Make, - model: d.Model, - length: +d.Length // convert "Length" column to number - }; -}); -``` - -If only one of *init* and *row* is specified, it is interpreted as the *row* conversion function if it is a function, and otherwise an *init* object. - -See also [d3.csv](#csv) and [d3.tsv](#tsv). - -# d3.html(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/xml.js "Source") - -Fetches the file at the specified *input* URL as [text](#text) and then [parses it](https://developer.mozilla.org/docs/Web/API/DOMParser) as HTML. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. - -# d3.image(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/image.js "Source") - -Fetches the image at the specified *input* URL. If *init* is specified, sets any additional properties on the image before loading. For example, to enable an anonymous [cross-origin request](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image): - -```js -const img = await d3.image("https://example.com/test.png", {crossOrigin: "anonymous"}); -``` - -# d3.json(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/json.js "Source") - -Fetches the [JSON](http://json.org) file at the specified *input* URL. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. If the server returns a status code of [204 No Content](https://developer.mozilla.org/docs/Web/HTTP/Status/204) or [205 Reset Content](https://developer.mozilla.org/docs/Web/HTTP/Status/205), the promise resolves to `undefined`. - -# d3.svg(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/xml.js "Source") - -Fetches the file at the specified *input* URL as [text](#text) and then [parses it](https://developer.mozilla.org/docs/Web/API/DOMParser) as SVG. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. - -# d3.text(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/text.js "Source") - -Fetches the text file at the specified *input* URL. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. - -# d3.tsv(input[, init][, row]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/dsv.js "Source") - -Equivalent to [d3.dsv](#dsv) with the tab character as the delimiter. - -# d3.xml(input[, init]) · [Source](https://github.com/d3/d3-fetch/blob/master/src/xml.js "Source") - -Fetches the file at the specified *input* URL as [text](#text) and then [parses it](https://developer.mozilla.org/docs/Web/API/DOMParser) as XML. If *init* is specified, it is passed along to the underlying call to [fetch](https://fetch.spec.whatwg.org/#fetch-method); see [RequestInit](https://fetch.spec.whatwg.org/#requestinit) for allowed fields. +- [Documentation](https://d3js.org/d3-fetch) +- [Examples](https://observablehq.com/collection/@d3/d3-fetch) +- [Releases](https://github.com/d3/d3-fetch/releases) +- [Getting help](https://d3js.org/community) From 407684e25ca21bf023751cbd9286f72b9c3af603 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 6 Oct 2023 17:40:04 +0200 Subject: [PATCH 2/2] no examples --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 38d501b..668de41 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,5 @@ This module provides convenient parsing on top of [Fetch](https://fetch.spec.wha ## Resources - [Documentation](https://d3js.org/d3-fetch) -- [Examples](https://observablehq.com/collection/@d3/d3-fetch) - [Releases](https://github.com/d3/d3-fetch/releases) - [Getting help](https://d3js.org/community)