137 lines
5.4 KiB
Lua
137 lines
5.4 KiB
Lua
---@meta
|
|
|
|
---A pretty printer for formatting text in a stylized manner.
|
|
---
|
|
---Printing uses document objects to structure the text. These documents will be
|
|
---used to print the most compact layout possible
|
|
---
|
|
---Based on [*A Prettier Printer*](https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf)
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html)
|
|
local pretty = {}
|
|
|
|
---A document contains formatted text with multiple possible layouts.
|
|
---@class ccTweaked.cc.pretty.Doc
|
|
|
|
---An empty document
|
|
---@type ccTweaked.cc.pretty.Doc
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:empty)
|
|
pretty.empty = nil
|
|
|
|
---A document with a single space in it
|
|
---@type ccTweaked.cc.pretty.Doc
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:space)
|
|
pretty.space = nil
|
|
|
|
---A line break, however when in a group and everything can fit on one line, is
|
|
---replaced with `empty`
|
|
---@type ccTweaked.cc.pretty.Doc
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:line)
|
|
pretty.line = nil
|
|
|
|
---A line break, however when in a group and everything can fit on one line, is
|
|
---replaced with `space`
|
|
---@type ccTweaked.cc.pretty.Doc
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:space_line)
|
|
pretty.space_line = nil
|
|
|
|
---Create a new `Doc` from a string
|
|
---@param text string The string to construct a document from
|
|
---@param color? ccTweaked.colors.color The color to print the text in. Defaults to the current color
|
|
---@return ccTweaked.cc.pretty.Doc doc The document containing the provided text
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:text)
|
|
function pretty.text(text, color) end
|
|
|
|
---Concatenate multiple documents into one
|
|
---@param ... ccTweaked.cc.pretty.Doc|string The documents to concat
|
|
---@return ccTweaked.cc.pretty.Doc doc The concatenated document
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:concat)
|
|
function pretty.concat(...) end
|
|
|
|
---Indents the following lines in the provided document using spaces
|
|
---@param depth integer The number of spaces to indent to
|
|
---@param doc ccTweaked.cc.pretty.Doc The document to indent
|
|
---@return ccTweaked.cc.pretty.Doc doc The nested document
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:nest)
|
|
function pretty.nest(depth, doc) end
|
|
|
|
---Build a document that is displayed on a single line if there is enough room
|
|
---or as normal if not
|
|
---@param doc ccTweaked.cc.pretty.Doc The document to make a group
|
|
---@return ccTweaked.cc.pretty.Doc doc The grouped document
|
|
---## Example
|
|
---```
|
|
---local pretty = require("cc.pretty")
|
|
---
|
|
---pretty.print(
|
|
--- pretty.group(
|
|
--- pretty.concat("Hello", pretty.space_line, "World!")
|
|
--- )
|
|
---)
|
|
---```
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:group)
|
|
function pretty.group(doc) end
|
|
|
|
---Write a doc to the terminal
|
|
---@param doc ccTweaked.cc.pretty.Doc The document to write
|
|
---@param maxWidth? number The maximum fraction of the screen width that can be written to before wrapping. Defaults to 0.6
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:write)
|
|
function pretty.write(doc, maxWidth) end
|
|
|
|
---Print a doc to the terminal with a trailing new line
|
|
---@param doc ccTweaked.cc.pretty.Doc The document to write
|
|
---@param maxWidth? number The maximum fraction of the screen width that can be written to before wrapping. Defaults to 0.6
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:print)
|
|
function pretty.print(doc, maxWidth) end
|
|
|
|
---Render a document into a string
|
|
---@param doc ccTweaked.cc.pretty.Doc The document to render
|
|
---@param width? number The maximum width of this document. Long strings will not be wrapped to fit this width, it is just used for finding the best layout
|
|
---@param maxWidth? number The maximum fraction of the screen width that can be written to before wrapping. Defaults to 0.6
|
|
---@return string rendered The rendered string
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:render)
|
|
function pretty.render(doc, width, maxWidth) end
|
|
|
|
---@class prettyOptions
|
|
---@field function_args boolean Show the arguments to a function if known, defaults to false
|
|
---@field function_source boolean Show where a function was defined, defaults to false
|
|
|
|
---Convert an object into a document that can then be displayed with `write` or `print`
|
|
---@param obj any The object to convert to a document
|
|
---@param options? prettyOptions Options for how certain things are displayed
|
|
---@return ccTweaked.cc.pretty.Doc doc The formatted document
|
|
---## Example
|
|
---```
|
|
---local pretty = require "cc.pretty"
|
|
---pretty.print(pretty.pretty({ 1, 2, 3 }))
|
|
---```
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:pretty)
|
|
function pretty.pretty(obj, options) end
|
|
|
|
---A shorthand that calls `pretty` and `print`
|
|
---@param obj any The object to print
|
|
---@param options? prettyOptions Options for how certain things are displayed
|
|
---@param maxWidth? number The maximum fraction of the screen width that can be written to before wrapping. Defaults to 0.6
|
|
---## Example
|
|
---```
|
|
---local pretty = require "cc.pretty"
|
|
---pretty.pretty_print({ 1, 2, 3 })
|
|
---```
|
|
------
|
|
---[Official Documentation](https://tweaked.cc/library/cc.pretty.html#v:pretty_print)
|
|
function pretty.pretty_print(obj, options, maxWidth) end
|
|
|
|
return pretty
|