Doc: {pkgs.writers.*} migrate doc-comments

This commit is contained in:
Johannes Kirschbauer 2024-09-14 18:51:20 +02:00
parent 79c40d1b73
commit 9d9decda25
No known key found for this signature in database

View File

@ -297,25 +297,36 @@ rec {
ln -s ${inner}/bin/${name} $out
'';
# Like writeScript but the first line is a shebang to bash
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeBash "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeBash "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScript but the first line is a shebang to bash
Can be called with or without extra arguments.
# Examples
:::{.example}
## Without arguments
```nix
writeBash "example" ''
echo hello world
''
```
## With arguments
```nix
writeBash "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeBash =
name: argsOrScript:
if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@ -323,46 +334,72 @@ rec {
else
makeScriptWriter { interpreter = "${lib.getExe pkgs.bash}"; } name argsOrScript;
# Like writeScriptBin but the first line is a shebang to bash
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeBashBin "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeBashBin "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScriptBin but the first line is a shebang to bash
Can be called with or without extra arguments.
## Examples
:::{.example}
## `pkgs.writers.writeBashBin` example without arguments
```nix
writeBashBin "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeBashBin` example with arguments
```nix
writeBashBin "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeBashBin = name: writeBash "/bin/${name}";
# Like writeScript but the first line is a shebang to dash
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeDash "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeDash "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScript but the first line is a shebang to dash
Can be called with or without extra arguments.
# Example
:::{.example}
## `pkgs.writers.writeDash` example without arguments
```nix
writeDash "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeDash` example with arguments
```nix
writeDash "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeDash =
name: argsOrScript:
if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@ -370,46 +407,73 @@ rec {
else
makeScriptWriter { interpreter = "${lib.getExe pkgs.dash}"; } name argsOrScript;
# Like writeScriptBin but the first line is a shebang to dash
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeDashBin "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeDashBin "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScriptBin but the first line is a shebang to dash
Can be called with or without extra arguments.
# Examples
:::{.example}
## `pkgs.writers.writeDashBin` without arguments
```nix
writeDashBin "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeDashBin` with arguments
```nix
writeDashBin "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeDashBin = name: writeDash "/bin/${name}";
# Like writeScript but the first line is a shebang to fish
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeFish "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeFish "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScript but the first line is a shebang to fish
Can be called with or without extra arguments.
:::{.example}
## `pkgs.writers.writeFish` without arguments
```nix
writeFish "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeFish` with arguments
```nix
writeFish "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeFish =
name: argsOrScript:
if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@ -426,36 +490,58 @@ rec {
check = "${lib.getExe pkgs.fish} --no-config --no-execute"; # syntax check only
} name argsOrScript;
# Like writeScriptBin but the first line is a shebang to fish
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeFishBin "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeFishBin "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScriptBin but the first line is a shebang to fish
Can be called with or without extra arguments.
# Examples
:::{.example}
## `pkgs.writers.writeFishBin` without arguments
```nix
writeFishBin "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeFishBin` with arguments
```nix
writeFishBin "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeFishBin = name: writeFish "/bin/${name}";
# writeHaskell takes a name, an attrset with libraries and haskell version (both optional)
# and some haskell source code and returns an executable.
#
# Example:
# writeHaskell "missiles" { libraries = [ pkgs.haskellPackages.acme-missiles ]; } ''
# import Acme.Missiles
#
# main = launchMissiles
# '';
/**
writeHaskell takes a name, an attrset with libraries and haskell version (both optional)
and some haskell source code and returns an executable.
# Examples
:::{.example}
## `pkgs.writers.writeHaskell` usage example
```nix
writeHaskell "missiles" { libraries = [ pkgs.haskellPackages.acme-missiles ]; } ''
import Acme.Missiles
main = launchMissiles
'';
```
:::
*/
writeHaskell =
name:
{
@ -480,28 +566,43 @@ rec {
inherit makeWrapperArgs strip;
} name;
# writeHaskellBin takes the same arguments as writeHaskell but outputs a directory (like writeScriptBin)
/**
writeHaskellBin takes the same arguments as writeHaskell but outputs a directory (like writeScriptBin)
*/
writeHaskellBin = name: writeHaskell "/bin/${name}";
# Like writeScript but the first line is a shebang to nu
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeNu "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeNu "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScript but the first line is a shebang to nu
Can be called with or without extra arguments.
# Examples
:::{.example}
## `pkgs.writers.writeNu` without arguments
```nix
writeNu "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeNu` with arguments
```nix
writeNu "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeNu =
name: argsOrScript:
if lib.isAttrs argsOrScript && !lib.isDerivation argsOrScript then
@ -511,29 +612,44 @@ rec {
else
makeScriptWriter { interpreter = "${lib.getExe pkgs.nushell} --no-config-file"; } name argsOrScript;
# Like writeScriptBin but the first line is a shebang to nu
#
# Can be called with or without extra arguments.
#
# Example without arguments:
# writeNuBin "example" ''
# echo hello world
# ''
#
# Example with arguments:
# writeNuBin "example"
# {
# makeWrapperArgs = [
# "--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
# ];
# }
# ''
# hello
# ''
/**
Like writeScriptBin but the first line is a shebang to nu
Can be called with or without extra arguments.
# Examples
:::{.example}
## `pkgs.writers.writeNuBin` without arguments
```nix
writeNuBin "example" ''
echo hello world
''
```
:::
:::{.example}
## `pkgs.writers.writeNuBin` with arguments
```nix
writeNuBin "example"
{
makeWrapperArgs = [
"--prefix" "PATH" ":" "${lib.makeBinPath [ pkgs.hello ]}"
];
}
''
hello
''
```
:::
*/
writeNuBin = name: writeNu "/bin/${name}";
# makeRubyWriter takes ruby and compatible rubyPackages and produces ruby script writer,
# If any libraries are specified, ruby.withPackages is used as interpreter, otherwise the "bare" ruby is used.
/**
makeRubyWriter takes ruby and compatible rubyPackages and produces ruby script writer,
If any libraries are specified, ruby.withPackages is used as interpreter, otherwise the "bare" ruby is used.
*/
makeRubyWriter =
ruby: rubyPackages: buildRubyPackages: name:
{
@ -552,19 +668,30 @@ rec {
}
) name;
# Like writeScript but the first line is a shebang to ruby
#
# Example:
# writeRuby "example" { libraries = [ pkgs.rubyPackages.git ]; } ''
# puts "hello world"
# ''
/**
Like writeScript but the first line is a shebang to ruby
# Examples
:::{.example}
## `pkgs.writers.writeRuby` usage example
```nix
writeRuby "example" { libraries = [ pkgs.rubyPackages.git ]; } ''
puts "hello world"
''
```
:::
*/
writeRuby = makeRubyWriter pkgs.ruby pkgs.rubyPackages buildPackages.rubyPackages;
writeRubyBin = name: writeRuby "/bin/${name}";
# makeLuaWriter takes lua and compatible luaPackages and produces lua script writer,
# which validates the script with luacheck at build time. If any libraries are specified,
# lua.withPackages is used as interpreter, otherwise the "bare" lua is used.
/**
makeLuaWriter takes lua and compatible luaPackages and produces lua script writer,
which validates the script with luacheck at build time. If any libraries are specified,
lua.withPackages is used as interpreter, otherwise the "bare" lua is used.
*/
makeLuaWriter =
lua: luaPackages: buildLuaPackages: name:
{
@ -587,26 +714,36 @@ rec {
}
) name;
# writeLua takes a name an attributeset with libraries and some lua source code and
# returns an executable (should also work with luajit)
#
# Example:
# writeLua "test_lua" { libraries = [ pkgs.luaPackages.say ]; } ''
# s = require("say")
# s:set_namespace("en")
#
# s:set('money', 'I have %s dollars')
# s:set('wow', 'So much money!')
#
# print(s('money', {1000})) -- I have 1000 dollars
#
# s:set_namespace("fr") -- switch to french!
# s:set('wow', "Tant d'argent!")
#
# print(s('wow')) -- Tant d'argent!
# s:set_namespace("en") -- switch back to english!
# print(s('wow')) -- So much money!
# ''
/**
writeLua takes a name an attributeset with libraries and some lua source code and
returns an executable (should also work with luajit)
# Examples
:::{.example}
## `pkgs.writers.writeLua` usage example
```nix
writeLua "test_lua" { libraries = [ pkgs.luaPackages.say ]; } ''
s = require("say")
s:set_namespace("en")
s:set('money', 'I have %s dollars')
s:set('wow', 'So much money!')
print(s('money', {1000})) -- I have 1000 dollars
s:set_namespace("fr") -- switch to french!
s:set('wow', "Tant d'argent!")
print(s('wow')) -- Tant d'argent!
s:set_namespace("en") -- switch back to english!
print(s('wow')) -- So much money!
''
```
:::
*/
writeLua = makeLuaWriter pkgs.lua pkgs.luaPackages buildPackages.luaPackages;
writeLuaBin = name: writeLua "/bin/${name}";
@ -632,16 +769,41 @@ rec {
writeRustBin = name: writeRust "/bin/${name}";
# writeJS takes a name an attributeset with libraries and some JavaScript sourcecode and
# returns an executable
#
# Example:
# writeJS "example" { libraries = [ pkgs.uglify-js ]; } ''
# var UglifyJS = require("uglify-js");
# var code = "function add(first, second) { return first + second; }";
# var result = UglifyJS.minify(code);
# console.log(result.code);
# ''
/**
writeJS takes a name an attributeset with libraries and some JavaScript sourcecode and
returns an executable
# Inputs
`name`
: 1\. Function argument
`attrs`
: 2\. Function argument
`content`
: 3\. Function argument
# Examples
:::{.example}
## `pkgs.writers.writeJS` usage example
```nix
writeJS "example" { libraries = [ pkgs.uglify-js ]; } ''
var UglifyJS = require("uglify-js");
var code = "function add(first, second) { return first + second; }";
var result = UglifyJS.minify(code);
console.log(result.code);
''
```
:::
*/
writeJS =
name:
{
@ -660,7 +822,9 @@ rec {
exec ${lib.getExe pkgs.nodejs} ${pkgs.writeText "js" content} "$@"
'';
# writeJSBin takes the same arguments as writeJS but outputs a directory (like writeScriptBin)
/**
writeJSBin takes the same arguments as writeJS but outputs a directory (like writeScriptBin)
*/
writeJSBin = name: writeJS "/bin/${name}";
awkFormatNginx = builtins.toFile "awkFormat-nginx.awk" ''
@ -685,14 +849,24 @@ rec {
gixy $out
'';
# writePerl takes a name an attributeset with libraries and some perl sourcecode and
# returns an executable
#
# Example:
# writePerl "example" { libraries = [ pkgs.perlPackages.boolean ]; } ''
# use boolean;
# print "Howdy!\n" if true;
# ''
/**
writePerl takes a name an attributeset with libraries and some perl sourcecode and
returns an executable
# Examples
:::{.example}
## `pkgs.writers.writePerl` usage example
```nix
writePerl "example" { libraries = [ pkgs.perlPackages.boolean ]; } ''
use boolean;
print "Howdy!\n" if true;
''
```
:::
*/
writePerl =
name:
{
@ -706,12 +880,39 @@ rec {
}
) name;
# writePerlBin takes the same arguments as writePerl but outputs a directory (like writeScriptBin)
/**
writePerlBin takes the same arguments as writePerl but outputs a directory (like writeScriptBin)
*/
writePerlBin = name: writePerl "/bin/${name}";
# makePythonWriter takes python and compatible pythonPackages and produces python script writer,
# which validates the script with flake8 at build time. If any libraries are specified,
# python.withPackages is used as interpreter, otherwise the "bare" python is used.
/**
makePythonWriter takes python and compatible pythonPackages and produces python script writer,
which validates the script with flake8 at build time. If any libraries are specified,
python.withPackages is used as interpreter, otherwise the "bare" python is used.
# Inputs
`python`
: 1\. Function argument
`pythonPackages`
: 2\. Function argument
`buildPythonPackages`
: 3\. Function argument
`name`
: 4\. Function argument
`attrs`
: 5\. Function argument
*/
makePythonWriter =
python: pythonPackages: buildPythonPackages: name:
{
@ -745,55 +946,89 @@ rec {
}
) name;
# writePyPy2 takes a name an attributeset with libraries and some pypy2 sourcecode and
# returns an executable
#
# Example:
# writePyPy2 "test_pypy2" { libraries = [ pkgs.pypy2Packages.enum ]; } ''
# from enum import Enum
#
# class Test(Enum):
# a = "success"
#
# print Test.a
# ''
/**
writePyPy2 takes a name an attributeset with libraries and some pypy2 sourcecode and
returns an executable
# Examples
:::{.example}
## `pkgs.writers.writePyPy2` usage example
```nix
writePyPy2 "test_pypy2" { libraries = [ pkgs.pypy2Packages.enum ]; } ''
from enum import Enum
class Test(Enum):
a = "success"
print Test.a
''
```
:::
*/
writePyPy2 = makePythonWriter pkgs.pypy2 pkgs.pypy2Packages buildPackages.pypy2Packages;
# writePyPy2Bin takes the same arguments as writePyPy2 but outputs a directory (like writeScriptBin)
/**
writePyPy2Bin takes the same arguments as writePyPy2 but outputs a directory (like writeScriptBin)
*/
writePyPy2Bin = name: writePyPy2 "/bin/${name}";
# writePython3 takes a name an attributeset with libraries and some python3 sourcecode and
# returns an executable
#
# Example:
# writePython3 "test_python3" { libraries = [ pkgs.python3Packages.pyyaml ]; } ''
# import yaml
#
# y = yaml.safe_load("""
# - test: success
# """)
# print(y[0]['test'])
# ''
/**
writePython3 takes a name an attributeset with libraries and some python3 sourcecode and
returns an executable
# Examples
:::{.example}
## `pkgs.writers.writePython3` usage example
```nix
writePython3 "test_python3" { libraries = [ pkgs.python3Packages.pyyaml ]; } ''
import yaml
y = yaml.safe_load("""
- test: success
""")
print(y[0]['test'])
''
```
:::
*/
writePython3 = makePythonWriter pkgs.python3 pkgs.python3Packages buildPackages.python3Packages;
# writePython3Bin takes the same arguments as writePython3 but outputs a directory (like writeScriptBin)
writePython3Bin = name: writePython3 "/bin/${name}";
# writePyPy3 takes a name an attributeset with libraries and some pypy3 sourcecode and
# returns an executable
#
# Example:
# writePyPy3 "test_pypy3" { libraries = [ pkgs.pypy3Packages.pyyaml ]; } ''
# import yaml
#
# y = yaml.safe_load("""
# - test: success
# """)
# print(y[0]['test'])
# ''
/**
writePyPy3 takes a name an attributeset with libraries and some pypy3 sourcecode and
returns an executable
# Examples
:::{.example}
## `pkgs.writers.writePyPy3` usage example
```nix
writePyPy3 "test_pypy3" { libraries = [ pkgs.pypy3Packages.pyyaml ]; } ''
import yaml
y = yaml.safe_load("""
- test: success
""")
print(y[0]['test'])
''
```
:::
*/
writePyPy3 = makePythonWriter pkgs.pypy3 pkgs.pypy3Packages buildPackages.pypy3Packages;
# writePyPy3Bin takes the same arguments as writePyPy3 but outputs a directory (like writeScriptBin)
/**
writePyPy3Bin takes the same arguments as writePyPy3 but outputs a directory (like writeScriptBin)
*/
writePyPy3Bin = name: writePyPy3 "/bin/${name}";
makeFSharpWriter =