aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authormerakor <cem@ckyln.com>2021-03-24 05:22:12 +0000
committermerakor <cem@ckyln.com>2021-03-24 05:22:12 +0000
commitf603dd5b4139cc1e7b2127eb1b9fcfe82d5176ba (patch)
tree64fa2ffa543af3dc22e301f4346983043ef1d75b /docs
parente816cab6f5f4eaa0e63f7f0ce751cde0f96b5a4b (diff)
downloadcpt-f603dd5b4139cc1e7b2127eb1b9fcfe82d5176ba.tar.gz
docs: update
FossilOrigin-Name: 1830ef7f1ff3b725999ac81b9123fb7bf0c00ab3b6f82a0027bc24f87e04ba67
Diffstat (limited to 'docs')
-rw-r--r--docs/cpt.org39
-rw-r--r--docs/cpt.texi39
-rw-r--r--docs/cpt.txt20
3 files changed, 66 insertions, 32 deletions
diff --git a/docs/cpt.org b/docs/cpt.org
index 7f0982e..9ffa37a 100644
--- a/docs/cpt.org
+++ b/docs/cpt.org
@@ -910,22 +910,27 @@ This function was taken from [[https://github.com/ko1nksm/readlinkf][POSIX sh re
symbolic links until it reaches the actual file.
** TODO System Functions
-- [ ] Add description
+:PROPERTIES:
+:DESCRIPTION: Functions to manipulate your system
+:END:
*** =as_root()=
:PROPERTIES:
:DESCRIPTION: Run a command as the root user
:END:
-=as_root()= calls the rest of the arguments as a different user. Unless a =user=
+=as_root()= calls the rest of the arguments as a different user. Unless a ~$user~
environment variable is set, it will call the following arguments as the root
user. It supports the following programs for privilege escalation with the
following order:
-1. =sls=
+1. =ssu=
2. =sudo=
3. =doas=
4. =su=
+The program called for this operation can be overridden using the ~$CPT_SU~
+variable.
+
** TODO Package Functions
:PROPERTIES:
:DESCRIPTION: Manipulate, or query anything related to packages
@@ -973,23 +978,35 @@ This function checks whether a given package fits the proper package
specification. This function *does not return with failure, it exits outright*
if it fails.
-*** TODO =pkg_find()=
+*** =pkg_find()=
:PROPERTIES:
:DESCRIPTION: Query package locations
:END:
=pkg_find()= is the tool for searching packages. It accepts up to 3 arguments.
-- $1: Query :: This is the only mandatory argument. It accepts globbing, meaning
- that shell wildcards can be used in the query.
-- $2: Match :: If this exists =pkg_find()= will print every single match found
- in the search path. If it doesn't, =pkg_find()= will print the first match and
- exit.
-- $3: Type :: This is the argument to be passed to the =test= function. Unless
- this argument is given, it defaults to =-d=, which tests for directories.
+- $1: Query ::
+ This is the only mandatory argument. It accepts globbing, meaning that shell
+ wildcards can be used in the query.
+- $2: Match ::
+ If this exists =pkg_find()= will print every single match found in the search
+ path. If it doesn't, =pkg_find()= will print the first match and exit.
+- $3: Type ::
+ This is the argument to be passed to the =test= function. Unless this argument
+ is given, it defaults to =-d=, which tests for directories.
#+begin_src sh
+# Returns the first match of cpt
pkg_find cpt
+
+# Returns all matches of cpt
+pkg_find cpt all
+
+# Returns all globbed matches for cpt* (e.g. cpt and cpt-extra)
+pkg_find 'cpt*' all
+
+# Returns all matching cpt-* executables on user's PATH
+SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x
#+end_src
*** TODO =pkg_get_base()=
diff --git a/docs/cpt.texi b/docs/cpt.texi
index af309d2..af0fe5a 100644
--- a/docs/cpt.texi
+++ b/docs/cpt.texi
@@ -92,7 +92,7 @@ CPT Library
* Message functions:: Communicate to users
* Text functions:: Manipulate or check text
* Portability functions:: Functions to replace non-POSIX commands
-* System Functions::
+* System Functions:: Functions to manipulate your system
* Package Functions:: Manipulate, or query anything related to packages
Option parsing
@@ -803,7 +803,7 @@ package manager library.
* Message functions:: Communicate to users
* Text functions:: Manipulate or check text
* Portability functions:: Functions to replace non-POSIX commands
-* System Functions::
+* System Functions:: Functions to manipulate your system
* Package Functions:: Manipulate, or query anything related to packages
@end menu
@@ -1064,11 +1064,6 @@ symbolic links until it reaches the actual file.
@node System Functions
@section System Functions
-@itemize
-@item
-Add description
-@end itemize
-
@menu
* @samp{as_root()}:: Run a command as the root user
@end menu
@@ -1076,14 +1071,14 @@ Add description
@node @samp{as_root()}
@subsection @samp{as_root()}
-@samp{as_root()} calls the rest of the arguments as a different user. Unless a @samp{user}
+@samp{as_root()} calls the rest of the arguments as a different user. Unless a @code{$user}
environment variable is set, it will call the following arguments as the root
user. It supports the following programs for privilege escalation with the
following order:
@enumerate
@item
-@samp{sls}
+@samp{ssu}
@item
@samp{sudo}
@item
@@ -1092,6 +1087,9 @@ following order:
@samp{su}
@end enumerate
+The program called for this operation can be overridden using the @code{$CPT_SU}
+variable.
+
@node Package Functions
@section Package Functions
@@ -1147,19 +1145,28 @@ if it fails.
@table @asis
@item $1: Query
-This is the only mandatory argument. It accepts globbing, meaning
-that shell wildcards can be used in the query.
+This is the only mandatory argument. It accepts globbing, meaning that shell
+wildcards can be used in the query.
@item $2: Match
-If this exists @samp{pkg_find()} will print every single match found
-in the search path. If it doesn't, @samp{pkg_find()} will print the first match and
-exit.
+If this exists @samp{pkg_find()} will print every single match found in the search
+path. If it doesn't, @samp{pkg_find()} will print the first match and exit.
@item $3: Type
-This is the argument to be passed to the @samp{test} function. Unless
-this argument is given, it defaults to @samp{-d}, which tests for directories.
+This is the argument to be passed to the @samp{test} function. Unless this argument
+is given, it defaults to @samp{-d}, which tests for directories.
@end table
@example
+# Returns the first match of cpt
pkg_find cpt
+
+# Returns all matches of cpt
+pkg_find cpt all
+
+# Returns all globbed matches for cpt* (e.g. cpt and cpt-extra)
+pkg_find 'cpt*' all
+
+# Returns all matching cpt-* executables on user's PATH
+SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x
@end example
@node @samp{pkg_get_base()}
diff --git a/docs/cpt.txt b/docs/cpt.txt
index aec19d1..201dfd4 100644
--- a/docs/cpt.txt
+++ b/docs/cpt.txt
@@ -982,22 +982,22 @@ development manual for *Carbs Packaging Tools*. For development logs see
8.6 System Functions
~~~~~~~~~~~~~~~~~~~~
- - [ ] Add description
-
-
8.6.1 `as_root()'
-----------------
`as_root()' calls the rest of the arguments as a different
- user. Unless a `user' environment variable is set, it will call the
+ user. Unless a `$user' environment variable is set, it will call the
following arguments as the root user. It supports the following
programs for privilege escalation with the following order:
- 1. `sls'
+ 1. `ssu'
2. `sudo'
3. `doas'
4. `su'
+ The program called for this operation can be overridden using the
+ `$CPT_SU' variable.
+
8.7 Package Functions
~~~~~~~~~~~~~~~~~~~~~
@@ -1063,7 +1063,17 @@ development manual for *Carbs Packaging Tools*. For development logs see
directories.
,----
+ | # Returns the first match of cpt
| pkg_find cpt
+ |
+ | # Returns all matches of cpt
+ | pkg_find cpt all
+ |
+ | # Returns all globbed matches for cpt* (e.g. cpt and cpt-extra)
+ | pkg_find 'cpt*' all
+ |
+ | # Returns all matching cpt-* executables on user's PATH
+ | SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x
`----