This library exposes data from Web IDL specifications as Go types.
Data is sourced from github.com/w3c/webref. The data in the release package contains data from the curated list, i.e. types that have reached a level of maturity, and can assumed to be supported by major browsers.
Please reach out if you are interested in the bleeding edge specs.
Important
This tool is not complete. Not all IDL information are exposed. If you find that you need something not exposed, please file an issue. Or even better, make a PR.
This is not a complete representation of all data, but strives to be the place to look.
Features are added as necessary from gost-dom, or user feedback.
This package is divided into subpackages:
elementscontains mapping from HTML element tag names to IDL interface name.idlcontains the Web IDL specifications.eventsinformation about the different event types being dispatched.
This exposes element tag name to interface name mapping, i.e., which type is used at runtime to handle a specific element.
E.g., an <a> element in the HTML will be handled by an HTMLAnchorElement in
code.
There is not a one-to-one mapping between tag names, and elements names. In
the html specs, multiple elements are handled by the generic HTMLElement.
Examples include, <article>, <section>, and <nav>. Then are all elements
for representation with no behaviour associated.
Contain specifications for the interfaces available at runtime; and made accessible to client-side code.
spec, err := idl.Load("html")
anchor := spec.Interfaces["HTMLAnchorElement"]
for _, o := anchor.Attributes {
// ...
}
for _, o := anchor.Operations {
// ...
}
The first version of idl module consisted was a "reverse engineering" of the
JSON data. This data should be contain all information in the source data. But
this exposes a less useful model.
A new interface was starter, better representing the Web IDL itself, using terms
like Interface instead of Name for types representing an interface
specification.
The new data model is not completed, i.e., not all source data is exposed. As a solution to missing information, the data has references to the the legacy objects representing the same data.
The legacy model is in the idl/legacy subpackage, and should not be used
unless the information is not present in the idl package itself.
If you depend on this information, please submit an issue, or even better, file a PR,
A click event bubbles and is cancelable. A formdata also bubbles, but isn't
cancelable. That is the type of information present in the events package.
This codebase is tested in general terms by inspecting properties on select
values, and comparing them against expectations. E.g., the URL interface from
the url specification should have a non-static toJSON operation, and a
static parse operation.
When support is added for a new type of information, new tests should be added verifying the information on real types in the IDL specification, both positive and negative tests, i.e., add tests for types that don't have this type of information.
The folder internal/specs/sources is a git submodule pointing to the
curated list of webref files.
A make target copies the used files to internal/specs/curated, and processes
them for smaller footprint, removing whitespace and unused attributes
To update the sources, you must get the submodule, update to the latest branch, and rerun the make script
If you didn't already, get the submodule git submodule update --init
If you already had the data, from the internal/specs/sources folder run
git fetch # if you have previously retrieved the data, get latest)
git checkout origin/curatedFrom the root of the project, run (note, this requires a unix-like shell)
make specs
Run the test suite, and commit the changes if successful, including the
internal/specs/sources containing the new commit hash.
If you need to add support for more "folders" in the sources, you need to:
- Add this to the list of processed folders in the Makefiles. Check comments for how
- Create the output folder, the target fails if the folder doesn't exist.
- Run the
specsmake target.
The compiled library takes up about 6Mb on disk, which is mainly embedded data files, which also takes up space in source code.1
It is not a priotity to reduce this. This is a tool intended for design-time use, not runtime.
However, a PR to reduce compiled file size would be welcome, though a more complete model should be
The file size (and source code) could be reduced by one of two approaces
- Parse IDL files instead of JSON
- Generate Go code from JSON files
The JSON is a very verbose representation of the source IDL. By parsing and embedding IDL files, the source code, and compiled output would be significantly smaller.
You could generate Go source files with global variables initialised to the values representing the data.
Footnotes
-
The JSON data from the webref submodule is >15Mb in size. This tool copies and strips useless fields and whitespace, reducing the JSON data to ~5Mb. ↩