pencere

Start

The pencere command makes, runs and packs an app. It installs with one line, on macOS and Linux.

  1. Install the command

    curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | sh

    It puts the newest release of the command in ~/.local/bin (no sudo) after checking the file against the SHA256SUMS of that release, and tells you if the directory is not on your PATH.

    To see a view you need a terminal that hosts pencere: bateri is the first.

  2. Make a project

    pencere new hello
    cd hello
    hello/
      src/
        program/
          app.lua
        view/
          page.lua
        assets/
          icon.svg
      test/
        page_test.lua
      README.md
      .gitignore

    src/program/ is the program (app.lua and the modules it requires), src/view/ the page it shows (page.lua), src/assets/ the pictures the page and the program name as assets/….

  3. Run it

    pencere dev

    pencere dev runs it in this pane and runs it again when a file under src/ changes. print goes to .pencere/log, since the terminal is under the view.

  4. 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)
  5. 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.

  6. Test it

    pencere test
    test/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 test runs the tests in test/ (*_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/.

  7. Build one file

    pencere build
    pencere build --target x86_64-unknown-linux-musl
    pencere build --no-terminal

    Nothing generated is under src/: pencere build makes one executable, dist/hello, of the app. Give it to anyone with the same kind of machine; pencere build --target x86_64-unknown-linux-musl makes 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