https://github.com/dokun1/Vaux

A HTML DSL library for Swift
https://github.com/dokun1/Vaux

dsl html swift

Last synced: about 1 month ago
JSON representation

A HTML DSL library for Swift

• Host: GitHub
• URL: https://github.com/dokun1/Vaux
• Owner: dokun1
• License: apache-2.0
• Created: 2019-06-06T17:36:49.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2020-04-21T20:07:36.000Z (over 4 years ago)
• Last Synced: 2024-03-14T15:26:14.463Z (9 months ago)
• Topics: dsl, html, swift
• Language: Swift
• Homepage:
• Size: 146 KB
• Stars: 597
• Watchers: 11
• Forks: 19
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

• awesome-result-builders - Vaux - A HTML DSL library for Swift (HTML)

README

        

# Vaux



  

    

  

  

    

  

  

    

  

  

    

  

  

    

  



Vaux is a library that allows you to generate HTML using Swift. It includes a domain-specific language written in Swift for HTML, and its purpose is to allow developers to write HTML, but in Swift.

**Warning**: If you are reading this, this is alpha software based on Swift 5.1, which is currently only downloadable from [swift.org](https://swift.org) or in Xcode 11 Beta. This is a work in progress in every sense of the phrase.

## Requirements

- Swift 5.1

## Motivation

At WWDC2019, Apple announced functionality for a new feature in Swift called [Function Builders](https://github.com/rjmccall/swift-evolution/blob/function-builders/proposals/XXXX-function-builders.md). The core functionality of Vaux, which includes a Swift DSL for HTML, is heavily inspired by this proposal and corresponding examples. As such, this library exists with two primary goals:

- Provide an underpinning for future potential opinionated frameworks for web interfaces written in Swift (for example, [this](https://github.com/dokun1/SwiftWebUI)).

- Learn more about function builders.

At the time of this library's first open source release, it is standing tall on the shoulders of giants, and gratitude is in order.

## Example

Let's say you want to write the following HTML:

```html

  

    

      Page title

    

  

  

    


      Page body

    

  


```

Rather than write this out by hand, you can first write a function that will return HTML using Vaux:

```swift

var pageTitle = "Page title"

var pageBody = "Page body"

func simplePage() -> HTML {

  html {

    head {

      title(pageTitle)

    }

    body {

      div {

        pageBody

      }

    }

  }

}

```

Then, you can render the function result into a static html file using Vaux like so:

```swift

let vaux = Vaux()

vaux.outputLocation = .file(name: "testing", path: "/tmp/")

do {

  try vaux.render(html)

} catch let error {

  print("Uh-oh, something happened: \(error.localizedDescription)")

}

```

The end result is that you have a file called `testing.html` in your `/tmp/` directory.

## Creating HTML elements

**Note**: For a series of real use cases for Vaux, check out `VauxTests.swift` to see examples of different tags.

Write a function that returns `HTML`, and add your builders inside this function:

```swift

func buildPage() -> HTML {

}

```

## Documentation

_Coming soon..._

## Importing This Library

Vaux is available as a Swift package on GitHub. If you are using the Xcode 11 beta, you can simply add this url (https://github.com/dokun1/Vaux) as a dependency. Otherwise, you must include this as a dependency in your `Package.swift` file and use the command line to to create a project for this.