Start
The pencere command makes, runs and packs an app. It installs with one line, on macOS and Linux.
-
Install the command
curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | shIt puts the newest release of the command in
~/.local/bin(nosudo) after checking the file against theSHA256SUMSof that release, and tells you if the directory is not on yourPATH.To see a view you need a terminal that hosts pencere: bateri is the first.
-
Make a project
pencere new hello cd hellohello/ src/ program/ app.lua view/ page.lua assets/ icon.svg test/ page_test.lua README.md .gitignoresrc/program/is the program (app.luaand the modules it requires),src/view/the page it shows (page.lua),src/assets/the pictures the page and the program name asassets/…. -
Run it
pencere devpencere devruns it in this pane and runs it again when a file undersrc/changes.printgoes to.pencere/log, since the terminal is under the view. -
The program
src/program/app.lua-- hello: the program. It runs in the terminal pane and shows the view of src/view/ there: -- `serve` told no view shows what that directory has, here page.lua. Pictures are src/assets/, -- whose files the page and `icon =` name as "assets/…". `pencere dev` runs it and runs it again -- when a file changes; `pencere build` makes one file of it, dist/hello. local pencere = require("pencere") local time = pencere.time local outcome = pencere.serve { title = "hello", -- What the view asks for, once: a function that answers, or raises `{ code =, message = }`. calls = { hello = function(params) return { message = "Hello, " .. (params.name or "world") .. "!" } end, }, -- What the view listens to as it changes: the function starts feeding `sub`, and says how to stop. topics = { clock = function(_, sub) local timer = time.every(1, function() sub:push({ now = time.now() }) end) sub:on_end(function() timer:cancel() end) sub:push({ now = time.now() }) end, }, -- Where the page cannot be shown at all (no terminal, or the app was built with -- `pencere build --no-terminal`): say it in text. fallback = function() print("hello: this terminal shows no views, so here is the text.") print("Hello, world!") end, } -- After the view: ⌃C ends the app with the status a shell gives it. pencere.exit(outcome.status) -
The page
src/view/page.lua-- The view of hello: a page of the kit's page API, which the terminal draws in its own font and -- theme. It talks to app.lua with `pencere.call` (ask once) and `pencere.subscribe` (listen). local b = pencere local ui = b.Ui.new() local BUTTON = "greet" local greeting = "Press the button." local seconds = nil b.subscribe("clock", nil, function(value) seconds = math.floor(value.now) % 86400 return true end) local function greet() b.call("hello", { name = "pencere" }, function(result, err) greeting = err and ("It failed: " .. tostring(err.message or err.code)) or result.message return true end) end local function clock() if not seconds then return "…" end return string.format("%02d:%02d:%02d UTC", seconds // 3600, seconds // 60 % 60, seconds % 60) end return { render = function(size, now, reduce_motion) local hovered = ui.hover == BUTTON return b.div():size_full():items_center():justify_center():gap(14) :child(b.image("assets/icon.svg"):tint("accent"):size(48, 48)) :child(b.text(greeting):text_size(20)) :child(b.text(clock()):color("dim")) :child(b.div():press(BUTTON):px(14):py(8):rounded(8) :bg(hovered and "raised3" or "raised2") :child(b.text("Greet"))) end, handle = function(event) if event.type == "move" then return ui:point(b.layout, event) elseif event.type == "leave" then return ui:point(b.layout, nil) elseif event.type == "press" then ui:press(b.layout, event) elseif event.type == "release" then if ui:release(b.layout, event) == BUTTON then greet() return true end end end, }What a page is made of is in the elements, and what is ready to use on one in the components.
-
Test it
pencere testtest/page_test.lua-- Tests of hello. `pencere test` runs every *_test.lua file in this directory: the page of the app -- is opened under the host with no screen (the kit's own interpreter, laid out and scrolled as a -- terminal does it, with a clock the test moves), and the test does to it what a person does. local test = require("pencere.test") local expect = test.expect test("the button shows what the program answers", function() -- The program is a stand-in made of the calls the page makes: each is a function of its params. local page = test.open({ calls = { hello = function(params) return { message = "Hello, " .. params.name .. "!" } end, }, }) expect(page):to_say("Press the button.") page:get_by_role("button", { name = "Greet" }):click() expect(page):to_say("Hello, pencere!") expect(page):to_have_called("hello", { name = "pencere" }) end)pencere testruns the tests intest/(*_test.lua): each opens the page under a host with no screen and does to it what a person does, with a stand-in for the program or with the app's own (require("pencere.test")). What a failed test leaves is in.pencere/test/. -
Build one file
pencere build pencere build --target x86_64-unknown-linux-musl pencere build --no-terminalNothing generated is under
src/:pencere buildmakes one executable,dist/hello, of the app. Give it to anyone with the same kind of machine;pencere build --target x86_64-unknown-linux-muslmakes it for another.
In another language, or with a web page
pencere new hello --lang ts- the program in TypeScript (--lang rust: in Rust)
pencere new hello --page web- a web page for the view (a program in TypeScript has one unless --page lua)
The program is then written in TypeScript or in Rust, and the view is a web page.
Where to go from here
- ElementsWhat a page is made of, each with its picture and its code.
- ComponentsThe library's components, each with its picture and its code.
- The page APIEverything a page can do, in full.
- The programEverything a program in Lua has, and how an app is laid out.
- The commandEverything the command does, to the release of an app.
- ExamplesApps in the repository to read and to run.