Layout = ref object
  elements: seq[LayoutElement]

LytBlock = ref object
  layoutCache: Table[Option[LytSolution], Option[LytSolution]]
  isBreaking* {.requiresinit.}: bool ## Whether or not this block should end the line
  breakMult* {.requiresinit.}: int ## Local line break cost change
  minWidth* {.requiresinit.}: int
  hasInnerChoice*: bool
  id {.requiresinit.}: int
  case kind*: LytBlockKind
  of bkVerb:
      textLines*: seq[LytStr] ## Multiple lines of text
      firstNl*: bool         ## Insert newline at the block start
    
  of bkText:
      text*: LytStr          ## A single line of text, free of carriage
                             ## returs etc.
    
  of bkWrap:
      prefix*: Option[string]
      sep*: string           ## Separator for block wraps
      wrapElements*: seq[LytBlock]

  of bkStack, bkChoice, bkLine:
      elements*: seq[LytBlock]

  of bkEmpty:
      nil

  

LytBlockKind = enum
  bkText,                   ## Single line text block
  bkLine,                   ## Horizontally stacked lines
  bkChoice,                 ## Several alternating layouts
  bkStack,                  ## Vertically stacked layouts
  bkWrap,                   ## Mulitple blocks wrapped to create lowerst-cost layout
  bkVerb,                   ## Multiple lines verbatim
  bkEmpty                    ## Empty layout block - ignored by `add` etc.

LytBuilderKind = enum
  blkLine, blkStack, blkText, blkIndent, blkSpace, blkChoice, blkEmpty, blkWrap

LytOptions = object
  leftMargin*: int           ## position of the first right margin. Expected `0`
  rightMargin*: int          ## position of the second right margin. Set for `80`
                             ## to wrap on default column limit.
  leftMarginCost*: float     ## cost (per character) beyond margin 0.
                             ## Expected value `~0.05`
  rightMarginCost*: float    ## cost (per character) beyond margin 1. Should
                             ## be much higher than `c0`. Expected value
                             ## `~100`
  linebreakCost*: int        ## cost per line-break
  indentSpaces*: int         ## spaces per indent
  cpack*: float              ## cost (per element) for packing justified layouts.
                             ## Expected value `~0.001`
  format_policy*: LytFormatPolicy

LytSolution = ref object
  id {.requiresinit.}: int ## A Solution object effectively maps an integer (the left margin at
                           ## 
                           ## which the solution is placed) to a layout notionally optimal for
                           ## 
                           ## that margin, together with cost information used to evaluate the
                           ## 
                           ## layout. For compactness, the map takes the form of a
                           ## 
                           ## piecewise-linear cost function, with associated layouts.
  knots: seq[int] ## a list of ints, specifying the margin settings at
                  ## which the layout changes. Note that the first knot is required to be
                  ## 
                  ## 0.
  spans: seq[int]            ## a list of ints, giving for each knot, the width of
                             ## 
                             ## the corresponding layout in characters.
  intercepts: seq[float]     ## constant cost associated with each knot.
  gradients: seq[float]      ## at each knot, the rate with which the layout
                             ## cost increases with an additional margin
                             ## indent of 1 character.
  layouts*: seq[Layout]      ## the Layout objects expressing the optimal
                             ## layout between each knot.
  index: int

LytStr = object
  text*: ColoredText

OutConsole = object
  leftMargin: int
  rightMargin: int
  hPos: int
  margins: seq[int]
  outStr: ColoredText

defaultFormatOpts = (leftMargin: 0, rightMargin: 80, leftMarginCost: 0.05,
                     rightMarginCost: 100.0, linebreakCost: 5, indentSpaces: 2,
                     cpack: 0.001,
                     format_policy: (breakElementLines: (:anonymous, nil)))

proc `$`(blc: LytBlock): string {....raises: [ValueError], tags: [].}

proc `$`(le: LayoutElement): string {....raises: [ValueError], tags: [].}

proc `$`(lt: Layout): string {....raises: [ValueError], tags: [].}

proc `$`(sln: LytSolution): string {....raises: [ValueError], tags: [].}

proc `$`(sln: Option[LytSolution]): string {....raises: [ValueError], tags: [].}

func `&?`(bl: LytBlock; added: tuple[condOk: bool, bl: LytBlock]): LytBlock {.
    ...raises: [], tags: [].}

func `??`(bl: LytBlock; condOk: bool): LytBlock {....raises: [], tags: [].}

func `??`(blocks: tuple[ok, fail: LytBlock]; condOk: bool): LytBlock {.
    ...raises: [], tags: [].}

proc `[]`(b: static[LytBuilderKind]; a: string | ColoredString | ColoredLine |
    seq[ColoredLine] |
    ColoredText; breaking: bool = false): LytBlock

proc `[]`(b: static[LytBuilderKind]; bl: LytBlock; args: varargs[LytBlock]): LytBlock

proc `[]`(b: static[LytBuilderKind]; i: int; bl: LytBlock): LytBlock

proc `[]`(b: static[LytBuilderKind]; s: seq[LytBlock]; sep: string = ", "): LytBlock

proc `[]`(b: static[LytBuilderKind]; tlen: int = 1): LytBlock

func `[]`(blc: LytBlock; idx: int): LytBlock {....raises: [], tags: [].}

func `[]`(blc: var LytBlock; idx: int): var LytBlock {....raises: [], tags: [].}

func add(target: var LytBlock; other: varargs[LytBlock];
         compact: bool = defaultCompact) {....raises: [], tags: [].}

func codegenRepr(inBl: LytBlock; indent: int = 0): string {.
    ...raises: [ValueError], tags: [].}

func condOr(cond: bool; ok: LytBlock; fail: LytBlock = makeEmptyBlock()): LytBlock {.
    ...raises: [], tags: [].}

func convertBlock(bk: LytBlock; newKind: LytBlockKind): LytBlock {....raises: [],
    tags: [].}

proc debugOn(self: Layout; buf: var string): void {....raises: [ValueError],
    tags: [].}

proc doOptLayout(self: var LytBlock; rest: var Option[LytSolution];
                 opts: LytOptions): Option[LytSolution] {.
    ...raises: [ValueError, Exception, KeyError], tags: [RootEffect].}

func filterEmpty(blocks: openArray[LytBlock]): seq[LytBlock] {....raises: [],
    tags: [].}

func flatten(bl: LytBlock; kind: set[LytBlockKind]): LytBlock {....raises: [],
    tags: [].}

func isEmpty(bl: LytBlock): bool {.inline, ...raises: [], tags: [].}

func join(blocks: LytBlock; sep: LytBlock; vertLines: bool = true): LytBlock {.
    ...raises: [NilArgumentError], tags: [].}

func join(blocks: seq[LytBlock]; sep: LytBlock; direction: LytBlockKind): LytBlock {.
    ...raises: [], tags: [].}

func len(blc: LytBlock): int {....raises: [], tags: [].}

func len(s: LytStr): int {....raises: [], tags: [].}

proc makeAlignedGrid(blocks: seq[seq[LytBlock]];
                     aligns: openArray[StringAlignDirection]): LytBlock {.
    ...raises: [ArgumentError, NilArgumentError], tags: [].}

proc makeAlignedGrid(blocks: seq[seq[LytBlock]]; aligns: openArray[
    tuple[leftPad, rightPad: int, direction: StringAlignDirection]]): LytBlock {.
    ...raises: [ArgumentError, NilArgumentError], tags: [].}

func makeBlock(kind: LytBlockKind; breakMult: int = 1): LytBlock {....raises: [],
    tags: [].}

func makeChoiceBlock(elems: openArray[LytBlock]; breakMult: int = 1;
                     compact: bool = defaultCompact): LytBlock {....raises: [],
    tags: [].}

func makeEmptyBlock(): LytBlock {....raises: [], tags: [].}

func makeForceLinebreak(text: string = ""): LytBlock {....raises: [], tags: [].}

func makeIndentBlock(blc: LytBlock; indent: int; breakMult: int = 1): LytBlock {.
    ...raises: [NilArgumentError], tags: [].}

func makeLineBlock(elems: openArray[LytBlock]; breakMult: int = 1;
                   compact: bool = defaultCompact): LytBlock {.
    ...raises: [NilArgumentError], tags: [].}

func makeLineCommentBlock(text: string; prefix: string = "# "): LytBlock {.
    ...raises: [], tags: [].}

proc makeStackBlock(elems: openArray[LytBlock]; breakMult: int = 1;
                    compact: bool = defaultCompact): LytBlock {....raises: [],
    tags: [].}

func makeTextBlock(text: ColoredString | ColoredLine | ColoredRuneLine | string;
                   breakMult: int = 1; breaking: bool = false): LytBlock

func makeTextBlock(text: string; breakMult: int = 1): LytBlock {....raises: [],
    tags: [].}

proc makeTextBlocks(text: openArray[string]): seq[LytBlock] {....raises: [],
    tags: [].}

func makeTextOrStackTextBlock(text: string | ColoredString | ColoredLine |
    seq[ColoredLine] |
    ColoredText; breaking: bool = false; firstNl: bool = false;
                              breakMult: int = 1): LytBlock

func makeVerbBlock[S: string | ColoredString | ColoredLine | ColoredRuneLine](
    textLines: openArray[S]; breaking: bool = true; firstNl: bool = false;
    breakMult: int = 1): LytBlock

func makeWrapBlock(elems: openArray[LytBlock]; breakMult: int = 1;
                   sep: string = ", "): LytBlock {....raises: [], tags: [].}

proc printOn(self: Layout; buf: var OutConsole) {....raises: [], tags: [].}

func pyCodegenRepr(inBl: LytBlock; indent: int = 0; nimpref: string = "";
                   prelude: bool = false; colortext: bool = false;
                   colored: bool = false; makeTextOrVerb: bool = false): string {.
    ...raises: [ImplementError, ValueError], tags: [].}

func textLen(b: LytBlock): int {....raises: [], tags: [].}

proc toLayouts(bl: LytBlock; opts: LytOptions = defaultFormatOpts): seq[Layout] {....raises: [
    ArgumentError, ValueError, Exception, KeyError, NoneArgumentError],
    tags: [RootEffect].}

proc toString(bl: LytBlock; rightMargin: int = 80;
              opts: LytOptions = defaultFormatOpts): ColoredText {....raises: [
    ArgumentError, ValueError, Exception, KeyError, NoneArgumentError],
    tags: [RootEffect].}

func treeRepr(inBl: LytBlock): string {....raises: [ValueError], tags: [].}

proc treeRepr(self: Layout; level: int = 0): ColoredText {.
    ...raises: [ValueError, Exception], tags: [RootEffect].}

proc treeRepr(self: LytSolution; level: int = 0): ColoredText {.
    ...raises: [ValueError, Exception], tags: [RootEffect].}

proc write(stream: Stream | File; self: Layout; indent: int = 0)

iterator items(blc: LytBlock): LytBlock {....raises: [], tags: [].}

iterator mitems(blc: var LytBlock): var LytBlock {....raises: [], tags: [].}

iterator mpairs(blc: var LytBlock): (int, var LytBlock) {....raises: [], tags: [].}

iterator pairs(blc: LytBlock): (int, LytBlock) {....raises: [], tags: [].}

template addItBlock(res: LytBlock; item: typed; expr: untyped; join: LytBlock): untyped

template findSingle(elems: typed; targetKind: typed): untyped

template initBlockFmtDSL() {.dirty.}

template joinItBlock(direction: LytBlockKind; item: typed; expr: untyped;
                     join: LytBlock): untyped

template joinItLine(item: typed; expr: untyped; join: LytBlock): untyped