@neoncitylights/piper

This library provides some utilities for walking through specific HTML elements and turning into machine-readable data.

Install

npm install @neoncitylights/piper
Copy

Documentation

Auto-generated API documentation is available.

API Reference

Walker functions

• fn: # walkDescriptionList.walkDescriptionList<*K*, *V*>(element, termCallback, detailsCallback): Map<K, V> • source
• fn: # walkTable.walkTable(table): TableRow[][] • source

Walker helper utilities

• T: # walkTable.TableBodies • source
• T: # walkTable.TableRow • source
• C: # walkTable.TableModelError • source
• fn: # walkTable.collectProperties(table): string[] • source
• fn: # walkTable.collectTableBodies(table): TableBodies • source
• fn: # walkTable.collectTableRows(table): TableRow • source

Table utilities

• T: # tableUtils.HTMLTableLikeElement • source
• fn: # tableUtils.isTableLikeElement(element): element is HTMLTableRelatedElement • source
• fn: # tableUtils.getTableCaption(table): string • source
• fn: # tableUtils.getClosestParentTable(element): HTMLTableElement|undefiend • source
• fn: # tableUtils.getClosestParentTableByRow(row): HTMLTableElement • source

Usage

import { walkDescriptionList, walkTable } from '@neoncitylights/piper';

// walking through a description list
let descListElement = document.querySelector('dl#my-description-list') as HTMLDListElement;
let descList = walkDescriptionList(
    descListElement,
    (term) => term.textContent ?? '',
    (details) => details.textContent ?? '');

// walking through a table
let timezonesTable = document.querySelector('table') as HTMLTableElement;
let timezones = walkTable(timezonesTable);
Copy

Full examples

Walking through a description list (<dl>)

<dl id="prefs">
    <div>
        <dt>Extensions</dt>
        <dd>Remove, install, and change settings of extensions</dd>
    </div>
    <div>
        <dt>Site activity</dt>
        <dd>Learn how visitors are using your site</dd>
    </div>
    <div>
        <dt>Layout and appearance</dt>
        <dd>Change how your site appears to viewers</dd>
    </div>
    <div>
        <dt>Privacy</dt>
        <dd>Decide who is able to access your site</dd>
    </div>
    <div>
        <dt>Security and storage</dt>
        <dd>Backup, update, and protect your site</dd>
    </div>
</dl>
Copy

import { walkDescriptionList } from '@neoncitylights/piper';

const prefsElement = document.getElementById('prefs') as HTMLDListElement;
const prefs = walkDescriptionList(prefsElement,
    (term) => term.textContent ?? '',
    (details) => details.textContent ?? '');
Copy

{
    "Extensions": "Remove, install, and change settings of extensions",
    "Site activity": "Learn how visitors are using your site",
    "Layout and appearance": "Change how your site appears to viewers",
    "Privacy": "Decide who is able to access your site",
    "Security and storage": "Backup, update, and protect your site."
}
Copy

Walking through a table (<table>)

<table class="wikitable" id="timezone-examples">
    <thead>
        <tr>
            <th>Name</th>
            <th>Explanation</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><a href="/wiki/America/Costa_Rica">America/Costa_Rica</a></td>
            <td>name of country used because the name of the largest city (and capital city) <a href="/wiki/San_Jos%C3%A9,_Costa_Rica" >San José</a> is <a href="/wiki/San_Jos%C3%A9_(disambiguation)#Places">ambiguous</a></td>
        </tr>
        <tr>
            <td><a href="/wiki/America/New_York">America/New_York</a></td>
            <td>Space replaced with underscore</td>
        </tr>
        <tr>
            <td><a href="/wiki/Asia/Kolkata">Asia/Kolkata</a></td>
            <td>name of city of <a href="/wiki/Kolkata">Kolkata</a> used, because it was the most populous city in the zone at the time the zone was set up, though this is no longer true<sup><a href="#cite_note-17">[17]</a></sup></td>
        </tr>
        <tr>
            <td><a href="/wiki/Asia/Sakhalin">Asia/Sakhalin</a></td>
            <td>name of island used, because largest city, <a href="/wiki/Yuzhno-Sakhalinsk">Yuzhno-Sakhalinsk</a>, has more than 14 characters</td>
        </tr>
        <tr>
            <td><a href="/wiki/America/Bahia_Banderas">America/Bahia_Banderas</a></td>
            <td>"de" removed from <a href="/wiki/Bahia_de_Banderas">Bahia de Banderas</a>, because correct name has more than 14 characters</td>
        </tr>
        <tr>
            <td><a href="/wiki/Antarctica/DumontDUrville">Antarctica/DumontDUrville</a></td>
            <td>the apostrophe is removed. The space would normally be replaced with "_", but the name would then exceed 14 characters.</td>
        </tr>
    </tbody>
</table>
Copy

import { walkTable } from '@neoncitylights/piper';

let timezoneTableElement = document.getElementById('timezone-examples') as HTMLTableElement;
let timezoneExamples = walkTable(timezoneTableElement);
Copy

[
    [
        {
            "Name": "America/Costa_Rica",
            "Explanation": "name of country used because the name of the largest city (and capital city) San José is ambiguous"
        },
        {
            "Name": "America/New_York",
            "Explanation": "Space replaced with underscore"
        },
        {
            "Name": "Asia/Kolkata",
            "Explanation": "name of city of Kolkata used, because it was the most populous city in the zone at the time the zone was set up, though this is no longer true[17]"
        },
        {
            "Name": "Asia/Sakhalin",
            "Explanation": "name of island used, because largest city, Yuzhno-Sakhalinsk, has more than 14 characters"
        },
        {
            "Name": "America/Bahia_Banderas",
            "Explanation": "de removed from Bahia de Banderas, because correct name has more than 14 characters"
        },
        {
            "Name": "Antarctica/DumontDUrville",
            "Explanation": "the apostrophe is removed. The space would normally be replaced with \"_\", but the name would then exceed 14 characters."
        }
    ]
]
Copy

License

This library is licensed under the MIT License.