Autogenerated documentation from ./src/std/*.

Cell: std

The std Cell

… is the only cell in divnix/std and provides only very limited functionality.

  • It contains the TUI, in ./cli.
  • It contains a devshellProfile in ./devshellProfiles.
  • It contains a growing number of second level library functions in ./lib.
  • Packages that are used in std devshells are proxied in ./packages.

That’s it.

Block: cli

No documentation

Block: devshellProfiles

std’s devshellProfiles

This Cell Block only exports a single default devshellProfile.

Any stdized repository should include this into its numtide/devshell in order to provide any visitor with the fully pre-configured std TUI.

It also wires & instantiates a decent ADR tool. Or were you planning to hack away without some minimal conscious effort of decision making and recording? 😅

Usage Example

# ./nix/local/shells.nix
{
  inputs,
  cell,
}: let
  l = nixpkgs.lib // builtins;
  inherit (inputs) nixpkgs;
  inherit (inputs.std) std;
in
  l.mapAttrs (_: std.lib.mkShell) {
    # `default` is a special target in newer nix versions
    # see: harvesting below
    default = {
      name = "My Devshell";
      # make `std` available in the numtide/devshell
      imports = [ std.devshellProfiles.default ];
    };
  }

# ./flake.nix
{
  inputs.std.url = "github:divnix/std";

  outputs = inputs:
    inputs.std.growOn {
      inherit inputs;
      cellsFrom = ./nix;
      cellBlocks = [
        /* ... */
        (inputs.std.blockTypes.devshells "shells")
      ];
    }
    # soil for compatiblity ...
    {
      # ... with `nix develop` - `default` is a special target for `nix develop`
      devShells = inputs.std.harvest inputs.self ["local" "shells"];
    };
}

Block: errors

Error Message Functions

This Cell Block comprises several error message functions that can be used in different situations.

Target: removeBy

No description

removeBy
{inputs}: time: body: let
  l = inputs.nixpkgs.lib // builtins;
  ansi = import ./ansi.nix;
  pad = s: let
    n = 17;
    prefix = l.concatStringsSep "" (l.genList (_: " ") (n - (l.stringLength s)));
  in
    prefix + s;
  indent = s: let
    n = 5;
    prefix = l.concatStringsSep "" (l.genList (_: " ") n);
    lines = l.splitString "\n" s;
  in
    "  📝 │ " + (l.concatStringsSep "\n${prefix}│ " lines);
  warn = let
    apply =
      l.replaceStrings
      (map (key: "{${key}}") (l.attrNames ansi))
      (l.attrValues ansi);
  in
    msg:
      l.trace (apply "🔥 {bold}{196}Standard Deprecation Notices - {220}run `std check' to show!{reset}")
      l.traceVerbose (apply "\n{202}${msg}{reset}");
in
  warn ''
    ─────┬─────────────────────────────────────────────────────────────────────────
      💪 │ {bold}Action Required !{un-bold}
    ─────┼─────────────────────────────────────────────────────────────────────────
    {italic}${indent body}{un-italic}
    ─────┼─────────────────────────────────────────────────────────────────────────
      📅 │ {bold}Scheduled Removal: ${pad time}{un-bold}
    ─────┴─────────────────────────────────────────────────────────────────────────
  ''

Target: requireInput

No description

requireInput
{inputs}: input: url: target: let
  l = inputs.nixpkgs.lib // builtins;

  # other than `divnix/blank`
  isBlank = input: inputs.${input}.narHash == "sha256-O8/MWsPBGhhyPoPLHZAuoZiiHo9q6FLlEeIDEXuj6T4=";

  ansi = import ./ansi.nix;

  pad = n: s: let
    prefix = l.concatStringsSep "" (l.genList (_: " ") n);
  in
    prefix + s;

  indent = s: let
    n = 5;
    prefix = l.concatStringsSep "" (l.genList (_: " ") n);
    lines = l.splitString "\n" s;
  in
    l.concatStringsSep "\n${prefix}│ " lines;

  warn = let
    apply =
      l.replaceStrings
      (map (key: "{${key}}") (l.attrNames ansi))
      (l.attrValues ansi);
  in
    msg: l.trace (apply "🚀 {bold}{200}Standard Input Overloading{reset}${msg}") "";

  body = ''
    In order to use ${target}, add to {bold}flake.nix{un-bold}:

      inputs.std.inputs.${input}.url = "${url}";
  '';

  inputs' = let
    names = l.attrNames (l.removeAttrs inputs ["self" "cells" "blank" "nixpkgs"]);
    nameLengths = map l.stringLength names;
    maxNameLength =
      l.foldl'
      (max: v:
        if v > max
        then v
        else max)
      0
      nameLengths;

    lines =
      l.map (
        name: "- ${name}${
          if isBlank name
          then pad (maxNameLength - (l.stringLength name)) " | blanked out"
          else ""
        }"
      )
      names;
  in
    "Declared Inputs:\n" + (l.concatStringsSep "\n" lines);
in
  assert l.assertMsg (! (isBlank input)) (warn ''

    ─────┬─────────────────────────────────────────────────────────────────────────
      🏗️  │ {bold}Input Overloading for ${target}{un-bold}
    ─────┼─────────────────────────────────────────────────────────────────────────
      📝 │ {italic}${indent body}{un-italic}
    ─────┼─────────────────────────────────────────────────────────────────────────
      🙋 │ ${indent inputs'}
    ─────┴─────────────────────────────────────────────────────────────────────────
  ''); inputs

Block: templates

Nix Templates

These are opinionated template projects designed to get you kick-started.

You can make use of them through the Nix CLI, via:

cd my-new-project
nix flake init -t github:divnix/std#<template-name>

Please consult the template section in the docs for an overview.

Target: minimal

No description

A minimal project template with docs!

Included Configuration
  • devshell for your contribution environments!
  • treefmt for formatting all the things!
  • mdbook for making documentation part of your workflow!
  • lefthook for commit discipline and a clean history!
  • GitHub Setting App for configuring GitHub declaratively!
Bootstrap
# make a new empty project dir
mkdir my-project
cd my-project

# grab the template
nix flake init -t github:divnix/std#minimal

# see which values to change
grep -r --include=\*.nix 'CONFIGURE-ME' .

# do some inititialization
git init && git add .

# enter the devshell and effectuate repo configuration
direnv allow

git add . && git commit -m "feat: initial commit"

Target: rust

No description

Standard, and Nix and Rust, oh my!

This template uses Nix to create a sane development shell for Rust projects, Standard for keeping your Nix code well organized, Fenix for pulling the latest rust binaries via Nix, and Crane for building Rust projects in Nix incrementally, making quick iteration a breeze.

Rust Analyzer is also wired up properly for immediate use from a terminal based editor with language server support. Need one with stellar Nix and Rust support? Try Helix!

Bootstrap
# make a new empty project dir
mkdir my-project
cd my-project

# grab the template
nix flake init -t github:divnix/std#rust

# do some inititialization
git init && git add .

# enter the devshell
direnv allow || nix develop

# continue some inititialization
cargo init # pass --lib for library projects
cargo build # to generate Cargo.lock

git add . && git commit -m "init"