bytecraft 0.4.0

A lightweight DSL for scaffolding files and folders

🧱 Bytecraft

A human-readable DSL for scaffolding files and folders.

pip install bytecraft

---

Bytecraft lets you describe a project structure in plain, readable instructions and execute it with a single command — no Bash, no Python boilerplate, no mental overhead. Designed with data pipelines and scaffold-heavy workflows in mind.

# pipeline.bc

load-vars "pipeline.ebv"

set-working-folder "{{project}}"

for i in 1 to {{num_partitions}}
  make-file "data/partition_{{i:03}}.parquet"
  make-file "schemas/schema_{{i:03}}.json" with "{ \"partition\": {{i}} }"
end-for

py -m bytecraft pipeline.bc

[Bytecraft] Loaded 3 variable(s) from: pipeline.ebv
[Bytecraft] Working folder set: my-pipeline
[Bytecraft] Created file: my-pipeline/data/partition_001.parquet
[Bytecraft] Created file: my-pipeline/schemas/schema_001.json
...

---

Installation

Requires Python 3.10+

pip install bytecraft

---

Commands

set-working-folder

Sets the base directory for all subsequent relative paths. Created automatically if it doesn't exist.

set-working-folder "my-project"

---

make-folder

Creates a directory and any missing parent directories. Does nothing if the folder already exists.

make-folder "data/raw"

---

make-file

Creates a file. Parent directories are created automatically. Overwrites if the file already exists.

# Empty file
make-file "src/__init__.py"

# Inline content
make-file "VERSION" with "1.0.0"

# Multi-line content block
make-file "README.md" with ---
# My Project

Some description here.
---

---

append-file

Appends content to an existing file. Creates the file if it doesn't exist. A newline is automatically inserted before the new content if the file is non-empty.

make-file "pipeline.log" with "Pipeline started"
append-file "pipeline.log" with "Stage 1 complete"
append-file "pipeline.log" with "Stage 2 complete"

Multi-line blocks work too:

append-file "README.md" with ---

## Changelog

Added in v2.
---

---

copy-file

Copies a file or folder to a new location. Parent directories are created automatically. If copying a folder that already exists at the destination, it is replaced.

copy-file "src/app.py" to "backup/app.py"
copy-file "src" to "src_backup"

---

move-file

Moves a file or folder to a new location. Parent directories are created automatically.

move-file "build/output.js" to "dist/app.js"
move-file "temp" to "archive/temp"

---

delete-file

Deletes a file. Warns if the path doesn't exist or points to a folder.

delete-file "temp.log"
delete-file "{{build_dir}}/old_output.csv"

---

delete-folder

Deletes a folder and all its contents. Warns if the path doesn't exist or points to a file.

delete-folder "temp"
delete-folder "{{build_dir}}/cache"

---

make-zip

Creates a zip archive from a file or folder. Folder structure is preserved inside the zip.

make-zip "releases/v1.0.zip" from "dist"
make-zip "releases/data.zip" from "data/processed"

---

set

Defines a variable. Variables are referenced anywhere using {{name}} syntax — in paths, content, template calls, and loop bodies.

set project "my-pipeline"
set version "1.0.0"

make-file "VERSION" with "{{version}}"

---

load-vars

Loads variables from an .ebv (External Bytecraft Variables) file. Useful for sharing config across multiple scripts or driving loops from external values.

load-vars "config.ebv"

config.ebv:

# Pipeline config
project = my-pipeline
version = 1.0.0
author = Sourasish Das
env = prod
num_partitions = 24
num_shards = 8

Lines starting with # are ignored. Values do not need quotes.

---

for

Loops over a list of values or an integer range. The loop variable is available inside the body via {{name}}. Range bounds can be variables. Loops can be nested.

# Value list
for env in "dev" "staging" "prod"
  make-file "config/{{env}}.json" with "{ \"env\": \"{{env}}\" }"
end-for

# Integer range
for i in 1 to 10
  make-file "logs/day_{{i}}.log"
end-for

# Variable range bounds (driven by .ebv)
load-vars "pipeline.ebv"
for i in 1 to {{num_partitions}}
  make-file "data/partition_{{i:03}}.parquet"
end-for

Format specs

Loop variables (and any numeric variable) support Python-style format specs using {{var:fmt}}:

Syntax	Example output
{{i:02}}	01, 02, ... 09, 10
{{i:03}}	001, 002, ... 099, 100
{{i:>5}}	1, 2 (right-aligned)

for i in 1 to 100
  make-file "shards/shard_{{i:03}}.csv"
end-for
# → shard_001.csv, shard_002.csv, ... shard_100.csv

---

if / else-if / else

Conditionally executes a block. Supports file existence checks and variable comparisons. Supports else-if and else chains. Can be nested inside loops and other if blocks.

# File existence
if exists "data/processed"
  make-folder "data/archive"
end-if

if not exists "dist"
  make-folder "dist"
end-if

# Variable comparison with else-if / else
if "{{env}}" is "prod"
  make-file "config.json" with "{ \"debug\": false, \"strict\": true }"
else-if "{{env}}" is "staging"
  make-file "config.json" with "{ \"debug\": true, \"strict\": true }"
else
  make-file "config.json" with "{ \"debug\": true, \"strict\": false }"
end-if

# Negation
if "{{env}}" is not "dev"
  include "hardening.bc"
end-if

---

define-template / use-template

Templates let you define reusable scaffolding blocks and stamp them out with different values. Variables passed to use-template are local to that call and do not leak back into the outer script.

define-template "dataset"
  make-folder "data/{{name}}/raw"
  make-folder "data/{{name}}/processed"
  make-file "data/{{name}}/README.md" with "# {{name}} dataset"
end-template

use-template "dataset" name "customers"
use-template "dataset" name "orders"
use-template "dataset" name "products"

---

include

Runs another .bc file inline with fully shared state. Variables, templates, the working folder, and strict mode all carry across in both directions. Paths are resolved relative to the calling script's directory.

include "base.bc"
include "templates/data-pipeline.bc"

---

strict on / strict off

In strict mode, warnings become fatal errors — undefined variables, unknown commands, and missing source files all halt execution immediately. Can be toggled on and off within the same script.

strict on

make-file "VERSION" with "{{version}}"   # fine if version is set
make-file "bad.txt" with "{{typo}}"      # ERROR: halts execution

strict off

---

Comments

Lines starting with # are ignored.

# This is a comment

---

Forgiving Syntax

Bytecraft is intentionally forgiving. Quotes are optional — if they're missing, Bytecraft will recover and interpret your intent:

make-file hello.txt with Hello World

is treated the same as:

make-file "hello.txt" with "Hello World"

Unknown commands print a warning and are skipped rather than crashing the script. Use strict on if you want the opposite behaviour.

---

Full Example

# Data pipeline scaffold

strict on

load-vars "pipeline.ebv"

set-working-folder "{{project}}"

# Dataset template
define-template "dataset"
  make-folder "data/{{name}}/raw"
  make-folder "data/{{name}}/processed"
  make-folder "data/{{name}}/archive"
  make-file "data/{{name}}/README.md" with "# {{name}} dataset — {{project}}"
end-template

use-template "dataset" name "customers"
use-template "dataset" name "orders"
use-template "dataset" name "products"

# Generate partitioned output files
for i in 1 to {{num_partitions}}
  make-file "output/partition_{{i:03}}.parquet"
end-for

# Per-environment configs
for env in "dev" "staging" "prod"
  if "{{env}}" is "prod"
    make-file "config/{{env}}.json" with "{ \"debug\": false, \"strict\": true }"
  else-if "{{env}}" is "staging"
    make-file "config/{{env}}.json" with "{ \"debug\": true, \"strict\": true }"
  else
    make-file "config/{{env}}.json" with "{ \"debug\": true, \"strict\": false }"
  end-if
end-for

# Build log
make-file "pipeline.log" with "Scaffold started"
append-file "pipeline.log" with "Datasets created"
append-file "pipeline.log" with "Partitions generated"
append-file "pipeline.log" with "Configs written"

# Package for release in prod only
if "{{env}}" is "prod"
  copy-file "output" to "dist/output"
  make-zip "releases/{{project}}-{{version}}.zip" from "dist"
  append-file "pipeline.log" with "Release packaged"
end-if

pipeline.ebv:

project = my-pipeline
version = 1.0.0
author = Sourasish Das
env = prod
num_partitions = 24

---

Limitations (v0.4.0)

• No arithmetic expressions (e.g. {{i}} + 1)
• No string operations (concat, slice, etc.)
• No nested variable references (e.g. {{{{key}}}})

---

Roadmap

• Variables and interpolation
• Multi-line file content blocks
• copy-file and move-file
• make-zip
• append-file
• Templates (define-template / use-template)
• include
• Strict mode
• for loops (value lists and ranges)
• Variable range bounds
• Zero-padding format specs ({{i:03}})
• if / else-if / else
• .ebv external variable files
• delete-file and delete-folder
• Arithmetic expressions
• String operations

---

License

Server-Lab Open-Control License (SOCL) 1.0
Copyright (c) 2025 Sourasish Das