~/bend-docscommunity

src/init/plan.bend checks

raw source on the hub · import 0x886223f5c47e4983fe57d887c034bc7f/src/init/plan.bend as Plan

init/plan: ez init as a pure planner. It asks nothing: its World is the name, entry and description asked for and four texts, each None when the file is not there: ez.toml, .gitignore, the entry file and src/lib.bend. The interpreter (init/run.bend) reads them, calls plan, and runs what it returns.

ez init starts a project and never writes over one. A ledger that is already there, whatever it holds, is refused with no effect at all, so its dependencies, tools and bin survive a second ez init. Otherwise the plan writes, in order: a new ledger naming the package and its entry; the ignore rules for what ez generates, added to .gitignore when it lacks them; src/lib.bend, when the stub below is written at the project's top and nothing is there yet; and a stub entry when there is none.

The layout is cargo's: the program at the top and a library under src/ that it imports, so the directory git would not keep empty holds a file. The stub opens with # <name>: <description>, since the hub describes a package by the first line of its first file by path (pub/blurb.bend), and the entry comes before anything under src/.

The Effect, Plan and Outcome types are the lock's (lock/plan.bend), which the add design moves to a shared plan/plan.bend later; see "Update (A1, A4)" in docs/rfc/ez-add-planner.md.

5 imports
import Base
import ../lock/plan.bend as P
import ../ledger/manifest.bend as M
import ../ledger/render.bend as Rend
import ../pub/blurb.bend as B

Types

type World source · line 33 · raw

Data

what ez init reads: the name, entry file and description asked for ("" for none), and the texts of ez.toml, .gitignore, the entry file and src/lib.bend, None when absent

Definitions

def toml source · line 38 · raw

String

the ledger's path, which is fixed

def ignore.file source · line 42 · raw

String

where the ignore rules go

def lib.file source · line 46 · raw

String

where the library a new project starts with goes

def name.or source · line 50 · raw

@+at:String -> String

the name a new ledger takes: what was asked for, or app

def entry.or source · line 54 · raw

@+file:String -> String

the entry a new ledger names: what was asked for, or main.bend

def rules source · line 69 · raw

@+name:String -> List<&2, String>

everything ez writes into a project that is not the project's: the vendored packages, the test gate's shadow and its cache all live under one .ez/, and ez build drops a binary in bin/<name>.out (build.named in ez/start.bend) unless it is told otherwise. A project whose first ez check leaves untracked output is a project whose owner has to work out for themselves which of it was theirs.

.ez/ is ignored as its contents rather than as a directory, and .ez/lib is let back in only to have its contents ignored again. That is what lets a !.ez/lib/<hash> line keep a vendored tree: git cannot re-include a file under a directory it has excluded, so under a bare .ez/ every such line would be inert.

def stated.step source · line 77 · raw

@here:Bool -> @rest:(@_:Unit -> Bool) -> Bool

one step of a scan that is looking for one hit, with the head's answer in hand. Bool.or is an ordinary function and reduces both of its sides, so a scan written with it reads the whole list even when the first line answers. The rest of the scan arrives as a thunk and only the arm that wants it applies it.

def stated source · line 86 · raw

@ls:List<&2, String> -> @+rule:String -> Bool

whether a file already states this rule, on a line of its own. A rule buried in a longer line is not the rule, so the comparison is against whole lines.

def missing source · line 94 · raw

@rs:List<&2, String> -> @+ls:List<&2, String> -> List<&2, String>

the rules a file does not already state, in order

def tail source · line 105 · raw

@+text:String -> String

a file's text with a newline on the end, so what is appended to it starts on a line of its own. An empty file gets none, or the append would open with a blank line.

def ignored source · line 111 · raw

@+text:String -> @ms:List<&2, String> -> String

the ignore file with the rules it lacks added under a line saying whose they are. What is already there is kept: the file is the project's, not ez's.

def body source · line 123 · raw

@lays:Bool -> String

the rest of a new entry: a program that checks and runs, saying what the library it was laid out with gives it, or hello when there is none

def stub source · line 131 · raw

@+name:String -> @+desc:String -> @lays:Bool -> String

the entry of a new project: its line for the hub, then the program

def lib source · line 135 · raw

String

the library a new project starts with, which its entry imports

def text.of source · line 139 · raw

@got:Maybe<&2, String> -> String

a file's text, "" when it is not there

def ignore.put source · line 149 · raw

@ms:List<&2, String> -> @+text:String -> @rest:List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect> -> List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect>

.gitignore written ahead of the rest when it lacks a rule. Nothing to add means nothing written, so an ez init in a directory whose ignore file already has the rules leaves it exactly as it found it.

def due source · line 159 · raw

@got:Maybe<&2, String> -> @+at:String -> Bool

whether the stub is written: nothing is at the entry, so ez init does not overwrite the program, and the entry is not ez.toml or .gitignore, so the stub is not written over the file this plan just wrote there

def lays source · line 170 · raw

@got:Maybe<&2, String> -> @due:Bool -> @+at:String -> Bool

whether src/lib.bend is laid out with the stub: nothing is there yet, so a library already there is never written over, the stub is written, and it sits at the project's top, where its ./src/lib.bend import finds it. An entry in a directory of its own gets the stub alone.

def main.put source · line 178 · raw

@due:Bool -> @+at:String -> @+text:String -> @rest:List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect> -> List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect>

the stub at the entry when it is due, ahead of the rest

def lib.put source · line 186 · raw

@lays:Bool -> @rest:List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect> -> List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect>

the library when it is laid out, ahead of the rest

def files source · line 195 · raw

@+name:String -> @+at:String -> @+desc:String -> @main:Maybe<&2, String> -> @lib:Maybe<&2, String> -> List<&2, 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Effect>

the files written after the ledger and the ignore rules: the library and the stub, each when it is due

def model source · line 208 · raw

@+name:String -> @+at:String -> 0x886223f5c47e4983fe57d887c034bc7f/src/ledger/manifest.Manifest

the ledger a new project starts from: this package, its entry, and nothing else, so no publish-as or version and a project that publishes by hash

def fresh source · line 212 · raw

@+name:String -> @+at:String -> String

its text

def fits source · line 218 · raw

@+name:String -> @+at:String -> @+desc:String -> Bool

whether a new project can be written: its ledger reads back (EZ-LED-4), and the line its entry opens with is one line, so the description cannot spill into the program

def why.unfit source · line 222 · raw

@+name:String -> @+at:String -> String

why a new project that does not fit is refused

def plan.new source · line 230 · raw

@ok:Bool -> @+name:String -> @+at:String -> @+desc:String -> @ignore:Maybe<&2, String> -> @main:Maybe<&2, String> -> @lib:Maybe<&2, String> -> 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Plan

the new project's files, once it fits. A name or entry the ledger cannot carry, such as one holding a quote, or a description holding a newline, is refused with no effect at all.

def plan.go source · line 251 · raw

@led:Maybe<&2, String> -> @+name:String -> @+at:String -> @+desc:String -> @ignore:Maybe<&2, String> -> @main:Maybe<&2, String> -> @lib:Maybe<&2, String> -> 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Plan

the plan, once the name and entry are settled. A ledger on disk holds dependencies, tools and a bin that a fresh one would lose, so ez init writes over none of it, whatever the file holds, and refuses.

def plan source · line 268 · raw

@world:World -> 0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Plan

ez init over a World

def refuses.plan source · line 273 · raw

@pl:0x886223f5c47e4983fe57d887c034bc7f/src/lock/plan.Plan -> Bool

whether a plan ends in a refusal

def refuses source · line 282 · raw

@world:World -> Bool

whether ez init refuses on a World