PLC Bundle V1 Example Implementations
atscan.net
1# PLC Bundle V1 Example Implementations
2
3This set of scripts represents a compact, readable example implementations for creating [PLC Bundle](https://tangled.org/@atscan.net/plcbundle) v1 archives. It fetches operations from the PLC directory and generates a complete, verifiable repository of data bundles.
4
5It is fully compliant with the [PLC Bundle v1 Specification](https://tangled.org/atscan.net/plcbundle/blob/main/docs/specification.md).
6
7## Features
8
9- **Spec Compliant:** Correctly implements hashing, chaining, serialization, and boundary de-duplication.
10- **Reproducible:** Generates byte-for-byte identical bundles to the other implementations.
11- **Standalone:** Single-file script with clear dependencies.
12
13## Implementations
14
15| Language | File |
16| --- | --- |
17| [TypeScript](#typescript) | [`typescript/plcbundle.ts`](typescript/plcbundle.ts) |
18| [Python](#python) | [`python/plcbundle.py`](python/plcbundle.py) |
19| [Ruby](#ruby) | [`ruby/plcbundle.rb`](ruby/plcbundle.rb) |
20
21## TypeScript
22
23File: [`typescript/plcbundle.ts`](typescript/plcbundle.ts)
24
25### Usage
26
27This script should run well with **[Bun](https://bun.com/) (recommended)**, [Deno](https://deno.com/), or [Node.js](https://nodejs.org/en).
28
29The script accepts one optional argument: the path to the output directory where bundles will be stored. If omitted, it defaults to `./plc_bundles`.
30
31#### Bun (Recommended)
32
33Bun is the fastest and easiest way to run this script, as it handles TypeScript and dependencies automatically.
34
35```sh
36# Install dependencies
37bun install
38
39# Run the script to create bundles in ./my_plc_bundles
40bun run plcbundle.ts ./my_plc_bundles
41```
42
43#### Deno
44
45Deno can also run the script directly. You will need to provide permissions for network access and file system I/O.
46
47```sh
48# Run the script with Deno
49deno run --allow-net --allow-read --allow-write plcbundle.ts ./my_plc_bundles
50```
51
52#### Node.js (with TypeScript)
53
54If using Node.js, you must first install dependencies and compile the TypeScript file to JavaScript.
55
56```sh
57# Install dependencies
58npm install
59
60# Compile the script
61npx tsc
62
63# Run the compiled JavaScript
64node dist/plcbundle.js ./my_plc_bundles
65```
66
67---
68
69
70
71## Python
72
73File: [`python/plcbundle.py`](python/plcbundle.py)
74
75### Usage
76
77TODO
78
79## Ruby
80
81File: [`ruby/plcbundle.rb`](ruby/plcbundle.rb)
82
83### Prerequisites
84
85You need Ruby installed (version 3+ recommended).
86
87### Installation
88
89The script relies on two external gems for HTTP requests and Zstandard compression.
90
91```sh
92# Install required gems
93gem install zstd-ruby
94```
95
96### Usage
97
98Run the script from your terminal. It accepts one optional argument: the path to the output directory.
99
100```sh
101# Run and save bundles to the default './plc_bundles_rb' directory
102ruby plcbundle.rb
103
104# Run and save to a custom directory
105ruby plcbundle.rb ./my_ruby_bundles
106```