Conix API Docs

ask :: Content -> Content

Prevent infinite recursion when using a value from the data store as content.

For example:

Will break with an infinite recursion error. To resolve this do:

[ { x = 3; }
  (ref data.x)
]

or (if you don’t like typing “ref”):

[ { x = 3; }
  (r data.x)
]

code :: Language -> Code -> Content

Create a markdown code block

conix.git.ref :: GitBranchString

The GIT branch of the conix repo currently being used

conix.git.rev :: GitCommitHashString

The GIT commit hash of conix repo currently used

conix.git.text :: NixString

String containing a Nix Attribute expression representing conix.git

conix.git.url :: URLString

The HTTP URL of the conix GIT repo

conix.homepageUrl :: URLString

The homepage URL of conix

conix.version.major :: Natural

The major version of the conix repo being used

conix.version.minor :: Natural

The minor version of the conix repo being used

conix.version.patch :: Natural

The patch version of the conix repo being used

conix.version.text :: SemanticVersionString

The semantic version of the conix repo being used.

It is formatted as: major.minor.patch

conixCss :: FileName -> Content -> Content

The css file conix uses for generating its documentation

css :: FilePath -> Content

When used with meta add the local css file to this html file’s includes

digraph :: ImageName -> DOTCode -> Content

Shorthand for: dotgraph imgName "digraph { ... }"

dir :: DirName -> Content -> Content

Nest the file heirarchy of the given content into the given directory

dotgraph :: ImageName -> DOTCode -> Content

Create an graph image from the given DOT code

eval :: Content -> { text :: String, drv :: Derivation, data :: AttrSet, refs :: AttrSet, exprs :: AttrSet }

Evaluate Content with just the conix library in scope

evalExtended :: Content -> Content -> { text :: String, drv :: Derivation, data :: AttrSet, refs :: AttrSet, exprs :: AttrSet }

Evaluate a Content with the conix library extended with the exprs defined in the first Content

expr :: HaskellTypeString -> Content -> a

Create a new API expression with a type, documentation, and a Nix value.

Traditionally Nix modules are just attribute sets with their values being API expressions (e.g a function). Documentation is left as comments and types don’t exist. expr abstracts over documentation, types, and the user defined function to make documentation first class in Nix.

file :: (Text -> Derivation) -> FileNameStr -> Content -> Content

Create a new file from the text produced by the given content

foldAttrsCond :: (a -> Bool) -> (a -> b) -> (AttrSet b -> b) -> AttrSet a -> b

Fold an attribute set down while allowing for attribute sets to be a leaf value.

The first function returns true if the given attribute set is a leaf value. The second function maps leaf values to final values. The third function returns a combined final value from the final values of the lower branches.

For example, to sum the leaf values in an attribute set where a leaf is either a nix value or attribute set containing “stop” as an attribute is:

countLeaves = foldAttrsCond 
  # An attribute set is a leaf if it contains "stop" as an attribute.
  (s: s ? stop) 
  # return the value 1 for each leaf. We don't need the actual value to compute the result.
  (_: 1)        
  # countMap is a flat attribute set containing the previously counted branches.
  (countMap: builtins.foldl' (sum: count: sum + count) 0 (builtins.attrValues countMap));

# This should return 5.
nleaves = countLeaves { a = { b = "b"; c = "c"; }; d.e.f = "f"; g = { h = { stop = 2; }; i = 7; }; };

foldAttrsIxCond :: ((AttrSet e ) -> Bool) -> (a -> Path -> b) -> (AttrSet b -> b) -> AttrSet a -> b

This is just like foldAttrsCond except the function to convert leaf values into final values also takes in the path from the top of the attribute set for that leaf value.

foldlIx :: (Natural -> b -> a -> b) -> b -> [a] -> b

Left fold with index

html :: FileName -> Content -> Content

Create an HTML file from the given content

img :: FilePath -> Content

Inserts an image in the given document and ensures that the imported image exits and is included in the final derivation

indent :: Natural -> Content -> Content

Indent the text of the content by the given number of spaces

intersperse :: a -> [a] -> [a]

Insert the given element inbetween elements of the given list

link :: Content -> Content

Generate a relative path to the given content

For example:

conix: with conix; [ (html "bob" { x = 3; }) (dir "larry" (html "joe" (link refs.x))) ]

will produce a relative path in the html file “joe” ../bob.html

list :: [Content] -> Content

Create a bullet list

local :: FilePath -> Content

Add a local file to the generated derivation

markdown :: FileName -> Content -> Content

Create a markdown file from the given text

merge :: [Content] -> Content

Merge Contents together. This concatenates text values, collects files into a single directory, and recursively merges data values.

Normally when constructing text values and you wish to concatenate them together one wishes to use something like: foo + "\n" + bar. With merge one can simply write: merge [ foo "\n" bar ] and achieve the same affect.

meta :: [Content] -> Content

Construct the meta data portion of a Pandoc sytle markdown file

modtxt :: (Text -> Text) -> Content -> Content

Modify the text produced by the content

module :: Content -> { Path :: Expression } -> Content

Create a new module with the given module doc string and attribute set containing expressions.

The first argument is content (typically module level documentation) to insert before API documentation.

For example:

  module 
    ''
    # String API

    This is an api for creating fancy strings.
    ''
    { 
      appendPeriod = expr
        "Content -> Content"
        "Appends a period to the given content"
        (x: [ x "."])
        ;
    }

nest :: PathString -> Content -> Content

Nest the data for the given content under a given path

For example:

  m: with m;
  [
    (nest "foo.bar" (n: with n; [{ x = 3; } (r data.x)]))
    {x = 4;}
    (r data.x)
  ]
will produce:

```nix
"3344"

notice how we’ve defined x in two places. Nesting allows one to keep the first x from overriding the value of the second.

pagetitle :: String -> Content

The title of the rendered document

pandoc :: OutputFileExtension -> PandocCmdArgs -> BuildInputs -> FileName -> Content -> Content

Use pandoc to construct a file from the given content

pathOf :: LocalFilePath -> Content

Writes the given file path as text and includes the referenced file in the output

pdf :: FileName -> Content -> Content

Create a PDF file from the given content

printNixVal :: a -> String

Pretty print a pure nix-value.

NOTE: do not call this function on a derivation as it will segfault.

r :: Content -> Content

See ref

run :: Content -> Derivation

Runs eval and extracts the derivation

runCode :: (Content -> Content) -> Language -> Code -> Content

Create a code block and append the results of executing the passed runner

runConixSnippet :: SnippetName -> Content -> Content

Run the given Conix code and insert its resulting text

runExtended :: Content -> Content -> Derivation

Runs evalExtended and extracts the derivation

runNixSnippet :: SnippetName -> NixCode -> Content

Create a Nix code block, execute the code, and append the results as a second code block

set :: AttrSet -> Content

Set a pure attribute set. This appends no new text to the content.

table :: [Content] -> [[Content]] -> Content

Create a markdown table with the given headers and rows

tell :: AttrSet -> Content -> Content

Add data to the given content. Attribute paths are absolute and not relative. TODO: add an example

text :: Text -> Content

Append text to the current file.

textfile :: FileName -> Content -> Content

Write the content to the given text file

tutorialSnippet :: FileName -> AttrPathName -> Content -> Content

Create a nix snippet with its content under a reference

using :: (AttrSet -> Content) -> Content

Creates expressions from functions that depend on the final data. Use this as follows:

conix: with conix; <content expression here>

Here conix = { pkgs = ...; data = ...; ... } where data is the final data and the rest of the conix attribute set is the conix library and a copy of (in pkgs of course).