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

server MyApp {
    host "localhost"
    port 8080
}

2. Entity Definitions

Define your data models with fields, types, validation, and relationships:

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:

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:

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:

# 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:

./masonry.exe generate html -i app.masonry -o ./output

Template-based Generation

Use custom templates for code generation:

# 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:

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:

./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