1# javascript-data-files
2
3This is a collection of Python functions for manipulating JavaScript "data files" -- that is, JavaScript files that define a single variable with a JSON value.
4
5This is an example of a JavaScript data file:
6
7```javascript
8const shape = { "sides": 5, "colour": "red" };
9```
10
11Think of this module as the JSON module, but for JavaScript files.
12
13These data files are meant to be both human- and machine-readable.
14
15## Usage
16
17If you install `javascript-data-files`:
18
19*   You can read a JavaScript file with `read_js(path, varname)`
20*   You can write a JavaScript file with `write_js(path, value, varname)`
21*   You can append an item to a JavaScript array with `append_to_js_array(path, value)`
22*   You can append a key-value pair to a JavaScript object with `append_to_js_object(path, key, value)`
23
24If you install `javascript-data-files[typed]`:
25
26*   You can read a JavaScript file and validate it matches a particular Python type with `read_typed_js(path, varname, model)`.
27
28## Installation
29
30You have two options:
31
321.  Copy the file `src/javascript` folder into your project.
33    You probably want to copy the tests as well.
34
352.  Install the package using pip:
36
37    ```console
38    $ pip install javascript-data-files
39    ```
40
41## Why not use JSON files?
42
43If you've opening an HTML file from disk, you can load data from a local JavaScript file, for example:
44
45```html
46<script src="file://users/alexwlchan/repos/javascript-data-files/data.js"></script>
47```
48
49This is the only way to load data from an external file from an HTML file you've opened locally -- you can't do this with a JSON file, for example.
50
51I have a lot of HTML files and local sites I build with an HTML viewer and metadata in a JavaScript file.
52The convenience of this approach outweighs the mild annoyance of having to store data in JavaScript, not JSON.
53
54## Development
55
56If you want to make changes to the library, there are instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
57
58## License
59
60MIT.