Styx Library Documentation

Preface

The library contains various functions that can be used through site.nix and templates.

This file is generated with a nix expression.

Styx documentation

Library functions are grouped in namespaces, but are also all included in the top-level scope to be easily accessible.
So for example, lib.utils.chunksOf can be shortened to lib.chunksOf.

1. conf

parseDecls

Description

Parse configuration interface declarations.

Arguments (Attribute Set)

decls

A configuration attribute set.

Type: Attrs.

optionFn

Function to convert options.

Type: Option → a.

Optional, defaults to lib.id.

valueFn

Function to convert values.

Type: a → b.

Optional, defaults to lib.id.

Return

Attrs

Example

Code

parseDecls {
  optionFn = o: option.default;
  valueFn  = v: v + 1;
  decls = {
    a.b.c = mkOption {
      default = "abc";
      type = types.str;
    };
    x.y = 1;
  };
}

Result

{
  a = {
    b = {
      c = "abc";
    };
  };
  x = {
    y = 2;
  };
}

typeCheck

Description

Type check configuration declarations against definitions.

Arguments (Standard)

decls

A configuration declarations attribute set.

Type: Attrs.

defs

A configuration definitions attribute set.

Type: Attrs.

Return

Throw an error if defs do not type-check with decls.

2. data

The data namespace contains functions to fetch and manipulate data.

asciidocToHtml

Description

Convert asciidoc text to HTML.

Arguments (Standard)

text

Text in asciidoc format.

Type: String.

Return

String

Example

Code

asciidocToHtml "Hello `asciidoc`!"

Result

"<div class=\"paragraph\">
<p>Hello <code>asciidoc</code>!</p>
</div>
"

groupBy

Description

Group a list of attribute sets.

Arguments (Standard)

list

List of attribute sets.

Type: [ Attrs ].

f

Function to generate the group name.

Type: Attrs → String.

Return

A property list of grouped attribute sets

Example

Code

groupBy [
  { type = "fruit"; name = "apple"; }
  { type = "fruit"; name = "pear"; }
  { type = "vegetable"; name = "lettuce"; }
]
(s: s.type)

Result

[ {
  fruit = [ {
    name = "apple";
    type = "fruit";
  } {
    name = "pear";
    type = "fruit";
  } ];
} {
  vegetable = [ {
    name = "lettuce";
    type = "vegetable";
  } ];
} ]

loadDir

Description

Load a directory containing data that styx can handle.

Arguments (Attribute Set)

asAttrs

If set to true, the function will return a set instead of a list. The key will be the file basename, and the value the data set.

Type: Bool.

Optional, defaults to false.

dir

The directory to load data from.

Type: Path.

env

The nix environment to use in loaded files.

Type: Attrs.

Optional, defaults to { }.

filterDraftsFn

Function to filter the drafts.

Type: Draft → Bool.

Optional, defaults to d: !( ( !(attrByPath ["conf" "renderDrafts"] false env) ) && (attrByPath ["draft"] false d) ).

Return

A list of data attribute sets. (Or a set of data set if asAttrs is true)

Example

Code

data.posts = loadDir {
  dir = ./data/posts;
  inherit env;
};

Any extra attribute in the argument set will be added to every loaded data attribute set.

loadFile

Description

Loads a data file

Arguments (Attribute Set)

env

The nix environment to use in loaded file.

Type: Attrs.

Optional, defaults to { }.

file

Path of the file to load.

Type: Path.

Return

A list of data attribute sets. (Or a set of data set if asAttrs is true)

Example

Code

data.posts = loadFile {
  file = ./data/pages/about.md;
  inherit env;
};

Any extra attribute in the argument set will be added to the data attribute set.

markdownToHtml

Description

Convert markdown text to HTML.

Arguments (Standard)

text

Text in markdown format

Type: String.

Return

String

Example

Code

markdownToHtml "Hello `markdown`!"

Result

"<p>Hello <code>markdown</code>!</p>
"

mkTaxonomyData

Description

Generate taxonomy data from a list of data attribute sets.

Arguments (Attribute Set)

Taxonomies

A list of taxonomies to extract.

Type: [ String ].

data

A list of data attribute sets to extract taxonomy data from.

Type: [ Data ].

Return

A taxonomy attribute set.

Example

Code

mkTaxonomyData {
  data = [
    { tags = [ "foo" "bar" ]; path = "/a.html"; }
    { tags = [ "foo" ];       path = "/b.html"; }
    { category = [ "baz" ];   path = "/c.html"; }
  ];
  taxonomies = [ "tags" "category" ];
}

Result

[ {
  category = [ {
    baz = [ {
      category = [ "baz" ];
      path = "/c.html";
    } ];
  } ];
} {
  tags = [ {
    foo = [ {
      path = "/b.html";
      tags = [ "foo" ];
    } {
      path = "/a.html";
      tags = [ "foo" "bar" ];
    } ];
  } {
    bar = [ {
      path = "/a.html";
      tags = [ "foo" "bar" ];
    } ];
  } ];
} ]

sortTerms

Description

Sort taxonomy terms by number of occurences.

Arguments (Standard)

terms

List of taxonomy terms attribute sets.

Type: [ Terms ].

Return

Sorted list of taxonomy terms attribute sets.

Example

Code

sortTerms [ { bar = [ {} {} ]; } { foo = [ {} {} {} ]; } ]

Result

[ {
  foo = [ { } { } { } ];
} {
  bar = [ { } { } ];
} ]

valuesNb

Description

Calculate the number of values in a taxonomy term attribute set.

Arguments (Standard)

term

Taxonomy terms attribute set.

Type: Terms.

Return

Int

Example

Code

valuesNb { foo = [ {} {} {} ]; }

Result

3. generation

generatePage

Description

Function to generate a page source, used by mkSite.

Arguments (Standard)

page

A page attribute set with at least layout and template defined.

Type: Page.

Return

Page source

Example

Code

generatePage {
  layout = template: "<html><body>${template}</body></html>";
  template = page: ''
    <h1>Styx example page</h1>
    ${page.content}
  '';
  content = "<p>Hello world!</p>";
};

Result

"<html><body><h1>Styx example page</h1>
<p>Hello world!</p>
</body></html>"

localesToPageList

Description

Convert a set of locales to a list of pages.

Arguments (Attribute Set)

default

A function to set default values to the pages, eg: to set the default layout template.

Type: Locale → Attrs.

Optional, defaults to locale: {}.

locales

A set of locales, each having a pages attribute set.

Type: Attrs.

Return

[ Page ]

Example

Code

pagelist = localesToPageList {
  inherit locales;
  default = locale: {
    layout = locale.env.templates.layout;
  };
};

Code

localesToPageList {
  locales = {
    eng = rec {
      code   = "eng";
      prefix = "/${code}";
      pages = {
        foo = { path = "/foo.html"; };
        bar = [ { path = "/bar-1.html"; } { path = "/bar-2.html"; } ];
      };
    };
    fre = rec {
      code = "fre";
      prefix = "/${code}";
      pages = {
        foo = { path = prefix + "/foo.html"; };
        bar = [ { path = prefix + "/bar-1.html"; } { path = prefix + "/bar-2.html"; } ];
      };
    };
  };
  default = locale: {
    baz = "${locale.code}-baz";
  };
}

Result

[ {
  baz = "eng-baz";
  path = "/foo.html";
} {
  baz = "eng-baz";
  path = "/bar-1.html";
} {
  baz = "eng-baz";
  path = "/bar-2.html";
} {
  baz = "fre-baz";
  path = "/fre/foo.html";
} {
  baz = "fre-baz";
  path = "/fre/bar-1.html";
} {
  baz = "fre-baz";
  path = "/fre/bar-2.html";
} ]

mkSite

Description

Generate a site, this is the main function of a styx site.

Arguments (Attribute Set)

files

A list of static files directories to copy in the site.

Type: [ Path ].

Optional, defaults to [ ].

genPageFn

Function to generate a page source from a page attribute set.

Type: Page → String.

Optional, defaults to lib.generation.generatePage.

pageList

A list of pages attributes sets to generate.

Type: [ Page ].

Optional, defaults to [ ].

pagePathFn

Function to generate a page from a page attribute set.

Type: Page → String.

Optional, defaults to page: page.path.

postGen

A set of command to execute after generating the site.

Type: String.

Optional, defaults to "".

preGen

A set of command to execute before generating the site.

Type: String.

Optional, defaults to "".

substitutions

A substitution set to apply to static files.

Type: Attrs.

Optional, defaults to { }.

Return

The site derivation.

Example

Code

mkSite { pageList = [ pages.index ]; }

pagesToList

Description

Convert a set of pages to a list of pages.

Arguments (Attribute Set)

default

Attribute set of default values to add to every page set, useful to set layout.

Type: Attrs.

Optional, defaults to { }.

pages

A set of page attribute sets.

Type: Attrs.

Return

[ Page ]

Example

Code

pagelist = pagestolist {
  inherit pages;
  default.layout = templates.layout;
};

Code

pagesToList {
  pages = {
    foo = { path = "/foo.html"; };
    bar = [ { path = "/bar-1.html"; } { path = "/bar-2.html"; } ];
  };
  default = {
    baz = "baz";
  };
}

Result

[ {
  baz = "baz";
  path = "/foo.html";
} {
  baz = "baz";
  path = "/bar-1.html";
} {
  baz = "baz";
  path = "/bar-2.html";
} ]

4. pages

mkMultipages

Description

Create the list of pages from a multipage data set.

Arguments (Attribute Set)

basePath

String used by pathFn to generate the page path. Used in pageFn default, ignored if pageFn is set.

Type: String.

Optional, defaults to null.

pageFn

Function to generate extra attributes to merge to the page.

Type: Int → Data → Page.

Optional, defaults to:

index: data:
  optionalAttrs (basePath != null) {
    path = mkSplitPagePath { inherit index; pre = basePath; };
  }

pages

List of subpages data.

Type: [ Attrs ].

Return

Pages according to the output.
Every page will get a multipages attribute containing:

pages: list of all the subpages.
index: Index of the page in the subpages list.

Example

Code

pages.about = mkMultipages ({
  template = templates.page.full;
  basepath = "about";
} // data.about);

Any extra arguments will be forwarded to every generated page set.

mkPageList

Description

Generate a list of pages from a list of data set.

Arguments (Attribute Set)

data

List of data sets.

Type: [ Data ].

multipageFn

Function to generate extra attributes of mutipages.

Type: Int → Data → Attrs.

Optional, defaults to:

index: data: {
  path = mkSplitPagePath { pre = "${pathPrefix}${data.fileData.basename}"; inherit index; };
}

pageFn

Function to generate extra attributes of normal pages.

Type: (Data → Attrs).

Optional, defaults to data: { path = "${pathPrefix}${data.fileData.basename}.html"; }.

pathPrefix

String used by pathFn and multipagePathFn to generate the page path.

Type: String.

Optional, defaults to "".

Return

An attribute set with the following attributes:.

list: The list of contents, containing single pages and first page of multipages posts.
pages: List of all pages, including multipages subpages.

Example

Code

pages.posts = mkPageList {
  data       = data.posts;
  pathPrefix = "/posts/";
  template   = templates.post.full;
};

Any extra arguments will be forwarded to every generated page set.

mkPages

Description

Generate a pages attribute set. It is used to produce multiple "outputs" by pages generating functions like mkPageList.
pagesToList will only generate the pages attribute from a pages attribute set.

Arguments (Attribute Set)

pages

List of pages to generate.

Type: [ Page ].

Return

A pages attribute set.

Any extra argument will be added to the pages set.

mkSplit

Description

Create a list of pages from a list of data.

Arguments (Attribute Set)

basePath

Base path of the generated pages. First page path will be "basePath.html", follwing pages "basePath-index.html"

Type: Attrs.

data

List of data sets.

Type: [ Data ].

itemsPerPage

Number of data items to allocate to a page.

Type: Int.

Return

List of pages. Each page has:

items: List of the page data items.
pages: List of splitted pages.

Example

Code

pages.archives = mkSplit {
  basePath     = "/archives";
  itemsPerPage = 10;
  data         = pages.posts;
  template     = templates.archives;
};

Code

mkSplit {
  data = map (x: { id = x; }) (range 1 4);
  itemsPerPage = 2;
  basePath = "/test";
}

Result

[ {
  index = 1;
  items = [ {
    id = 1;
  } {
    id = 2;
  } ];
  pages = [ ... ];
  path = "/test.html";
} {
  index = 2;
  items = [ {
    id = 3;
  } {
    id = 4;
  } ];
  pages = [ ... ];
  path = "/test-2.html";
} ]

Any extra arguments will be forwarded to every generated page set.

mkSplitCustom

Description

Create a list of pages from a list of data.

Arguments (Attribute Set)

data

List of data sets.

Type: [ Data ].

pageFn

A function to apply to each data set, takes the index of the page and a data set and return a page set.
Must set itemsNb, the number of item to have on the page, and path to generate valid pages.

Type: Int → Data → Page.

Example:

index: data: {
  itemsNb = if index == 1 then 3 else 5;
  path = if index == 1 then "/index.html" else "/archive-${toString index}.html";
}

Return

List of pages. Each page has:

items: List of the page data items.
pages: List of splitted pages.

Example

Code

mkSplitCustom {
  data = map (x: { id = x; }) (range 1 4);
  pageFn = (index: data: {
    itemsNb = if index == 1 then 3 else 5;
    path    = if index == 1 then "/index.html" else "/archive-${toString index}.html";
  });
}

Result

[ {
  index = 1;
  items = [ {
    id = 1;
  } ];
  pages = [ ... ];
  path = "/index.html";
} {
  index = 2;
  items = [ {
    id = 2;
  } {
    id = 3;
  } ];
  pages = [ ... ];
  path = "/archive-2.html";
} {
  index = 3;
  items = [ {
    id = 4;
  } ];
  pages = [ ... ];
  path = "/archive-3.html";
} ]

mkSplitPagePath

Description

Function to generate a splitted page path.

Arguments (Attribute Set)

index

Index of the page.

Type: Int.

post

String to add at the end of the path.

Type: String.

Optional, defaults to ".html".

pre

String to add at the beginning of the path.

Type: String.

Return

Page path.

Example

Code

mkSplitPagePath {
  index = 1;
  pre = "/foo";
}

Result

"/foo.html"

Code

mkSplitPagePath {
  index = 3;
  pre = "/foo";
}

Result

"/foo-3.html"

mkTaxonomyPages

Description

Generate taxonomy pages from a data set list.

Arguments (Attribute Set)

data

List of data sets.

Type: [ Data ].

taxonomyPageFn

Function to add extra attributes to the taxonomy page set.

Type: (String → Page).

Optional, defaults to taxonomy: {}.

taxonomyTemplate

Template used for taxonomy pages.

Type: Null | Template.

termPageFn

Function to add extra attributes to the taxonomy page set.

Type: (String → String → Page).

Optional, defaults to taxonomy: term: {}.

termTemplate

Template used for taxonomy term pages.

Type: Null | Template.

Return

List of taxonomy page attribute sets.

Example

Code

pages.postTaxonomies = mkTaxonomyPages {
  data = data.taxonomies.posts;
  taxonomyTemplate = templates.taxonomy.full;
  termTemplate = templates.taxonomy.term.full;
};

mkTaxonomyPath

Description

Generate a taxonomy page path.

Arguments (Standard)

taxonomy

Type: String.

Return

Taxonomy page path.

Example

Code

mkTaxonomyPath "tags"

Result

"/tags/index.html"

mkTaxonomyTermPath

Description

Generate a taxonomy term page path.

Arguments (Standard)

taxonomy

Type: String.

term

Type: String.

Return

Taxonomy term page path.

Example

Code

mkTaxonomyTermPath "tags" "styx"

Result

"/tags/styx/index.html"

5. proplist

The proplist namespace contains functions to manipulate property lists, list of attribute set with only one attribute.

Property lists are used in the taxonomy data structure.

Example:

[ { type = "fruit"; } { name = "Apple"; } ]

getProp

Description

Get a property in a property list by the key name.

Arguments (Standard)

key

Key of the property to extract.

Type: String.

proplist

The property list to extract the property from.

Type: PropList.

Return

Property

Example

Code

getProp "name" [ { name = "Alice"; } ]

Result

{
  name = "Alice";
}

getValue

Description

Get a value from a property in a property list by the key name.

Arguments (Standard)

key

Key of the property to extract value.

Type: String.

proplist

The property list to extract the value from.

Type: PropList.

Return

The value of the property.

Example

Code

getValue "name" [ { name = "Alice"; } ]

Result

"Alice"

isDefined

Description

Check if a property with a key exists in a property list.

Arguments (Standard)

key

Key of the property to check existence.

Type: String.

proplist

The property list to check.

Type: PropList.

Return

Bool

Example

Code

isDefined "name" [ { name = "Alice"; } ]

Result

true

propFlatten

Description

Flatten a property list which values are lists.

Arguments (Standard)

proplist

The property list to flatten.

Type: PropList.

Return

The flattened property list.

Example

Code

propFlatten [ { foo = [ 1 2 ]; } { bar = "baz"; } { foo = [ 3 4 ]; } ]

Result

[ {
  foo = [ 1 2 3 4 ];
} {
  bar = "baz";
} ]

propKey

Description

Get the key of a property.

Arguments (Standard)

prop

The property to extract the key from.

Type: Property.

Return

Key of the property.

Example

Code

propKey { name = "Alice"; }

Result

"name"

propMap

Description

Map for property lists.

Arguments (Standard)

f

Function to map to the property list.

Type: PropKey → PropValue → a.

proplist

The property list to map.

Type: PropList.

Return

[ a ]

Example

Code

propMap (k: v: "${k}: ${v}") [ { name = "Alice"; } { hobby = "Sports"; } ]

Result

[ "name: Alice" "hobby: Sports" ]

propValue

Description

Get the value of a property.

Arguments (Standard)

prop

The property to extract the value from.

Type: Property.

Return

The value of the property.

Example

Code

propValue { name = "Alice"; }

Result

"Alice"

removeProp

Description

Return a property list where the property with key key has been removed.

Arguments (Standard)

key

Key of the property to remove.

Type: String.

proplist

The property list to remove the property from.

Type: PropList.

Return

PropList

Example

Code

removeProp "name" [ { name = "Alice"; } { hobby = "Sports"; } ]

Result

[ {
  hobby = "Sports";
} ]

6. template

documentedTemplate

Description

Provide a way to document a template function.

Arguments (Attribute Set)

arguments

Template arguments documentation. Attrs if the arguments are an attribute set, List for standard arguments.

Type: Null | Attrs | List.

Optional, defaults to null.

description

Template description, asciidoc markup can be used.

Type: String.

env

Template environment.

examples

Examples of usages defined with mkExample.

Type: Null | [ Example ].

notes

Notes regarding special usages, asciidoc markup can be used.

Type: Null | String.

Optional, defaults to "Null".

template

Template to document.

Return

The template function, or the documented template set if env has a genDoc attribute set to true.

escapeHTML

Description

Escape an HTML string.

Arguments (Standard)

html

A HTML string to escape.

Type: String.

Return

The escaped HTML string.

Example

Code

escapeHTML ''<p class="foo">Hello world!</p>''

Result

"&lt;p class=&quot;foo&quot;&gt;Hello world!&lt;/p&gt;"

htmlAttr

Description

Generates a HTML tag attribute.

Arguments (Standard)

attribute

HTML attribute name.

Type: String.

value

HTML attribute value.

Type: String | [ String ].

Return

The HTML attribute string.

Example

Code

htmlAttr "class" "foo"

Result

"class=\"foo\""

Code

htmlAttr "class" [ "foo" "bar" ]

Result

"class=\"foo bar\""

htmlAttrs

Description

Generate a HTML tag attributes.

Arguments (Standard)

Set

An attribute set where the key is the attribute name, and the value the attribute value(s).

Type: Attrs.

Return

The HTML attributes string.

Example

Code

htmlAttrs { class = [ "foo" "bar" ]; }

Result

"class=\"foo bar\""

Code

htmlAttrs { class = [ "foo" "bar" ]; id = "baz"; }

Result

"class=\"foo bar\" id=\"baz\""

isDocTemplate

Description

Check if a set is a documented template.

Arguments (Standard)

set

Attribute set to check.

Type: Attrs.

Return

Bool

Example

isEven

Description

Checks if a number is even.

Arguments (Standard)

a

Number to check.

Type: Int.

Return

Bool

Example

Code

isEven 3

Result

false

isOdd

Description

Checks if a number is odd.

Arguments (Standard)

a

Number to check.

Type: Int.

Return

Bool

Example

Code

isOdd 3

Result

true

mapTemplate

Description

Concat template functions with a new line.

Arguments (Standard)

template

The template to apply, must return a string.

Type: Function.

items

The items to apply to the template.

Type: List.

Return

String

Example

Code

mapTemplate (item: ''
  <li>${item}</li>''
) [ "foo" "bar" "baz" ]

Result

"<li>foo</li>
<li>bar</li>
<li>baz</li>"

mapTemplateWithIndex

Description

Concat template functions with a new line.

Arguments (Standard)

template

The template to apply, must return a string.

Type: Function.

items

The items to apply to the template.

Type: List.

Return

String

Example

Code

mapTemplateWithIndex (index: item: ''
  <li>${toString index} - ${item}</li>''
) [ "foo" "bar" "baz" ]

Result

"<li>1 - foo</li>
<li>2 - bar</li>
<li>3 - baz</li>"

mod

Description

Returns the remainder of a division.

Arguments (Standard)

dividend

Dividend.

Type: Int.

divisor

Divisor.

Type: Int.

Return

Division remainder.

Example

Code

mod 3 2

Result

normalTemplate

Description

Abstract the normal template pattern.

Arguments (Standard)

a

This argument can be:

String: The argument will be added to the page set content.
Attribute Set: The argument will be merged to the page set.
Page → String: The String argument will be added to the page set content attribute.
Page → Attrs: The Attra parameter will be merged to the page set.

Return

A normal template function of type Page → Page.

Example

Code

let template = normalTemplate "A simple string.";
    page = { data = "Page data."; };
in template page

Result

{
  content = "A simple string.";
  data = "Page data.";
}

Code

let template = normalTemplate { content = "Page content."; };
    page = { data = "Page data."; };
in template page

Result

{
  content = "Page content.";
  data = "Page data.";
}

Code

let template = normalTemplate (page: "Page data: ${page.data}");
    page = { data = "Page data."; };
in template page

Result

{
  content = "Page data: Page data.";
  data = "Page data.";
}

Code

let template = normalTemplate (page: { title = "foo"; "Page data: ${page.data}"; });
    page = { data = "Page data."; };
in template page

Result

{
  content = "Page data: Page data.";
  data = "Page data.";
  title = "foo";
}

parseDate

Description

Parse a date.

Arguments (Standard)

date

A date string in format "YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ss"

Type: String.

Return

A date attribute set, with the following attributes:

YYYY: The year in 4 digit format (2012).
YY: The year in 2 digit format (12).
Y: Alias to YYYY.
y: Alias to YY.
MM: The month in 2 digit format (12, 01).
M: The month number (12 ,1).
m: Alias to MM.
m-: Alias to M.
B: Month in text format (December, January).
b: Month in short text format (Dec, Jan).
DD: Day of the month in 2 digit format (01, 31).
D: Day of the month (1, 31).
d-: Alias to D.
hh: The hour in 2 digit format (08, 12).
h: The hour in 1 digit format (8, 12).
mm: The minuts in 2 digit format (05, 55).
ss: The seconds in 2 digit format (05, 55).
time: The time in the mm:hh:ss format (12:00:00).
date.num: The date in the YYYY-MM-DD format (2012-12-21).
date.lit: The date in the D B YYYY format (21 December 2012).
T: The date and time combined in the YYYY-MM-DDThh:mm:ssZ format (2012-12-21T12:00:00Z).

Example

Code

with (parseDate "2012-12-21"); "${D} ${b} ${Y}"

Result

"21 Dec 2012"

processBlocks

Description

Merge blocks data.

Arguments (Standard)

blocks

List of blocks attributes set

Type: [ Block ].

Return

Block

Example

Code

processBlocks [ {
  content = "Block A";
  extraJS = "js/a.js";
} {
  content  = "Block B";
  extraJS  = "js/b.js";
  extraCSS = "css/b.css";
} {
  content  = "Block C";
  extraCSS = "css/c.css";
} {
  content  = "Block D";
  extraJS  = [ "js/d.js"   "js/d-1.js" ];
  extraCSS = [ "css/d.css" "css/d-1.css" ];
} ]

Result

{
  content = "Block A
Block B
Block C
Block D";
  extraCSS = [ "css/b.css" "css/c.css" "css/d.css" "css/d-1.css" ];
  extraJS = [ "js/a.js" "js/b.js" "js/d.js" "js/d-1.js" ];
}

7. themes

docText

Description

Convert a documentation set to a property list to generate documention.

Arguments (Standard)

doc

Documentation set.

Type: Attrs.

Return

A prepared documentation property list.

Example

Code

docText (mkDoc {
  title = mkOption {
    description = "Title";
    type = types.str;
  };
  foo.bar = 1;
})

Result

[ {
  "foo.bar" = {
    default = 1;
  };
} {
  title = {
    description = "Title";
    type = "string";
  };
} ]

load

Description

Load themes data.

Arguments (Attribute Set)

extraConf

A list of configuration attribute sets or configuration files to merge to themes configuration.

Type: [ Attrs ].

Optional, defaults to [ ].

extraEnv

An attribute set to merge to the environment, the environment is used in templates and returned in the env attribute.

Type: Attrs.

Optional, defaults to { }.

styxLib

The styx library.

Type: Attrs.

themes

List of themes, local themes or packages.

Type: [ (Path | Package) ].

Optional, defaults to { }.

Return

A theme data attribute set containing:

conf: Themes configuration merged with extraConf.
lib: The merged themes library.
files: List of static files folder.
templates: The merged themes template set.
themes: List of themes attribute sets.
decls: Themes declaration set.
docs: Themes documentation set.
env: Generated environment attribute set, extraEnv merged with lib, conf and templates.

Example

Code

themesData = styxLib.themes.load {
  inherit styxLib themes;
  extraEnv  = { inherit data pages; };
  extraConf = [ ./conf.nix extraConf ];
};

loadData

Description

Load a theme data.

Arguments (Attribute Set)

styxLib

The styx library.

Type: Attrs.

theme

A local theme or theme package.

Type: (Path | Package).

Return

A theme data attribute set containing:

lib: Theme library set.
meta: Theme meta information set.
path: Path of the theme.
decls: Theme declaration set, only if the theme defines a configuration interface.
docs: Theme documentation set, only if the theme defines a configuration interface.
exampleSrc: Theme example site source, only if the theme provides an example site.
templates: Theme templates set, only if the theme provides templates.
files: Theme static files path, only if the theme provides static files.

mkDoc

Description

Convert a theme declaration set to a documentation set.

Arguments (Standard)

decls

Theme declarations set.

Type: Attrs.

Return

A documentation set.

Example

Code

mkDoc {
  foo.bar = 1;
  title = mkOption {
    description = "Title";
    type = types.str;
  };
}

Result

{
  foo = {
    bar = {
      _type = "option";
      default = 1;
    };
  };
  title = {
    _type = "option";
    description = "Title";
    type = "string";
  };
}

8. utils

This namespace contains generic functions.

chunksOf

Description

Split a list in lists multiple lists of size items.

Arguments (Standard)

size

Maximum size of the splitted lists.

Type: Integer.

list

List to split.

Type: List.

Return

A list of lists of size size.

Example

Code

chunksOf 2 [ 1 2 3 4 5 ]

Result

[ [ 1 2 ] [ 3 4 ] [ 5 ] ]

dirContains

Description

Check if a path exists in a directory.

documentedFunction

Description

Create a documented function. A documented function is used to automatically generate documentation and tests.

Arguments (Attribute Set)

arguments

Function arguments documentation. Attrs if the arguments are an attribute set, List for standard arguments.

Type: Null | Attrs | List.

Optional, defaults to null.

description

Function description, asciidoc markup can be used.

Type: String.

examples

Examples of usages defined with mkExample.

Type: Null | [ Example ].

function

The function to document.

notes

Notes regarding special usages, asciidoc markup can be used.

Type: Null | String.

Optional, defaults to "Null".

return

Description of function return value, asciidoc markup can be used.

Type: String.

Return

The documented function set.

find

Description

Find a set in a list of set matching some criteria.

Arguments (Standard)

criteria

Criteria to find as an attribute set, can be a value to be compared or a function to compare the value.

Type: Attrs.

list

List of attributes to lookup for criteria.

Type: Attrs.

Return

The first matched attribute set, or throw an error if no result has been found.

Example

Code

find { uid = "bar"; } [
  { uid = "foo"; }
  { uid = "bar"; content = "hello!"; }
  { uid = "baz"; }
]

Result

{
  content = "hello!";
  uid = "bar";
}

Code

find { number = (x: x > 3); color = "blue"; } [
  { number = 1; color = "blue"; }
  { number = 4; color = "red"; }
  { number = 6; color = "blue"; }
]

Result

{
  color = "blue";
  number = 6;
}

getAttrs

Description

Get the attribute values for the n attribute name from a l list of attribute sets.

Arguments (Standard)

n

Attribute name.

Type: String.

l

List of attribute sets.

Type: [ Attrs ].

Return

A list containing the values of n.

Example

Code

getAttrs "a" [ { a = 1; } { a = 2; } { b = 3; } { a = 4; } ]

Result

[ 1 2 4 ]

importApply

Description

Import a nix file file and apply the arguments arg if it is a function.

Arguments (Standard)

file

Nix file to load.

Type: Path.

arg

Argument to call file contents with if it is a function.

is

Description

Check if an attribute set has a certain type.

Arguments (Standard)

type

Type to check.

Type: String.

attrs

Attribute set to check.

Type: Attrs.

Return

Bool

Example

Code

is "foo" { _type = "foo"; }

Result

true

isDocFunction

Description

Check if a set is a documented fuction.

Arguments (Standard)

attrs

Attribute set to check.

Type: Attrs.

Return

Bool

isExample

Description

Check if a set is an example.

Arguments (Standard)

attrs

Attribute set to check.

Type: Attrs.

Example

Code

isExample (mkExample {
  literalCode = "2 + 2";
  code = 2 + 2;
})

Result

true

merge

Description

Merge recursively a list of sets.

Example

Code

conf = lib.utils.merge [
  (lib.themes.loadConf { inherit themes; })
  (import ./conf.nix)
  extraConf
];

Code

merge [ { a = 1; b = 2; } { b = "x"; c = "y"; } ]

Result

{
  a = 1;
  b = "x";
  c = "y";
}

mkExample

Description

Create an example set.

Return

An example attribute set.

prettyNix

Description

Pretty print nix values.

Example

Code

prettyNix [ { a.b.c = true; } { x.y.z = [ 1 2 3 ]; } ]

Result

"[ {
  a = {
    b = {
      c = true;
    };
  };
} {
  x = {
    y = {
      z = [ 1 2 3 ];
    };
  };
} ]"

setToList

Description

Convert a deep set to a list of sets where the key is the path.

Example

Code

setToList { a.b.c = true; d = "foo"; x.y.z = [ 1 2 3 ]; }

Result

[ {
  "a.b.c" = true;
} {
  d = "foo";
} {
  "x.y.z" = [ 1 2 3 ];
} ]

sortBy

Description

Sort a list of attribute sets by attribute.

Example

Code

sortBy "priority" "asc" [ { priority = 5; } { priority = 2; } ]

Result

[ {
  priority = 2;
} {
  priority = 5;
} ]