SegmentedApps.md

Segmented Scarpe Apps

A segmented app has multiple code parts. One is your Shoes app. But others can be different. For instance:

      ---
      author: Noah
      ----- app_code
        Shoes.app do
          button "clicky"
        end
      ----- test code
        require "scarpe/cats_cradle"
        self.class.include Scarpe::Test::CatsCradle
        event_init

        on_heartbeat do
          assert_include button().text, "clicky"

          test_finished
        end

Here's a simple segmented app that creates an application, loads the CatsCradle test harness and runs tests. It has two "formal" parts -- the app and the test code -- and a "front matter" section at the start, similar to a page or blog post in Jekyll (GitHub Pages format) or most other static site generators.

The front matter section can include arbitrary YAML data. The code sections are separated by lines with a minimum of five dashes, followed by a name of your choice (or not) and then a newline.

You have to name the file with a ".scas" (Scarpe Segmented) extension. But both exe/scarpe and the Scarpe Webview test harness know how to load segmented apps properly.

The simplest .scas app is just a Shoes app with a different extension. That's perfectly legal, provided you don't have a line starting with five or more dashes (which counts as a new code segment.) If your file starts with three dashes and a newline, Scarpe will assume that there is front matter until the first line of five or more dashes, and parse that part of the file as YAML front matter.

Multiple Sections of Code

If you have a single code segment, with or without front matter, Scarpe assumes that it's a Shoes app.

If you have two sections, Scarpe assumes one is a Shoes app and the other is test code.

It's possible to customise how different code segments are treated by setting fields in the front matter.

Why Front Matter?

Front matter lets you choose the type of each code section, which lets you pick a loader -- for instance, whether that code section sets an environment variable, runs test code, specifies data or something else. Normally that's done by the display service, so the choices of section types are quite limited right now (August 2023.)