talexander/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Docs: migrate format of comments to doc-comments

Browse Source
This commit is contained in:
Johannes Kirschbauer 2025-02-12 14:38:20 +07:00
parent 8e066cbb1d
commit 88f912da48
No known key found for this signature in database
9 changed files with 1199 additions and 478 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
lib/fileset/internal.nix
View File

@ -267,7 +267,7 @@ rec {
# Set all entries not present to null
mapAttrs (name: value: null) (readDir path) // value;
/*
/**
A normalisation of a filesetTree suitable filtering with `builtins.path`:
- Replace all directories that have no files with `null`.
This removes directories that would be empty
@ -276,7 +276,22 @@ rec {
Note that this function is strict, it evaluates the entire tree
Type: Path -> filesetTree -> filesetTree
# Inputs
`path`
: 1\. Function argument
`tree`
: 2\. Function argument
# Type
```
Path -> filesetTree -> filesetTree
```
*/
_normaliseTreeFilter =
path: tree:
@ -298,7 +313,7 @@ rec {
else
tree;
/*
/**
A minimal normalisation of a filesetTree, intended for pretty-printing:
- If all children of a path are recursively included or empty directories, the path itself is also recursively included
- If all children of a path are fully excluded or empty directories, the path itself is an empty directory
@ -307,7 +322,22 @@ rec {
Note that this function is partially lazy.
Type: Path -> filesetTree -> filesetTree (with "emptyDir"'s)
# Inputs
`path`
: 1\. Function argument
`tree`
: 2\. Function argument
# Type
```
Path -> filesetTree -> filesetTree (with "emptyDir"'s)
```
*/
_normaliseTreeMinimal =
path: tree:

11
lib/licenses.nix
View File

@ -24,9 +24,10 @@ let
in
lib.mapAttrs mkLicense ({
/* License identifiers from spdx.org where possible.
* If you cannot find your license here, then look for a similar license or
* add it to this list. The URL mentioned above is a good source for inspiration.
/**
License identifiers from spdx.org where possible.
If you cannot find your license here, then look for a similar license or
add it to this list. The URL mentioned above is a good source for inspiration.
*/
abstyles = {
@ -37,7 +38,9 @@ lib.mapAttrs mkLicense ({
acsl14 = {
fullName = "Anti-Capitalist Software License v1.4";
url = "https://anticapitalist.software/";
/* restrictions on corporations apply for both use and redistribution */
/**
restrictions on corporations apply for both use and redistribution
*/
free = false;
redistributable = false;
};

311
lib/modules.nix
View File

@ -74,14 +74,16 @@ let
decls
));
/* See https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules
/**
See https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules
or file://./../doc/module-system/module-system.chapter.md
!!! Please think twice before adding to this argument list! The more
that is specified here instead of in the modules themselves the harder
it is to transparently move a set of modules to be a submodule of another
config (as the proper arguments need to be replicated at each call to
evalModules) and the less declarative the module set is. */
evalModules) and the less declarative the module set is.
*/
evalModules = evalModulesArgs@
{ modules
, prefix ? []
@ -378,7 +380,7 @@ let
else
m: m;
/*
/**
Collects all modules recursively into the form
{
@ -459,12 +461,42 @@ let
in modulesPath: initialModules: args:
filterModules modulesPath (collectStructuredModules unknownModule "" initialModules args);
/* Wrap a module with a default location for reporting errors. */
/**
Wrap a module with a default location for reporting errors.
# Inputs
`file`
: 1\. Function argument
`m`
: 2\. Function argument
*/
setDefaultModuleLocation = file: m:
{ _file = file; imports = [ m ]; };
/* Massage a module into canonical form, that is, a set consisting
of ‘options’, ‘config’ and ‘imports’ attributes. */
/**
Massage a module into canonical form, that is, a set consisting
of ‘options’, ‘config’ and ‘imports’ attributes.
# Inputs
`file`
: 1\. Function argument
`key`
: 2\. Function argument
`m`
: 3\. Function argument
*/
unifyModuleSyntax = file: key: m:
let
addMeta = config: if m ? meta
@ -528,7 +560,8 @@ let
# works.
in f (args // extraArgs);
/* Merge a list of modules. This will recurse over the option
/**
Merge a list of modules. This will recurse over the option
declarations in all modules, combining them into a single set.
At the same time, for each option declaration, it will merge the
corresponding option definitions in all machines, returning them
@ -548,6 +581,17 @@ let
...
];
}
# Inputs
`prefix`
: 1\. Function argument
`modules`
: 2\. Function argument
*/
mergeModules = prefix: modules:
mergeModules' prefix modules
@ -740,7 +784,8 @@ let
in
throw (concatStringsSep "\n\n" paragraphs);
/* Merge multiple option declarations into a single declaration. In
/**
Merge multiple option declarations into a single declaration. In
general, there should be only one declaration of each option.
The exception is the ‘options’ attribute, which specifies
sub-options. These can be specified multiple times to allow one
@ -750,7 +795,19 @@ let
'loc' is the list of attribute names where the option is located.
'opts' is a list of modules. Each module has an options attribute which
correspond to the definition of 'loc' in 'opt.file'. */
correspond to the definition of 'loc' in 'opt.file'.
# Inputs
`loc`
: 1\. Function argument
`opts`
: 2\. Function argument
*/
mergeOptionDecls =
loc: opts:
foldl' (res: opt:
@ -819,8 +876,25 @@ let
} // typeSet
) { inherit loc; declarations = []; declarationPositions = []; options = []; } opts;
/* Merge all the definitions of an option to produce the final
config value. */
/**
Merge all the definitions of an option to produce the final
config value.
# Inputs
`loc`
: 1\. Function argument
`opt`
: 2\. Function argument
`defs`
: 3\. Function argument
*/
evalOptionValue = loc: opt: defs:
let
# Add in the default value for this option, if any.
@ -902,7 +976,8 @@ let
else {};
};
/* Given a config set, expand mkMerge properties, and push down the
/**
Given a config set, expand mkMerge properties, and push down the
other properties into the children. The result is a list of
config sets that do not have properties at top-level. For
example,
@ -916,6 +991,13 @@ let
This transform is the critical step that allows mkIf conditions
to refer to the full configuration without creating an infinite
recursion.
# Inputs
`cfg`
: 1\. Function argument
*/
pushDownProperties = cfg:
if cfg._type or "" == "merge" then
@ -927,7 +1009,8 @@ let
else # FIXME: handle mkOrder?
[ cfg ];
/* Given a config value, expand mkMerge properties, and discharge
/**
Given a config value, expand mkMerge properties, and discharge
any mkIf conditions. That is, this is the place where mkIf
conditions are actually evaluated. The result is a list of
config values. For example, ‘mkIf false x’ yields ‘[]’,
@ -936,6 +1019,13 @@ let
mkMerge [ 1 (mkIf true 2) (mkIf true (mkIf false 3)) ]
yields ‘[ 1 2 ]’.
# Inputs
`def`
: 1\. Function argument
*/
dischargeProperties = def:
if def._type or "" == "merge" then
@ -951,7 +1041,8 @@ let
else
[ def ];
/* Given a list of config values, process the mkOverride properties,
/**
Given a list of config values, process the mkOverride properties,
that is, return the values that have the highest (that is,
numerically lowest) priority, and strip the mkOverride
properties. For example,
@ -969,6 +1060,13 @@ let
]
Note that "z" has the default priority 100.
# Inputs
`defs`
: 1\. Function argument
*/
filterOverrides = defs: (filterOverrides' defs).values;
@ -982,9 +1080,18 @@ let
inherit highestPrio;
};
/* Sort a list of properties. The sort priority of a property is
/**
Sort a list of properties. The sort priority of a property is
defaultOrderPriority by default, but can be overridden by wrapping the property
using mkOrder. */
using mkOrder.
# Inputs
`defs`
: 1\. Function argument
*/
sortProperties = defs:
let
strip = def:
@ -1004,14 +1111,24 @@ let
else opt // { type = opt.type.substSubModules opt.options; options = []; };
/*
/**
Merge an option's definitions in a way that preserves the priority of the
individual attributes in the option value.
This does not account for all option semantics, such as readOnly.
Type:
# Inputs
`opt`
: 1\. Function argument
# Type
```
option -> attrsOf { highestPrio, value }
```
*/
mergeAttrDefinitionsWithPrio = opt:
let
@ -1038,7 +1155,20 @@ let
})
defsByAttr;
/* Properties. */
/**
Properties.
# Inputs
`condition`
: 1\. Function argument
`content`
: 2\. Function argument
*/
mkIf = condition: content:
{ _type = "if";
@ -1116,11 +1246,25 @@ let
mkAliasIfDef = option:
mkIf (isOption option && option.isDefined);
/* Compatibility. */
/**
Compatibility.
# Inputs
`modules`
: 1\. Function argument
`args`
: 2\. Function argument
*/
fixMergeModules = modules: args: evalModules { inherit modules args; check = false; };
/* Return a module that causes a warning to be shown if the
/**
Return a module that causes a warning to be shown if the
specified option is defined. For example,
mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "<replacement instructions>"
@ -1131,6 +1275,17 @@ let
how to achieve the same functionality without the removed option,
or alternatively a reasoning why the functionality is not needed.
replacementInstructions SHOULD be provided!
# Inputs
`optionName`
: 1\. Function argument
`replacementInstructions`
: 2\. Function argument
*/
mkRemovedOptionModule = optionName: replacementInstructions:
{ options, ... }:
@ -1148,7 +1303,8 @@ let
}];
};
/* Return a module that causes a warning to be shown if the
/**
Return a module that causes a warning to be shown if the
specified "from" option is defined; the defined value is however
forwarded to the "to" option. This can be used to rename options
while providing backward compatibility. For example,
@ -1160,6 +1316,17 @@ let
This also copies over the priority from the aliased option to the
non-aliased option.
# Inputs
`from`
: 1\. Function argument
`to`
: 2\. Function argument
*/
mkRenamedOptionModule = from: to: doRename {
inherit from to;
@ -1169,12 +1336,16 @@ let
};
mkRenamedOptionModuleWith = {
/* Old option path as list of strings. */
/**
Old option path as list of strings.
*/
from,
/* New option path as list of strings. */
/**
New option path as list of strings.
*/
to,
/*
/**
Release number of the first release that contains the rename, ignoring backports.
Set it to the upcoming release, matching the nixpkgs/.version file.
*/
@ -1188,7 +1359,8 @@ let
"Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'.";
};
/* Return a module that causes a warning to be shown if any of the "from"
/**
Return a module that causes a warning to be shown if any of the "from"
option is defined; the defined values can be used in the "mergeFn" to set
the "to" value.
This function can be used to merge multiple options into one that has a
@ -1215,6 +1387,21 @@ let
This show a warning if any a.b.c or d.e.f is set, and set the value of
x.y.z to the result of the merge function
# Inputs
`from`
: 1\. Function argument
`to`
: 2\. Function argument
`mergeFn`
: 3\. Function argument
*/
mkMergedOptionModule = from: to: mergeFn:
{ config, options, ... }:
@ -1240,7 +1427,8 @@ let
(mergeFn config)));
};
/* Single "from" version of mkMergedOptionModule.
/**
Single "from" version of mkMergedOptionModule.
Return a module that causes a warning to be shown if the "from" option is
defined; the defined value can be used in the "mergeFn" to set the "to"
value.
@ -1262,11 +1450,39 @@ let
This show a warning if a.b.c is set, and set the value of x.y.z to the
result of the change function
# Inputs
`from`
: 1\. Function argument
`to`
: 2\. Function argument
`changeFn`
: 3\. Function argument
*/
mkChangedOptionModule = from: to: changeFn:
mkMergedOptionModule [ from ] to changeFn;
/* Like ‘mkRenamedOptionModule’, but doesn't show a warning. */
/**
Like ‘mkRenamedOptionModule’, but doesn't show a warning.
# Inputs
`from`
: 1\. Function argument
`to`
: 2\. Function argument
*/
mkAliasOptionModule = from: to: doRename {
inherit from to;
visible = true;
@ -1274,13 +1490,15 @@ let
use = id;
};
/* Transitional version of mkAliasOptionModule that uses MD docs.
/**
Transitional version of mkAliasOptionModule that uses MD docs.
This function is no longer necessary and merely an alias of `mkAliasOptionModule`.
*/
mkAliasOptionModuleMD = mkAliasOptionModule;
/* mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b
/**
mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b
Create config definitions with the same priority as the definition of another option.
This should be used for option definitions where one option sets the value of another as a convenience.
@ -1288,6 +1506,17 @@ let
value using `mkDerivedConfig options.text (pkgs.writeText "filename.conf")`.
It takes care of setting the right priority using `mkOverride`.
# Inputs
`opt`
: 1\. Function argument
`f`
: 2\. Function argument
*/
# TODO: make the module system error message include information about `opt` in
# error messages about conflicts. E.g. introduce a variation of `mkOverride` which
@ -1300,7 +1529,7 @@ let
(opt.highestPrio or defaultOverridePriority)
(f opt.value);
/*
/**
Return a module that help declares an option that has been renamed.
When a value is defined for the old option, it is forwarded to the `to` option.
*/
@ -1450,18 +1679,34 @@ let
modulePath: staticArg:
lib.setDefaultModuleLocation modulePath (import modulePath staticArg);
/* Use this function to import a JSON file as NixOS configuration.
/**
Use this function to import a JSON file as NixOS configuration.
modules.importJSON :: path -> attrs
# Inputs
`file`
: 1\. Function argument
*/
importJSON = file: {
_file = file;
config = lib.importJSON file;
};
/* Use this function to import a TOML file as NixOS configuration.
/**
Use this function to import a TOML file as NixOS configuration.
modules.importTOML :: path -> attrs
# Inputs
`file`
: 1\. Function argument
*/
importTOML = file: {
_file = file;

4
lib/network/internal.nix
View File

@ -16,7 +16,7 @@ let
inherit (lib.lists) last;
/*
/**
IPv6 addresses are 128-bit identifiers. The preferred form is 'x:x:x:x:x:x:x:x',
where the 'x's are one to four hexadecimal digits of the eight 16-bit pieces of
the address. See RFC 4291.
@ -138,7 +138,7 @@ let
parseIpv6FromString = addr: parseExpandedIpv6 (expandIpv6 addr);
in
{
/*
/**
Internally, an IPv6 address is stored as a list of 16-bit integers with 8
elements. Wherever you see `IPv6` in internal functions docs, it means that
it is a list of integers produced by one of the internal parsers, such as

126
lib/options.nix
View File

@ -426,17 +426,28 @@ rec {
else if all isInt list && all (x: x == head list) list then head list
else throw "Cannot merge definitions of `${showOption loc}'. Definition values:${showDefs defs}";
/*
/**
Require a single definition.
WARNING: Does not perform nested checks, as this does not run the merge function!
*/
mergeOneOption = mergeUniqueOption { message = ""; };
/*
/**
Require a single definition.
NOTE: When the type is not checked completely by check, pass a merge function for further checking (of sub-attributes, etc).
# Inputs
`loc`
: 2\. Function argument
`defs`
: 3\. Function argument
*/
mergeUniqueOption = args@{
message,
@ -452,7 +463,20 @@ rec {
assert length defs > 1;
throw "The option `${showOption loc}' is defined multiple times while it's expected to be unique.\n${message}\nDefinition values:${showDefs defs}\n${prioritySuggestion}";
/* "Merge" option definitions by checking that they all have the same value. */
/**
"Merge" option definitions by checking that they all have the same value.
# Inputs
`loc`
: 1\. Function argument
`defs`
: 2\. Function argument
*/
mergeEqualOption = loc: defs:
if defs == [] then abort "This case should never happen."
# Return early if we only have one element
@ -465,23 +489,47 @@ rec {
else
first) (head defs) (tail defs)).value;
/* Extracts values of all "value" keys of the given list.
/**
Extracts values of all "value" keys of the given list.
Type: getValues :: [ { value :: a; } ] -> [a]
# Type
Example:
```
getValues :: [ { value :: a; } ] -> [a]
```
# Examples
:::{.example}
## `getValues` usage example
```nix
getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ] // => [ ]
```
:::
*/
getValues = map (x: x.value);
/* Extracts values of all "file" keys of the given list
/**
Extracts values of all "file" keys of the given list
Type: getFiles :: [ { file :: a; } ] -> [a]
# Type
Example:
```
getFiles :: [ { file :: a; } ] -> [a]
```
# Examples
:::{.example}
## `getFiles` usage example
```nix
getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ] // => [ ]
```
:::
*/
getFiles = map (x: x.file);
@ -530,7 +578,8 @@ rec {
[ docOption ] ++ optionals subOptionsVisible subOptions) (collect isOption options);
/* This function recursively removes all derivation attributes from
/**
This function recursively removes all derivation attributes from
`x` except for the `name` attribute.
This is to make the generation of `options.xml` much more
@ -540,6 +589,13 @@ rec {
This function was made obsolete by renderOptionValue and is kept for
compatibility with out-of-tree code.
# Inputs
`x`
: 1\. Function argument
*/
scrubOptionValue = x:
if isDerivation x then
@ -549,8 +605,16 @@ rec {
else x;
/* Ensures that the given option value (default or example) is a `_type`d string
/**
Ensures that the given option value (default or example) is a `_type`d string
by rendering Nix values to `literalExpression`s.
# Inputs
`v`
: 1\. Function argument
*/
renderOptionValue = v:
if v ? _type && v ? text then v
@ -560,10 +624,18 @@ rec {
} v);
/* For use in the `defaultText` and `example` option attributes. Causes the
/**
For use in the `defaultText` and `example` option attributes. Causes the
given string to be rendered verbatim in the documentation as Nix code. This
is necessary for complex values, e.g. functions, or values that depend on
other values or packages.
# Inputs
`text`
: 1\. Function argument
*/
literalExpression = text:
if ! isString text then throw "literalExpression expects a string."
@ -571,9 +643,17 @@ rec {
literalExample = lib.warn "lib.literalExample is deprecated, use lib.literalExpression instead, or use lib.literalMD for a non-Nix description." literalExpression;
/* For use in the `defaultText` and `example` option attributes. Causes the
/**
For use in the `defaultText` and `example` option attributes. Causes the
given MD text to be inserted verbatim in the documentation, for when
a `literalExpression` would be too hard to read.
# Inputs
`text`
: 1\. Function argument
*/
literalMD = text:
if ! isString text then throw "literalMD expects a string."
@ -581,10 +661,23 @@ rec {
# Helper functions.
/* Convert an option, described as a list of the option parts to a
/**
Convert an option, described as a list of the option parts to a
human-readable version.
Example:
# Inputs
`parts`
: 1\. Function argument
# Examples
:::{.example}
## `showOption` usage example
```nix
(showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
(showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
(showOption ["windowManager" "2bwm" "enable"]) == "windowManager.\"2bwm\".enable"
@ -593,6 +686,9 @@ rec {
(showOption ["foo" "*" "bar"]) == "foo.*.bar"
(showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"
(showOption ["foo" "<myPlaceholder>" "bar"]) == "foo.<myPlaceholder>.bar"
```
:::
*/
showOption = parts: let
# If the part is a named placeholder of the form "<...>" don't escape it.

229
lib/path/default.nix
View File

@ -165,7 +165,7 @@ in
# No rec! Add dependencies on this file at the top.
{
/*
/**
Append a subpath string to a path.
Like `path + ("/" + string)` but safer, because it errors instead of returning potentially surprising results.
@ -178,10 +178,28 @@ in
append p s == append p (subpath.normalise s)
Type:
append :: Path -> String -> Path
Example:
# Inputs
`path`
: The absolute path to append to
`subpath`
: The subpath string to append
# Type
```
append :: Path -> String -> Path
```
# Examples
:::{.example}
## `append` usage example
```nix
append /foo "bar/baz"
=> /foo/bar/baz
@ -206,6 +224,9 @@ in
=> <error>
append /foo "../bar"
=> <error>
```
:::
*/
append =
# The absolute path to append to
@ -219,7 +240,7 @@ in
${subpathInvalidReason subpath}'';
path + ("/" + subpath);
/*
/**
Whether the first path is a component-wise prefix of the second path.
Laws:
@ -228,10 +249,24 @@ in
- `hasPrefix` is a [non-strict partial order](https://en.wikipedia.org/wiki/Partially_ordered_set#Non-strict_partial_order) over the set of all path values.
Type:
hasPrefix :: Path -> Path -> Bool
Example:
# Inputs
`path1`
: 1\. Function argument
# Type
```
hasPrefix :: Path -> Path -> Bool
```
# Examples
:::{.example}
## `hasPrefix` usage example
```nix
hasPrefix /foo /foo/bar
=> true
hasPrefix /foo /foo
@ -240,6 +275,9 @@ in
=> false
hasPrefix /. /foo
=> true
```
:::
*/
hasPrefix =
path1:
@ -261,7 +299,7 @@ in
take (length path1Deconstructed.components) path2Deconstructed.components
== path1Deconstructed.components;
/*
/**
Remove the first path as a component-wise prefix from the second path.
The result is a [normalised subpath string](#function-library-lib.path.subpath.normalise).
@ -271,10 +309,24 @@ in
removePrefix p (append p s) == subpath.normalise s
Type:
removePrefix :: Path -> Path -> String
Example:
# Inputs
`path1`
: 1\. Function argument
# Type
```
removePrefix :: Path -> Path -> String
```
# Examples
:::{.example}
## `removePrefix` usage example
```nix
removePrefix /foo /foo/bar/baz
=> "./bar/baz"
removePrefix /foo /foo
@ -283,6 +335,9 @@ in
=> <error>
removePrefix /. /foo
=> "./foo"
```
:::
*/
removePrefix =
path1:
@ -310,7 +365,7 @@ in
second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
joinRelPath components;
/*
/**
Split the filesystem root from a [path](https://nixos.org/manual/nix/stable/language/values.html#type-path).
The result is an attribute set with these attributes:
- `root`: The filesystem root of the path, meaning that this directory has no parent directory.
@ -328,10 +383,24 @@ in
dirOf (splitRoot p).root == (splitRoot p).root
Type:
splitRoot :: Path -> { root :: Path, subpath :: String }
Example:
# Inputs
`path`
: The path to split the root off of
# Type
```
splitRoot :: Path -> { root :: Path, subpath :: String }
```
# Examples
:::{.example}
## `splitRoot` usage example
```nix
splitRoot /foo/bar
=> { root = /.; subpath = "./foo/bar"; }
@ -344,6 +413,9 @@ in
splitRoot "/foo/bar"
=> <error>
```
:::
*/
splitRoot =
# The path to split the root off of
@ -358,7 +430,7 @@ in
subpath = joinRelPath deconstructed.components;
};
/*
/**
Whether a [path](https://nixos.org/manual/nix/stable/language/values.html#type-path)
has a [store path](https://nixos.org/manual/nix/stable/store/store-path.html#store-path)
as a prefix.
@ -371,10 +443,24 @@ in
which occur when Nix files in the store use relative path expressions.
:::
Type:
hasStorePathPrefix :: Path -> Bool
Example:
# Inputs
`path`
: 1\. Function argument
# Type
```
hasStorePathPrefix :: Path -> Bool
```
# Examples
:::{.example}
## `hasStorePathPrefix` usage example
```nix
# Subpaths of derivation outputs have a store path as a prefix
hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo/bar/baz
=> true
@ -398,6 +484,9 @@ in
# Store derivations are also store paths themselves
hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo.drv
=> true
```
:::
*/
hasStorePathPrefix =
path:
@ -414,7 +503,7 @@ in
"lib.path.hasStorePathPrefix: Argument has a filesystem root (${toString deconstructed.root}) that's not /, which is currently not supported.";
componentsHaveStorePathPrefix deconstructed.components;
/*
/**
Whether a value is a valid subpath string.
A subpath string points to a specific file or directory within an absolute base directory.
@ -428,10 +517,24 @@ in
- The string doesn't contain any `..` path components.
Type:
subpath.isValid :: String -> Bool
Example:
# Inputs
`value`
: The value to check
# Type
```
subpath.isValid :: String -> Bool
```
# Examples
:::{.example}
## `subpath.isValid` usage example
```nix
# Not a string
subpath.isValid null
=> false
@ -455,12 +558,15 @@ in
# Doesn't need to be normalised
subpath.isValid "./foo//bar/"
=> true
```
:::
*/
subpath.isValid =
# The value to check
value: subpathInvalidReason value == null;
/*
/**
Join subpath strings together using `/`, returning a normalised subpath string.
Like `concatStringsSep "/"` but safer, specifically:
@ -492,10 +598,24 @@ in
ps != [] -> subpath.join ps == subpath.normalise (concatStringsSep "/" ps)
Type:
subpath.join :: [ String ] -> String
Example:
# Inputs
`subpaths`
: The list of subpaths to join together
# Type
```
subpath.join :: [ String ] -> String
```
# Examples
:::{.example}
## `subpath.join` usage example
```nix
subpath.join [ "foo" "bar/baz" ]
=> "./foo/bar/baz"
@ -516,6 +636,9 @@ in
=> <error>
subpath.join [ "../foo" ]
=> <error>
```
:::
*/
subpath.join =
# The list of subpaths to join together
@ -537,7 +660,7 @@ in
${subpathInvalidReason path}''
) 0 subpaths;
/*
/**
Split [a subpath](#function-library-lib.path.subpath.isValid) into its path component strings.
Throw an error if the subpath isn't valid.
Note that the returned path components are also [valid subpath strings](#function-library-lib.path.subpath.isValid), though they are intentionally not [normalised](#function-library-lib.path.subpath.normalise).
@ -548,10 +671,24 @@ in
subpath.join (subpath.components s) == subpath.normalise s
Type:
subpath.components :: String -> [ String ]
Example:
# Inputs
`subpath`
: The subpath string to split into components
# Type
```
subpath.components :: String -> [ String ]
```
# Examples
:::{.example}
## `subpath.components` usage example
```nix
subpath.components "."
=> [ ]
@ -560,6 +697,9 @@ in
subpath.components "/foo"
=> <error>
```
:::
*/
subpath.components =
# The subpath string to split into components
@ -569,7 +709,7 @@ in
${subpathInvalidReason subpath}'';
splitRelPath subpath;
/*
/**
Normalise a subpath. Throw an error if the subpath isn't [valid](#function-library-lib.path.subpath.isValid).
- Limit repeating `/` to a single one.
@ -602,10 +742,24 @@ in
builtins.tryEval (subpath.normalise p)).success == subpath.isValid p
Type:
subpath.normalise :: String -> String
Example:
# Inputs
`subpath`
: The subpath string to normalise
# Type
```
subpath.normalise :: String -> String
```
# Examples
:::{.example}
## `subpath.normalise` usage example
```nix
# limit repeating `/` to a single one
subpath.normalise "foo//bar"
=> "./foo/bar"
@ -641,6 +795,9 @@ in
# error on absolute path
subpath.normalise "/foo"
=> <error>
```
:::
*/
subpath.normalise =
# The subpath string to normalise

131
lib/sources.nix
View File

@ -18,10 +18,21 @@ let
pathIsRegularFile
;
/*
/**
A basic filter for `cleanSourceWith` that removes
directories of version control system, backup files (*~)
and some generated files.
# Inputs
`name`
: 1\. Function argument
`type`
: 2\. Function argument
*/
cleanSourceFilter =
name: type:
@ -52,11 +63,26 @@ let
(type == "unknown")
);
/*
/**
Filters a source tree removing version control files and directories using cleanSourceFilter.
Example:
# Inputs
`src`
: 1\. Function argument
# Examples
:::{.example}
## `cleanSource` usage example
```nix
cleanSource ./.
```
:::
*/
cleanSource =
src:
@ -65,12 +91,17 @@ let
inherit src;
};
/*
/**
Like `builtins.filterSource`, except it will compose with itself,
allowing you to chain multiple calls together without any
intermediate copies being put in the nix store.
Example:
# Examples
:::{.example}
## `cleanSourceWith` usage example
```nix
lib.cleanSourceWith {
filter = f;
src = lib.cleanSourceWith {
@ -82,6 +113,9 @@ let
builtins.filterSource f (builtins.filterSource g ./.)
# Fails!
```
:::
*/
cleanSourceWith =
{
@ -107,10 +141,21 @@ let
name = if name != null then name else orig.name;
};
/*
/**
Add logging to a source, for troubleshooting the filtering behavior.
Type:
# Inputs
`src`
: Source to debug. The returned source will behave like this source, but also log its filter invocations.
# Type
```
sources.trace :: sourceLike -> Source
```
*/
trace =
# Source to debug. The returned source will behave like this source, but also log its filter invocations.
@ -133,10 +178,30 @@ let
satisfiesSubpathInvariant = src ? satisfiesSubpathInvariant && src.satisfiesSubpathInvariant;
};
/*
/**
Filter sources by a list of regular expressions.
Example: src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]
# Inputs
`src`
: 1\. Function argument
`regexes`
: 2\. Function argument
# Examples
:::{.example}
## `sourceByRegex` usage example
```nix
src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]
```
:::
*/
sourceByRegex =
src: regexes:
@ -155,16 +220,38 @@ let
inherit src;
};
/*
/**
Get all files ending with the specified suffices from the given
source directory or its descendants, omitting files that do not match
any suffix. The result of the example below will include files like
`./dir/module.c` and `./dir/subdir/doc.xml` if present.
Type: sourceLike -> [String] -> Source
Example:
# Inputs
`src`
: Path or source containing the files to be returned
`exts`
: A list of file suffix strings
# Type
```
sourceLike -> [String] -> Source
```
# Examples
:::{.example}
## `sourceFilesBySuffices` usage example
```nix
sourceFilesBySuffices ./. [ ".xml" ".c" ]
```
:::
*/
sourceFilesBySuffices =
# Path or source containing the files to be returned
@ -183,10 +270,26 @@ let
pathIsGitRepo = path: (_commitIdFromGitRepoOrError path) ? value;
/*
/**
Get the commit id of a git repo.
Example: commitIdFromGitRepo <nixpkgs/.git>
# Inputs
`path`
: 1\. Function argument
# Examples
:::{.example}
## `commitIdFromGitRepo` usage example
```nix
commitIdFromGitRepo <nixpkgs/.git>
```
:::
*/
commitIdFromGitRepo =
path:

2
lib/strings-with-deps.nix
View File

@ -1,5 +1,5 @@
{ lib }:
/*
/**
Usage:
You define you custom builder script by adding all build steps to a list.

111
lib/versions.nix
View File

@ -3,62 +3,149 @@
rec {
/*
/**
Break a version string into its component parts.
Example:
# Examples
:::{.example}
## `splitVersion` usage example
```nix
splitVersion "1.2.3"
=> ["1" "2" "3"]
```
:::
*/
splitVersion = builtins.splitVersion;
/*
/**
Get the major version string from a string.
Example:
# Inputs
`v`
: 1\. Function argument
# Examples
:::{.example}
## `major` usage example
```nix
major "1.2.3"
=> "1"
```
:::
*/
major = v: builtins.elemAt (splitVersion v) 0;
/*
/**
Get the minor version string from a string.
Example:
# Inputs
`v`
: 1\. Function argument
# Examples
:::{.example}
## `minor` usage example
```nix
minor "1.2.3"
=> "2"
```
:::
*/
minor = v: builtins.elemAt (splitVersion v) 1;
/*
/**
Get the patch version string from a string.
Example:
# Inputs
`v`
: 1\. Function argument
# Examples
:::{.example}
## `patch` usage example
```nix
patch "1.2.3"
=> "3"
```
:::
*/
patch = v: builtins.elemAt (splitVersion v) 2;
/*
/**
Get string of the first two parts (major and minor)
of a version string.
Example:
# Inputs
`v`
: 1\. Function argument
# Examples
:::{.example}
## `majorMinor` usage example
```nix
majorMinor "1.2.3"
=> "1.2"
```
:::
*/
majorMinor = v: builtins.concatStringsSep "." (lib.take 2 (splitVersion v));
/*
/**
Pad a version string with zeros to match the given number of components.
Example:
# Inputs
`n`
: 1\. Function argument
`version`
: 2\. Function argument
# Examples
:::{.example}
## `pad` usage example
```nix
pad 3 "1.2"
=> "1.2.0"
pad 3 "1.3-rc1"
=> "1.3.0-rc1"
pad 3 "1.2.3.4"
=> "1.2.3"
```
:::
*/
pad =
n: version: