emerald-lang/emerald

:rocket: A whitespace-delimited, backend language-agnostic HTML5 templating engine

emerald's Issues

Attributes feature.

Need some advice for this one.

I had originally thought of doing attributes something like this:

html
  head
    title Attributes Example

  body
    h1 Attributes follow parentheses. (
      id     'header'
      class  'main-text'
      height '50px'
      width  '200px'
    )

  footer
    p Copyright Emerald Language 2016

I like the idea of having each attribute on a separate line, to try to mitigate long lines. I had figured that would look cleaner than:

html
  head
    title Attributes Example

  body
    h1(id 'header', class 'main-text', height '50px', width '200px') Some text after attributes

  footer
    p Copyright Emerald Language 2016

But I'm not sure, for longer lines, I don't know if the first way would look visually appealing.

I still like the idea of having each attribute on its own line, and having iteroperability with styles, and events - like this early emerald code:

    main
      section
        h1 Why use Emerald?
        p -> Emerald allows you to scope events and styles to html
          elements in an elegant, clean way.

      figure
        figcaption -> Here's an example of elements scoped in a
          button here.

        button Click me. (
          click -> console.log("I was clicked!")
          hover -> console.log("I was hovered!")
        )

What are your thoughts @davepagurek, @IceChen1?

Use a different tool for html-beautifying.

The gem we're using currently for beautification doesn't support html5 unfortunately. We should do some investigation into tools which support html5 beautification as well (or we could make a PR to the gem to support html5 😉).

Create classes which handle grammar rules

Create website for Emerald, in Emerald

got to eat our own dog food 🐕

Get rid of legacy ruby gem code

Note: Should be last issue completed in C++ milestone.

Add code coverage tool for tests.

Use some type of code coverage tool for ruby. Have an acceptable threshold of coverage, and ensure CircleCI builds pass this threshold.

Convert grammar over from treetop to cpp-peglib

Proposal: Different types of string literals

What are your thoughts different types of string literals?

p ->
  Hello, |name|

would become

<p>Hello, Dave</p>

and with a fat arrow:

p =>
  Hello, |name|

could have no interpolation and output:

<p>Hello, |name|</p>

This would give people a way to put text on the next line if it gets too long and still have interpolation, and a way to have a script or code tag without interpolation.

Make CLI output errors if it can't parse your input

It's pretty impossible to actually use Emerald without this

Fix repeated nodes

Looks like we can't get<peg::Semanticalues>() on a repeated node, it just adds itself into the list multiple times. We have to think about how to deal with this.

Document scaffolding, coding style

• Create markdown file for custom scaffolding usage.
• Create markdown file for cpp coding style (part of contributing guidelines).

Add support for comments.

The * character should denote single line comments.

Ex.

*
* Emerald Language
* Copyright 2016 Emerald
*

html
  head
    styles
      "css/main.css"
      "css/vendor/bootstrap.min.css"

    scripts
      "js/script.js"
      "js/other_script.js"

For multi-line comments, we should use the same syntax we use for multiline literals.

* ->
  Emerald Language
  Copyright 2016 Emerald

html
  head
    styles
      "css/main.css"
      "css/vendor/bootstrap.min.css"

    scripts
      "js/script.js"
      "js/other_script.js"

We are choosing to omit end of line comments in the language design.

Support escaped variable templating in the grammar

Add output filename option to CLI

So that it isn't always the same with .html appended. For example, if we want to output to a different directory.

Get CLI working

Handle self-closing tags

We need to do some checks in TagStatement#to_html to output a self-closing tag if the tag type is something like an img tag

Escape braces in preprocessor, and un-escape them in the code generation phase.

In the context free grammar, we use braces to signify indentation. The preprocessor adds braces based on the indentation level for emerald code. Hence, this code snippet

section
  div
    h1 This is a header.

becomes:

section
{
div
{
h1 This is a header.
}
}

We need to escape braces before preprocessing the emerald code, and unescape them when compiling in the code generation phase.

Ex.

html
  head
    script
      function sample_function() {
        console.log("Escape the braces please!");
      }

The braces in the script do not signify indentation, and should be escaped to avoid errors when being parsed by the context free grammar.

Inline attributes

section(class "test")

should become:

<section class="test"></section>

Convert rspec test suites over to CatchC++ test suites

Custom components proposal

You could define a component in a separate file sort of like this:

define person with name, email, photo
  section.person
    h1
      given email
        a(href mailto:#{email}) #{name}
      unless email
        span #{name}
    img(src #{photo})

And then you can use it like this:

each users as user
  person(
    name #{user.name}
    email #{user.email}
    photo #{user.photo_url}
  )

We should probably make a gem or something to handle importing these.

Thoughts on syntax, etc? How do we differentiate between passing regular string attributes versus passing template hashes? (do we even want to support template hash parameters?)

Use negative lookahead regex in ruby scaffolding script over naive approach I implemented with string matching.

For the methods calling the FileHelper::update_file method.

Test escaping for attributes

We need to make sure that:

h1 Test (
  class "something_with_a_quote_\""
)

should become:

<h1 class="something_with_a_quote_&quot;">Test</h1>

...but, here's the weird thing. If we're doing a code block:

button Click me (
  onClick =>
    alert("hello");
)

that should actually become:

<button onClick="alert(&quot;hello&quot;)">Click me</button>

I didn't think that was valid but thats actually what is supposed to be done, it turns out, so we SHOULDN'T be using ~> for script attributes (script tags are another story.)

I think it's still a good idea to keep ~> in case you want to inline some html instead of emerald, but we should discourage using it for script attributes. We also need to investigate if any special escaping has to be done for script tag contents or if we an still use => there.

Expose a ruby interface for conversion as well as the CLI

Make a way to have templated, non-escaped literals

e.g. something like

each people as person
  button(
    onClick ->>
      alert("Hi, I'm |name|")
  )

Maybe we get rid of ~>, and adding a double-head to an arrow makes it free of html escaping or something? Adding yet another arrow type might get confusing

Fix `emerald_tests.cpp` and other tests reporting errors.

Better testing for CircleCI builds.

Currently, we just have tests for the preprocessor, and the parser - but it would be awesome to have end-to-end tests which test the preprocessor, parser, and code generator, so we can validate the Emerald code we pass in generates the html we're expecting.

Import feature for modular emerald.

section.emr

section
  h1 This is some modular html.

main.emr

body
  import section
  import section

=>

body
  section
    h1 This is some modular html
  section
    h1 This is some modular html

Generalize tags, make all strings use text_content

Right now only certain tags allow having a string following it (heading tags.) Technically, we should be allowed to add text content in any tag in the grammar, and we can optionally do semantics checking after parsing (e.g. if you add text content in an image tag or something.) Same for nesting. I think a good way to do this is to make a tag generic in the grammar and move the specific tag types into a stage after the grammar.

Also, in doing this, we should make all strings use the text_content grammar node so that any form of text can have variable templating.

Clean up grammar

• Make rule names longer
• Add comments to rules in the grammar
• See if it's possible to make rules take up more than one line in the grammar, maybe by doing our own preprocessing
• Make to_html be const
• Use const Json
• Make a readme documenting the things we've learned for using peglib (e.g. named tokens can't be used in our case, ~ ignores the token)