From 06d4d5e065a6e3127b64b26245af23bcf21927b0 Mon Sep 17 00:00:00 2001 From: Erik Pettis Date: Thu, 15 Oct 2015 01:34:46 -0400 Subject: [PATCH] write readme.md --- init.lua | 4 +- integration_spec.lua | 41 ---------------- readme.md | 113 ++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 113 insertions(+), 45 deletions(-) delete mode 100644 integration_spec.lua diff --git a/init.lua b/init.lua index 84b47cb..6bd4502 100644 --- a/init.lua +++ b/init.lua @@ -11,10 +11,10 @@ local text = require "text" --- Table cells exposes the module interface. -- @table cells local cells = { - --- See @{column} + --- See @{column}, @{boxer} column = boxer(column), - --- See @{row} + --- See @{row}, @{boxer} row = boxer(row), --- See @{text}. diff --git a/integration_spec.lua b/integration_spec.lua deleted file mode 100644 index b251e47..0000000 --- a/integration_spec.lua +++ /dev/null @@ -1,41 +0,0 @@ -local cells = require "init" -local column = cells.column -local row = cells.row -local text = cells.text - -describe("example", function() - local page = column({ - column({ - text("hello from column 1").align("center"), - }), - column({ - text("hello from column 2"), - }).margin(" ").border("-"), - column({ - text("column 3").align("right"), - row({ - text("inner row").align("center"), - text(string.rep("this is some really long text that should definitely wrap ", 10)).align("center"), - text("some slightly shorter text that should probably still wrap").align("right"), - text("squeeze moar txt"), - text("teeeext!"), - row({ - column({ - text("text 1"), - text("text 4"), - }).border("1"), - text("text 2"), - text("text 3"), - }), - }).border("~"), - }), - row({ - text("fancy borders").align("right"), - }).margin("|").border("=").padding(" "), - }).border("*").padding(" ").width(103) - - print("") - for _, v in ipairs(page.render()) do - print(v) - end -end) diff --git a/readme.md b/readme.md index 0c315e8..93ca896 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,114 @@ # cells -A Lua module to format text in a grid. +A Lua module to format text in a grid. `cells` exposes constructors for `row`s, `column`s, and `text`s. By composing these three concepts, it's possible to express a wide variety of layouts. -Replacement for Papyros. +A `text` object accepts as input a string. That string can be returned wrapped to a certain width. In addition, the rendered string can be returned aligned either "left", "right", or "center". If an alignment is specified, the strings returned will be padded to conform to width expectations. + +A `row` arranges all inner content horizontally, whereas a `column` arranges all inner content vertically. Both `row`s and `column`s will grow horizontally until all inner content is rendered, but their widths can be specified. `row`s and `column`s accept as input a table of `text`s, `row`s, and `column`s. + +In addition, `row`s and `column`s can have single characters set as (from the outside-in) margin, border, and padding. + +# Example +Script: + +```lua +local cells = require "init" +local column = cells.column +local row = cells.row +local text = cells.text + +local lorem = "Lorem ipsum dolor sit amet, consectetur adipisicing elit. " .. + "Eligendi non quis exercitationem culpa nesciunt nihil aut nostrum " .. + "explicabo reprehenderit optio amet ab temporibus asperiores quasi " .. + "cupiditate. Voluptatum ducimus voluptates voluptas?" + +local page = column({ + column({ + text("cells").align("center"), + text("text formatting Lua module").align("center"), + }), + row({ + column({ + text("column header 1").align("center"), + column({ + text(lorem) + }).padding(" "), + }).border("."), + column({ + text("column header 2").align("center"), + column({ + text(lorem).align("right"), + text(lorem).align("right"), + }).padding(" "), + }).border("."), + }), + row({ + text(lorem), + text(lorem), + text(lorem), + text(lorem), + }).margin(" ").border(".").padding("="), +}).border("*").width(80) + +print("") +for _, v in ipairs(page.render()) do + print(v) +end +``` + +Outputs: + +``` +******************************************************************************** +* cells * +* text formatting Lua module * +*..............................................................................* +*. column header 1 .. column header 2 .* +*. .. .* +*. Lorem ipsum dolor sit amet, .. Lorem ipsum dolor sit amet, .* +*. consectetur adipisicing elit. .. consectetur adipisicing elit. .* +*. Eligendi non quis exercitationem .. Eligendi non quis exercitationem .* +*. culpa nesciunt nihil aut nostrum .. culpa nesciunt nihil aut nostrum .* +*. explicabo reprehenderit optio amet .. explicabo reprehenderit optio amet .* +*. ab temporibus asperiores quasi .. ab temporibus asperiores quasi .* +*. cupiditate. Voluptatum ducimus .. cupiditate. Voluptatum ducimus .* +*. voluptates voluptas? .. voluptates voluptas? .* +*. .. Lorem ipsum dolor sit amet, .* +*........................................ consectetur adipisicing elit. .* +* . Eligendi non quis exercitationem .* +* . culpa nesciunt nihil aut nostrum .* +* . explicabo reprehenderit optio amet .* +* . ab temporibus asperiores quasi .* +* . cupiditate. Voluptatum ducimus .* +* . voluptates voluptas? .* +* . .* +* .......................................* +* * +* ............................................................................ * +* .==========================================================================. * +* .=Lorem ipsum dolor Lorem ipsum dolor Lorem ipsum dolor Lorem ipsum dolor =. * +* .=sit amet, sit amet, sit amet, sit amet, =. * +* .=consectetur consectetur consectetur consectetur =. * +* .=adipisicing elit. adipisicing elit. adipisicing elit. adipisicing elit. =. * +* .=Eligendi non quis Eligendi non quis Eligendi non quis Eligendi non quis =. * +* .=exercitationem exercitationem exercitationem exercitationem =. * +* .=culpa nesciunt culpa nesciunt culpa nesciunt culpa nesciunt =. * +* .=nihil aut nostrum nihil aut nostrum nihil aut nostrum nihil aut nostrum =. * +* .=explicabo explicabo explicabo explicabo =. * +* .=reprehenderit reprehenderit reprehenderit reprehenderit =. * +* .=optio amet ab optio amet ab optio amet ab optio amet ab =. * +* .=temporibus temporibus temporibus temporibus =. * +* .=asperiores quasi asperiores quasi asperiores quasi asperiores quasi =. * +* .=cupiditate. cupiditate. cupiditate. cupiditate. =. * +* .=Voluptatum ducimusVoluptatum ducimusVoluptatum ducimusVoluptatum ducimus=. * +* .=voluptates voluptates voluptates voluptates =. * +* .=voluptas? voluptas? voluptas? voluptas? =. * +* .==========================================================================. * +* ............................................................................ * +* * +******************************************************************************** +``` + +# TODO +* Improve error messages, so they return more useful user information, like stack traces or user script line numbers. +* When setting `boxer` margin, border, and padding, width should be updated.