ADD more docs

This commit is contained in:
Nathan Dwarshuis 2023-09-27 22:55:13 -04:00
parent 98cc789d78
commit da5b4d3f2b
1 changed files with 155 additions and 22 deletions

View File

@ -1,3 +1,22 @@
{- Types to define a conky configuration.
Key terms:
- widget: the components of a module (dials, bars, plots, etc)
- module: a monitor for some aspect of the system to be displayed
- column: a vertical arrangement of modules
- panel: a horizontal arrangement of columns
- layout: a horizontal arrangement of panels
- geometry: the 'dimensions' of a widget
- pattern: the color/gradient to be used in widgets
NOTE: geometry is defined on a global level and at the module level. The global
level is defined in the theme type (see below) and applies to all widgets
equally. Some dimensions are not defined globally and are instead delegated to
each module to define themselves (these are not overrides so they must be
specified, although most modules have sensible defaults hardcoded)
See the 'fallback' config for an example of how to use these types.
-}
let Vector2 = \(a : Type) -> { x : a, y : a } let Vector2 = \(a : Type) -> { x : a, y : a }
let Point = Vector2 Natural let Point = Vector2 Natural
@ -262,6 +281,8 @@ let AllModules =
} }
let ModType = let ModType =
{- Wrapper type for each module
-}
< filesystem : FileSystem.Type < filesystem : FileSystem.Type
| graphics : Graphics.Type | graphics : Graphics.Type
| memory : Memory.Type | memory : Memory.Type
@ -273,21 +294,61 @@ let ModType =
| system : System.Type | system : System.Type
> >
let Annotated = \(a : Type) -> { type : Text, data : a } let Annotated =
{- Helper to ensure yaml is formatted in a parsable manner for union types
let Block = < Pad : Natural | Mod : Annotated ModType > The intent is to make a block like:
let Column_ = { blocks : List Block, width : Natural } parent:
type: <constructor_name>
data: <stuff_in_the_union_type>
-}
\(a : Type) -> { type : Text, data : a }
let Column = < CPad : Natural | CCol : Column_ > let Block =
{- Either vertical padding or a module -}
< Pad : Natural | Mod : Annotated ModType >
let Panel_ = { columns : List Column, margins : Margin } let Column_ =
{- A column of modules to display
let Panel = < PPad : Natural | PPanel : Panel_ > blocks: a list of blocks (either padding or a module)
width: the width of the column (and consequently everything in said column)
-}
{ blocks : List Block, width : Natural }
let Layout = { anchor : Point, panels : List Panel } let Column =
{- Either a column with modules or padding between columns -}
< CPad : Natural | CCol : Column_ >
let Panel_ =
{- A panel definition.
columns: a list of columns to show (must be at least one)
margins: space between the panel border and the columns
-}
{ columns : List Column, margins : Margin }
let Panel =
{- Wrapper type for either a panel or horizontal padding between panels -}
< PPad : Natural | PPanel : Panel_ >
let Layout =
{- The layout of the display
'anchor' is the coordinate of the upper-left corner, and 'panels' contains
the specifications of each panel (ie modules to show).
-}
{ anchor : Point, panels : List Panel }
let Sizes = let Sizes =
{- The font sizes to use for various widgets
plot_label: the text above the plot
table: the text in a table (headers and rows)
header: the text of each module header
normal: all other text (excluding plot axes)
-}
{ Type = { Type =
{ normal : Natural { normal : Natural
, plot_label : Natural , plot_label : Natural
@ -298,16 +359,29 @@ let Sizes =
} }
let Font = let Font =
{- A complete font specification -}
{ Type = { family : Text, sizes : Sizes.Type } { Type = { family : Text, sizes : Sizes.Type }
, default = { family = "Neuropolitical", sizes = Sizes::{=} } , default = { family = "Neuropolitical", sizes = Sizes::{=} }
} }
let PlotGeometry = let PlotGeometry =
{- Global dimensions for a plot
seconds: number of seconds to display on the x axis
ticks_x: the number of ticks to display on the x axis
-}
{ Type = { seconds : Natural, ticks_x : Natural } { Type = { seconds : Natural, ticks_x : Natural }
, default = { seconds = 90, ticks_x = 9 } , default = { seconds = 90, ticks_x = 9 }
} }
let TableGeometry = let TableGeometry =
{- Global dimensions for a table
name_chars: the max number of characters a cell can have before being truncated
padding: the margins between the border and the interior text
header_padding: the distance between the header and the first row of text
row_spacing: the distance between each row
-}
{ Type = { Type =
{ name_chars : Natural { name_chars : Natural
, padding : Margin , padding : Margin
@ -323,11 +397,17 @@ let TableGeometry =
} }
let HeaderGeometry = let HeaderGeometry =
{- Global dimensions for the header of a module
underline_offset: distance between bottom edge of text and the line below
padding: the distance between the underline and the first widget in the module
-}
{ Type = { underline_offset : Natural, padding : Natural } { Type = { underline_offset : Natural, padding : Natural }
, default = { underline_offset = 26, padding = 19 } , default = { underline_offset = 26, padding = 19 }
} }
let Geometry = let Geometry =
{- Global config for dimensions of various widgets -}
{ Type = { Type =
{ plot : PlotGeometry.Type { plot : PlotGeometry.Type
, table : TableGeometry.Type , table : TableGeometry.Type
@ -340,28 +420,72 @@ let Geometry =
} }
} }
let StopRGB = { color : Natural, stop : Double } let Color =
{- Alias for a solid color represented as a single hex number -}
Natural
let StopRGBA = { color : Natural, stop : Double, alpha : Double } let Alpha =
{- Alias for alpha channel as a fraction between 0 and 1 -}
Double
let ColorAlpha = { color : Natural, alpha : Double } let Stop =
{- Alias for the position of a color in a gradient (between 0 and 1) -}
Double
let StopRGB =
{- A solid color with a position in a gradiant -}
{ color : Color, stop : Stop }
let StopRGBA =
{- A transparent color with a position in a gradiant -}
{ color : Color, stop : Stop, alpha : Alpha }
let ColorAlpha =
{- A solid transparent color -}
{ color : Color, alpha : Alpha }
let Pattern = let Pattern =
< RGB : Natural {- Wrapper for different pattern types -}
< RGB : Color
| RGBA : ColorAlpha | RGBA : ColorAlpha
| GradientRGB : List StopRGB | GradientRGB : List StopRGB
| GradientRGBA : List StopRGBA | GradientRGBA : List StopRGBA
> >
let annotatePattern = let annotatePattern =
{- Helper function to ensure patterns are parsable in yaml
This will create entries in the yaml config like:
parent:
type: <pattern_type>
date:
<field1>: ...
<field2>: ...
-}
\(a : Pattern) -> \(a : Pattern) ->
{ type = showConstructor a, data = a } : Annotated Pattern { type = showConstructor a, data = a } : Annotated Pattern
let mod = \(a : ModType) -> Block.Mod { type = showConstructor a, data = a } let mod =
{- Helper function to ensure modules are parsable in yaml
This will create entries in the yaml config like:
parent:
type: <module name>
date:
<field1>: ...
<field2>: ...
-}
\(a : ModType) -> Block.Mod { type = showConstructor a, data = a }
let APattern = Annotated Pattern let APattern = Annotated Pattern
let symGradient = let symGradient =
{- Make a symmetric gradient between two colors.
c0 will be the color of either edge and c1 will be the color in the center
-}
\(c0 : Natural) -> \(c0 : Natural) ->
\(c1 : Natural) -> \(c1 : Natural) ->
annotatePattern annotatePattern
@ -373,6 +497,8 @@ let symGradient =
) )
let Patterns = let Patterns =
{- All patterns for a given theme
-}
{ Type = { Type =
{ header : APattern { header : APattern
, panel : { bg : APattern } , panel : { bg : APattern }
@ -445,19 +571,26 @@ let Theme =
{ font = Font::{=}, geometry = Geometry::{=}, patterns = Patterns::{=} } { font = Font::{=}, geometry = Geometry::{=}, patterns = Patterns::{=} }
} }
let Bootstrap = { update_interval : Natural, dimensions : Point } let Bootstrap =
{- Defines minimal options to start conky prior to calling any lua code.
-}
{ update_interval : Natural, dimensions : Point }
let Config = { bootstrap : Bootstrap, theme : Theme.Type, layout : Layout } let Config =
{- Global config type -}
{ bootstrap : Bootstrap, theme : Theme.Type, layout : Layout }
let toConfig = let toConfig =
\(i : Natural) -> {- Helper function to generate a config -}
\(x : Natural) -> \(update_interval : Natural) ->
\(y : Natural) -> \(width : Natural) ->
\(t : Theme.Type) -> \(height : Natural) ->
\(l : Layout) -> \(theme : Theme.Type) ->
{ bootstrap = { update_interval = i, dimensions = { x, y } } \(layout : Layout) ->
, theme = t { bootstrap =
, layout = l { update_interval, dimensions = { x = width, y = height } }
, theme
, layout
} }
: Config : Config