masonry/examples/lang/readme.md

# 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