From ca0736b92c93ff31cd0b23ff6d88da4ef643fcc9 Mon Sep 17 00:00:00 2001 From: Mason Payne Date: Mon, 1 Sep 2025 15:02:32 -0600 Subject: [PATCH] add instructions for AI and a readme for examples --- .github/copilot-instructions.md | 12 ++ examples/lang/readme.md | 202 ++++++++++++++++++++++++++++++++ 2 files changed, 214 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 examples/lang/readme.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..e6f54cb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,12 @@ +For terminal commands use commands that are compatible with Windows GitBash. + +If building, running or testing changes to the CLI program, use this command to build local changes: +`go build -o masonry.exe ./cmd/cli/` + +You can assume your working directory is `~/src/masonry` + +Do not delete or replace files if you can't read them. Sometimes there are bugs with your file system integration. The user will want to fix any integration issue you may encounter. + +When adding tests, always write tests that exercise the code that ends up in the product. Do not re-implement functions just to run tests against. Refactoring code to make it more testable is acceptable. + +As we add features to Masonry, adding fully implemented examples of using those features as new directories in the `examples` directory under their own self-contained directory with a readme.md is highly encouraged. Similar to the libp2p project. diff --git a/examples/lang/readme.md b/examples/lang/readme.md new file mode 100644 index 0000000..32df0c4 --- /dev/null +++ b/examples/lang/readme.md @@ -0,0 +1,202 @@ +# Basic DSL Usage + +## Overview + +The Masonry DSL (Domain Specific Language) is a unified syntax for defining full-stack applications. It allows you to describe servers, entities, API endpoints, and user interfaces in a single file, which can then be generated into various output formats including Go servers, HTML, and more. + +## Quick Start + +1. **Create a new Masonry file** (e.g., `app.masonry`) +2. **Define your application structure** using the DSL syntax +3. **Generate code** using the Masonry CLI + +## Basic DSL Structure + +A Masonry file consists of these main components: + +### 1. Server Configuration +```masonry +server MyApp { + host "localhost" + port 8080 +} +``` + +### 2. Entity Definitions +Define your data models with fields, types, validation, and relationships: + +```masonry +entity User desc "User account management" { + id: uuid required unique + email: string required validate email + name: string default "Anonymous" + created_at: timestamp default "now()" + profile_id: uuid relates to Profile as one +} +``` + +**Supported field types:** +- `uuid`, `string`, `text`, `int`, `boolean`, `timestamp` + +**Field modifiers:** +- `required` - Field is mandatory +- `unique` - Field must be unique +- `indexed` - Field should be indexed +- `default "value"` - Set default value +- `validate email` - Email validation +- `validate url` - URL validation +- `validate min_length "5"` - Minimum length validation +- `validate max_length "100"` - Maximum length validation + +**Relationships:** +- `relates to EntityName as one` - One-to-one relationship +- `relates to EntityName as many` - One-to-many relationship +- `relates to EntityName as many through "table_name"` - Many-to-many through table + +### 3. API Endpoints +Define REST API endpoints with parameters and responses: + +```masonry +endpoint GET "/users" for User desc "List users" auth { + param page: int from query + param limit: int required from query + returns list as "json" fields [id, email, name] +} + +endpoint POST "/users" for User desc "Create user" { + param user_data: object required from body + returns object as "json" fields [id, email, name] +} +``` + +**HTTP methods:** `GET`, `POST`, `PUT`, `DELETE` + +**Parameter sources:** +- `from query` - Query string parameter +- `from path` - URL path parameter +- `from body` - Request body parameter + +**Features:** +- `auth` - Requires authentication +- `returns list/object` - Response type +- `fields [...]` - Specify response fields + +### 4. User Interface Pages +Define web pages with components and layouts: + +```masonry +page UserManagement at "/admin/users" layout AdminLayout title "User Management" auth { + meta description "Manage system users" + + section main type container { + component UserTable for User { + fields [email, name, created_at] + actions [edit, delete, view] + data from "/users" + } + } +} +``` + +**Page features:** +- `layout LayoutName` - Page layout +- `title "Page Title"` - Page title +- `auth` - Requires authentication +- `meta` - SEO metadata + +**Sections and Components:** +- `section` - Layout containers with types (container, panel, tab, modal) +- `component` - Reusable UI elements +- `data from "/endpoint"` - Data binding + +## CLI Commands + +### Generate a Server +Generate and optionally run a Go HTTP server: + +```bash +# Generate server code +./masonry.exe serve -f app.masonry -o server.go + +# Generate and run server +./masonry.exe serve -f app.masonry -r +``` + +### Generate HTML +Convert Masonry files to static HTML: + +```bash +./masonry.exe generate html -i app.masonry -o ./output +``` + +### Template-based Generation +Use custom templates for code generation: + +```bash +# Use a single template file +./masonry.exe template -i app.masonry -t my-template.tmpl -o output.go + +# Use a template directory +./masonry.exe template -i app.masonry -d ./templates -r main.tmpl -o output.go +``` + +## Example Workflow + +1. **Create a simple blog application:** + +```masonry +server BlogApp { + host "localhost" + port 8080 +} + +entity Post { + id: uuid required unique + title: string required + content: text required + published: boolean default "false" + created_at: timestamp default "now()" +} + +endpoint GET "/posts" for Post { + returns list fields [id, title, published] +} + +endpoint POST "/posts" for Post { + param post_data: object required from body + returns object +} + +page PostList at "/posts" title "Blog Posts" { + component PostTable for Post { + fields [title, published, created_at] + data from "/posts" + } +} +``` + +2. **Generate and run the server:** + +```bash +./masonry.exe serve -f blog.masonry -r +``` + +3. **Visit http://localhost:8080 to see your generated application** + +## Advanced Features + +- **Conditional rendering** with `when` statements +- **Complex layouts** with nested sections +- **Form validation** and custom field types +- **Authentication** and authorization +- **Relationships** between entities +- **Custom templates** for different output formats + +For a complete example showcasing all features, see the `example.masonry` file in this directory. + +## Next Steps + +- Explore the full `example.masonry` to see advanced features +- Create custom templates for your preferred frameworks +- Use the `setup` command to install required dependencies +- Check out other examples in the `/examples` directory