foodogsquared/nixos-config
1
0
Fork 0
mirror of https://github.com/foo-dogsquared/nixos-config.git synced 2025-03-15 12:19:00 +00:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

lib: convert comments into nixdoc docstrings

Browse Source
This commit is contained in:
Gabriel Arazas 2025-02-26 21:22:47 +08:00
parent 6646d6f7f6
commit 3dfeb40453
No known key found for this signature in database
GPG Key ID: 62104B43D00AA360
5 changed files with 614 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
lib/builders/default.nix
View File

@ -1,13 +1,227 @@
{ pkgs, lib, self }:
{
/**
Create a derivation containing an XDG MIME association listing.
# Arguments
It's a sole attribute set with the following attributes:
config
: Nix-representable settings in INI format.
desktopName
: An optional string containing the desktop name. By default, it's empty
representing the global settings. Otherwise, it's considered to be
desktop-specific.
addedAssociations
: An attrset of MIME associations. This is not set if it's a
desktop-specific configuration.
removedAssociations
: An attrset of MIME associations. This is not set if it's a
desktop-specific configuration.
defaultApplications
: An attrset of MIME associations for default applications.
settings
: Nix-representable settings in INI format. Mutually exclusive with the
proper associations attribute and ignores proper checking if set. By
default, it is empty.
# Type
```
makeXDGMimeAssociationList :: Attr -> Derivation
```
# Examples
```nix
makeXDGMimeAssociationList {
defaultApplications = { "application/pdf" = "firefox.desktop"; };
addedAssociations = {
};
}
```
*/
makeXDGMimeAssociationList =
pkgs.callPackage ./xdg/make-association-list.nix { };
/**
Create a derivation containing an XDG Portal configuration.
# Arguments
It's a sole attribute set with the following attributes:
config
: The settings as a Nix-representable settings in INI format.
desktopName
: The name of the desktop name. By default, it is set to `common` which is
considered as the global namespace. Otherwise, you can just set
desktop-specific settings.
# Type
```
makeXDGPortalConfiguration :: Attr -> Derivation
```
# Examples
```nix
makeXDGPortalConfiguration {
desktopName = "one.foodogsquared.SampleDesktop";
config.preferred = {
default = "gtk";
"org.freedesktop.impl.portal.Screencast" = "gnome";
};
}
```
*/
makeXDGPortalConfiguration =
pkgs.callPackage ./xdg/make-portal-config.nix { };
/**
Create a derivation containing an XDG desktop entry file. Unlike
`pkgs.makeDesktopItem`, it's more freeform.
# Arguments
It's a sole attribute set with the following attributes:
name
: Name of the desktop entry. Only used as part of the package name and the
default value of the destination path.
config
: Nix-representable data to be exported as the desktop entry.
validate
: Add a validation check for the exported desktop entry.
destination
: Destination path relative to the output path.
# Type
```
makeXDGDesktopEntry :: Attr -> Derivation
```
# Examples
```nix
makeXDGDesktopEntry {
name = "horizontal-hunger";
validate = false;
config = { "Desktop Entry".Exec = "Hello"; };
}
```
*/
makeXDGDesktopEntry = pkgs.callPackage ./xdg/make-desktop-entry.nix { };
/**
A wrapper for building Hugo projects.
# Arguments
Similar to `pkgs.buildGoModule`.
# Type
```
buildHugoSite :: Attr -> Derivation
```
# Examples
```nix
buildHugoSite {
pname = "foodogsquared-hm-startpage";
version = "0.3.0";
src = lib.cleanSource ./.;
vendorHash = "sha256-Mi61QK1yKWIneZ+i79fpJqP9ew5r5vnv7ptr9YGq0Uk=";
preBuild = ''
install -Dm0644 ${
../tinted-theming/base16/bark-on-a-tree.yaml
} ./data/foodogsquared-homepage/themes/_dark.yaml
install -Dm0644 ${
../tinted-theming/base16/albino-bark-on-a-tree.yaml
} ./data/foodogsquared-homepage/themes/_light.yaml
'';
meta = with lib; {
description = "foodogsquared's homepage";
license = licenses.gpl3Only;
};
}
```
*/
buildHugoSite = pkgs.callPackage ./hugo-build-site { };
/**
An convenient function for building with the custom extended stdenv.
# Arguments
Similar to `pkgs.buildEnv`.
# Type
```
buildFDSEnv :: Attr -> Derivation
```
# Examples
```nix
buildFDSEnv {
paths = with pkgs; [ hello ];
pathsToLink = [ "/bin" "/share" ];
}
```
*/
buildFDSEnv =
pkgs.callPackage ./build-fds-env.nix { extendedStdenv = self.stdenv; };
/**
A wrapper for creating dconf databases.
# Arguments
A sole attribute set with the following attributes:
dir
: The directory of the dconf keyfiles.
name
: The name of the dconf database. By default, it is based from the directory name.
keyfiles
: A list of keyfiles to be included in the dconf database compilation.
# Type
```
buildDconfDb :: Attr -> Derivation
```
# Examples
```nix
buildDconfDb {
dir = ./config/dconf;
name = "custom-gnome";
}
```
*/
buildDconfDb = pkgs.callPackage ./build-dconf-db.nix { };
}

77
lib/data.nix
View File

@ -5,14 +5,27 @@
{ pkgs, lib, self }:
{
/* Import the YAML file and return it as a Nix object. Unfortunately, this is
/**
Import the YAML file and return it as a Nix object. Unfortunately, this is
implemented as an import-from-derivation (IFD) so it will not be pretty.
Type: importYAML :: Path -> Attrs
# Arguments
Example:
path
: The path of the YAML file.
# Type
```
importYAML :: Path -> Attrs
```
# Examples
```nix
importYAML ./your-mom.yaml
=> { name = "Yor Mum"; age = 56; world = "Herown"; }
```
*/
importYAML = path:
let
@ -21,14 +34,37 @@
'';
in lib.importJSON dataDrv;
/* Render a Tera template given a parameter set powered by `tera-cli`. Also
/**
Render a Tera template given a parameter set powered by `tera-cli`. Also
typically used as an IFD.
Type: renderTeraTemplate :: Attrs -> Path
# Arguments
Example:
It's a sole attribute set with the following attributes:
template
: The template file to be used.
context
: An attribute set containing the data used alongside the template.
extraArgs
: An attrset of command line arguments (same as
`lib.cli.toGNUCommandLineShell`) to be added on top of the typical
arguments used by the function.
# Type
```
renderTeraTemplate :: Attrs -> Path
```
# Example
```nix
renderTeraTemplate { path = ./template.tera; context = { hello = 34; }; }
=> /nix/store/HASH-tera-render-template
```
*/
renderTeraTemplate = { template, context, extraArgs ? { } }:
let
@ -45,14 +81,37 @@
tera --out "$out" ${extraArgs'} --template "${template}" "${contextFile}"
'';
/* Render a Mustache template given a parameter set powered by `mustache-go`.
/**
Render a Mustache template given a parameter set powered by `mustache-go`.
Also typically used as an IFD.
Type: renderMustacheTemplate :: Attrs -> Path
# Arguments
Example:
It's a sole attribute set with the following attributes:
template
: The path containing the template file.
context
: An attribute set of metadata used in the template file.
extraArgs
: An attrset of additional command line arguments (same as the argument
used in `lib.cli.toGNUCommandLineShell`) on top of the typical arguments
used in the function.
# Type
```
renderMustacheTemplate :: Attrs -> Path
```
# Examples
```nix
renderMustacheTemplate { path = ./template.mustache; context = { hello = 34; }; }
=> /nix/store/HASH-mustache-render-template
```
*/
renderMustacheTemplate = { template, context, extraArgs ? { } }:
let extraArgs' = lib.cli.toGNUCommandLineShell { } extraArgs;

78
lib/fetchers/default.nix
View File

@ -1,6 +1,84 @@
{ pkgs, lib, self }:
{
/**
A convenient wrapper for fetching contents from the Internet Archive.
# Arguments
It's a sole attribute set with the extra following attributes:
id
: The identifier of the item typically found in the URL of the object.
formats
: An array of formats to be downloaded. Mutually exclusive with `file`
attribute.
file
: The specific file to be downloaded. Mutually exclusive with `formats`
attribute.
It can also accept other arguments as an extra attributes for its fetcher
function (e.g., `hash` for fixed-output derivations).
# Type
```
fetchInternetArchive :: Attr -> Derivation
```
# Examples
```nix
fetchInternetArchive {
id = "md_music_sonic_the_hedgehog";
formats = [ "TEXT" "PNG" ];
hash = "sha256-xbhasJ/wEgcY+EcBAJp5UoYB4N4It3QV/iIeGGdCET8=";
}
fetchInternetArchive {
id = "md_music_sonic_the_hedgehog";
file = "01 - Title Theme - Masato Nakamura.flac";
hash = "sha256-kGjsVjtjXK9imqyi4GF6qkFVmobiTAe/ZAeEwiouqS4=";
}
```
*/
fetchInternetArchive = pkgs.callPackage ./fetch-internet-archive { };
/**
An convenient wrapper for downloading Ugee drivers.
# Arguments
It's a sole attribute set with the following attributes:
fileId
: The file identifier containing the driver.
pid
: The identifier of the model.
ext
: The file extension expected for the file.
# Type
```
fetchUgeeDriver :: Attr -> Derivation
```
# Examples
```nix
# Ugee M908.
fetchUgeeDriver {
fileId = "943";
pid = "505";
hash = "sha256-50Dbyaaa1B8nQu3+tTGvh/yjQqwaARB2MWtKSOUYsKg=";
ext = "tar.gz";
}
```
*/
fetchUgeeDriver = pkgs.callPackage ./fetch-ugee-driver { };
}

42
lib/math.nix
View File

@ -2,24 +2,58 @@
{ pkgs, lib, self }:
rec {
/* Returns the absolute value of the given number.
/**
Returns the absolute value of the given number.
Example:
# Arguments
number
: The numerical value.
# Type
```
abs :: Number -> Number
```
# Examples
```nix
abs -4
=> 4
abs (1 / 5)
=> 0.2
```
*/
abs = number: if number < 0 then -(number) else number;
/* Exponentiates the given base with the exponent.
Example:
/**
Exponentiates the given base with the exponent.
# Arguments
base
: The base value.
exponent
: The exponent value.
# Type
```
pow :: Integer -> Integer -> Integer
```
# Examples
```nix
pow 2 3
=> 8
pow 6 4
=> 1296
```
*/
pow = base: exponent:
# Just to be a contrarian, I'll just make this as a tail recursive function

176
lib/trivial.nix
View File

@ -1,36 +1,89 @@
{ pkgs, lib, self }:
rec {
/* Force a numerical value to be a floating value.
/**
Force a numerical value to be a floating value.
Example:
# Arguments
x
: The (numerical) value to be converted.
# Type
```
toFloat :: Number -> Float
```
# Examples
```nix
toFloat 5698
=> 5698.0
toFloat 9859.55
=> 9859.55
```
*/
toFloat = x: x / 1.0;
/* Count the attributes with the given predicate.
/**
Count the attributes with the given predicate.
Examples:
# Arguments
pred
: The predicate function to be used per-attribute key-value. Its expected
arguments are the attribute key and the attribute value in that order.
attrs
: The attribute set to be used.
# Type
```
countAttrs :: Function -> Attr -> Integer
```
# Examples
```nix
countAttrs (name: value: value) { d = true; f = true; a = false; }
=> 2
countAttrs (name: value: value.enable) { d = { enable = true; }; f = { enable = false; package = [ ]; }; }
=> 1
```
*/
countAttrs = pred: attrs:
lib.count (attr: pred attr.name attr.value)
(lib.mapAttrsToList lib.nameValuePair attrs);
/* Filters and groups the attribute set into two separate attribute where it
/**
Filters and groups the attribute set into two separate attribute where it
either accepted or denied from a given predicate function.
Example:
# Arguments
f
: The filter function to be used per-attribute. Its expected arguments are
the attribute key and the attribute value, in that order.
attrs
: The attribute set to be used.
# Type
```
filterAttrs :: Function -> Attr -> Attr
```
# Example
```nix
filterAttrs' (n: v: v == 4) { a = 4; b = 2; c = 6; }
=> { ok = { a = 4; }; notOk = { b = 2; c = 6; }; }
```
*/
filterAttrs' = f: attrs:
lib.foldlAttrs (acc: name: value:
@ -43,22 +96,52 @@ rec {
notOk = { };
} attrs;
/* Convenient function for converting bits to bytes.
/**
Convenient function for converting bits to bytes.
Example:
# Arguments
x
: An integer value expected to be the number of bits.
# Type
```
bitsToBytes :: Integer -> Integer
```
# Example
```nix
bitsToBytes 1600
=> 200
```
*/
bitsToBytes = x: x / 8.0;
/* Gives the exponent with the associated SI prefix.
/**
Gives the exponent with the associated SI prefix.
Example:
# Arguments
c
: The SI prefix itself.
# Type
```
SIPrefixExponent :: String -> Integer
```
# Example
```nix
SIPrefixExponent "M"
=> 6
SIPrefixExponent "Q"
=> 30
```
*/
SIPrefixExponent = c:
let
@ -90,28 +173,45 @@ rec {
};
in prefixes.${c};
/* Gives the multiplier for the metric units.
/**
Gives the multiplier for the metric units.
Example:
# Arguments
It has a similar argument to `foodogsquaredLib.trivial.SIPrefixExponent`.
# Examples
```nix
metricPrefixMultiplier "M"
=> 1000000
metricPrefixMultiplier "G"
=> 1000000000
```
*/
metricPrefixMultiplier = c: self.math.pow 10 (SIPrefixExponent c);
/* Gives the exponent with the associated binary prefix.
/**
Gives the exponent with the associated binary prefix.
As an implementation detail, we don't follow the proper IEC unit prefixes
and instead mapping this to the SI prefix for convenience.
Example:
# Arguments
Similar argument to `foodogsquaredLib.trivial.SIPrefixExponent` but only
for select SI prefixes instead.
# Examples
```nix
SIPrefixExponent "M"
=> 6
SIPrefixExponent "Q"
=> 30
```
*/
binaryPrefixExponent = c:
let
@ -127,22 +227,39 @@ rec {
};
in prefixes.${c};
/* Gives the multiplier for the given byte unit. Essentially returns the
/**
Gives the multiplier for the given byte unit. Essentially returns the
value in number of bytes.
Example:
# Argument
Similar argument to `foodogsquaredLib.trivial.binaryPrefixExponent`.
# Examples
```nix
binaryPrefixMultiplier "M"
=> 1048576
binaryPrefixMultiplier "G"
=> 1.099511628×10¹²
```
*/
binaryPrefixMultiplier = c: self.math.pow 2 (binaryPrefixExponent c);
/* Parse the given string containing the size into its appropriate value.
/**
Parse the given string containing the size into its appropriate value.
Returns the value in number of bytes.
Example:
# Arguments
str
: The string expecting to contain an integer and its suffix (e.g., `4GiB`,
`2 Mb`). Whitespace characters in between them is accepted.
# Examples
```nix
parseBytesSizeIntoInt "4GiB"
=> 4294967296
@ -151,6 +268,7 @@ rec {
parseBytesSizeIntoInt "2 Mb"
=> 250000
```
*/
parseBytesSizeIntoInt = str:
let
@ -169,14 +287,32 @@ rec {
bitDivider = if lib.hasSuffix "b" suffix then 8 else 1;
in numeral * multiplier / bitDivider;
/* Given an attrset of unit size object, return the size in bytes.
/**
Given an attrset of unit size object, return the size in bytes.
Example:
# Arguments
It is a sole attribute set with the following attributes:
size
: An integer value representing the numerical value of the unit.
prefix
: The SI prefix similar to `foodogsquaredLib.trivial.SIPrefixExponent`.
type
: Indicates the type of multiplier to be used. Only accepts `binary` and
`metric` as the value.
# Examples
```nix
unitsToInt { size = 4; prefix = "G"; type = "binary"; }
=> 4294967296
unitsToInt { size = 4; prefix = "G"; type = "metric"; }
=> 4000000000
```
*/
unitsToInt = { size, prefix, type ? "binary" }:
let