Skip to content

Latest commit

 

History

History
107 lines (87 loc) · 4.58 KB

DOCUMENTATION.md

File metadata and controls

107 lines (87 loc) · 4.58 KB

Documentation

Module (module.nix)

  • Adds a scheme option to be set to whatever mkSchemeAttrs accepts (see below). When used as a value, scheme will be equal to mkSchemeAttrs scheme.
  • Sets config.lib.base16.mkSchemeAttrs.

Essentially, the module is a NixOS / home-manager interface to the library.

Library (lib)

Access it as:

  • config.lib.base16 if using base16.nix as a NixOS module,
  • pkgs.callPackage inputs.base16.lib {} otherwise.

It exports 1 function:

mkSchemeAttrs

Given a scheme, which is either

  • a path to a YAML file,
  • an attrset containing colors,
  • an argument attrset to yaml2attrs, which
  • MUST contain string attributes baseXX,
  • MAY contain string attributes scheme, author, description, slug,

returns a scheme attrset with a ton of convenient color attributes:

  • every attribute from the base16 standard,
  • attributes baseXX = baseXX-hex, e.g. base00 = "000000";
  • toList = [ base00 ... base0F ], for use in e.g. config.console.colors,
  • mnemonic color names for base08 — base0F and base12 — base17: 
    mnemonic = {
  red = base08;
  orange = base09;
  yellow = base0A;
  green = base0B;
  cyan = base0C;
  blue = base0D;
  magenta = base0E;
  brown = base0F;
  bright-red = base12 or base08;
  bright-orange = base13 or base09;
  bright-green = base14 or base0B;
  bright-cyan = base15 or base0C;
  bright-blue = base16 or base0D;
  bright-magenta = base17 or base0E;
};

Other cool stuff:

  • withHashtag — a scheme with # prepended to colors;
  • meta attributes: scheme-name & scheme, scheme-author & author, scheme-slug & slug, scheme-description & description;
  • override — a function to override the colors (via baseXX) and meta attributes (scheme, slug and author), see the relevant entry in the How To section;
  • outPath — an attribute for coercion to the scheme's path, i.e. "${config.scheme}" equals to a path to a yaml file with the scheme;
  • __functor — an attribute for coercion to a function: if you use scheme attrs as a function, it will call mkTheme by passing the scheme as scheme and the argument you called scheme attrs with as templateRepo (if it's a derivation or a flake input), otherwise it passes argument // { scheme = scheme attrs }.

Note: ∀ x . mkSchemeAttrs (mkSchemeAttrs x) == mkSchemeAttrs x

The function below isn't exported, but it's what powers up the scheme attrset's __functor attribute:

mkTheme

Builds a theme file from a scheme and a template and returns its path. If you don't supply templateRepo, then supply both template and extension.

mkTheme = {
  # A scheme attrset returned from `mkSchemeAttrs` function.
  scheme,
  # A directory with a `templates` subdirectory (containing templates and a `config.yaml` file)
  # (e.g. a flake input of a template repository).
  templateRepo ? null,
  # Name of the template to lookup in templateRepo.
  # Must be one of the top-level targets from `${templateRepo}/templates/config.yaml` and
  # correspond to a template `${templateRepo}/templates/${targetTemplate}.mustache`.
  target ? "default",
  # A string with mustache template.
  # If is `null`, then `${templateRepo}/templates/${targetTemplate}.mustache` is used.
  template ? null,
  # An extension (e.g. ".config") with which to save the resulting theme file.
  # If is `null` and `templateRepo` is passed, the extension will be grabbed from there,
  # otherwise it's an empty string
  extension ? null,
  # Whether to use [IFD](https://nixos.wiki/wiki/Import_From_Derivation) to parse yaml.
  # Can cause problems with `nix flake check / show` (see the issue #3).
  use-ifd ? false,
  # Whether to check if the config.yaml was parsed correctly.
  check-parsed-config-yaml ? true,
}:

yaml2attrs

Given a path to a YAML file, converts its' contents to a Nix attrset in pure Nix.

  • On use-ifd = "never" (default), may fail on complex YAMLs.
  • On use-ifd = "always", converts the file's contents to a Nix attrset using yaml2json package. Causes an IFD. Isn't used by default, but can help if you're experiencing troubles with incorrectly parsed YAML files (see README Troubleshooting section for details).
  • On use-ifd = "auto", causes an IFD if recognizes a complex YAML on which nix parser fails.