Mercurial > irccd

annotate man/irccd-api-directory.3 @ 1004:3ea3361f0fc7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
irccd: now track modes
author David Demelier <markand@malikania.fr>
date Tue, 16 Feb 2021 18:37:22 +0100
parents 0e11221c9bcc
children cf99df45cb84
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 .\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 .\" Permission to use, copy, modify, and/or distribute this software for any
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 .\" purpose with or without fee is hereby granted, provided that the above
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 .\" copyright notice and this permission notice appear in all copies.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 .Dd @IRCCD_MAN_DATE@
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 .Dt IRCCD-API-DIRECTORY 3
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 .Os
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 .\" NAME
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 .Sh NAME
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 .Nm Irccd.Directory
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 .Nd directory iteration and inspection API
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 .\" SYNOPSIS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 .Sh SYNOPSIS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 .Vt Irccd.Directory.Dot
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 .Vt Irccd.Directory.DotDot
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 .Vt Irccd.Directory.TypeDir
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 .Vt Irccd.Directory.TypeFile
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 .Vt Irccd.Directory.TypeLink
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 .Vt Irccd.Directory.TypeUnknown
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 .Fn Irccd.Directory "path, flags"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 .Fn Irccd.Directory.find "path, pattern, recursive = false"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 .Fn Irccd.Directory.mkdir "path, mode = 0700"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 .Fn Irccd.Directory.remove "path, recursive = false"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 .Fn Irccd.Directory.prototype.find "pattern, recursive"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 .Fn Irccd.Directory.prototype.remove "recursive = false"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 .\" DESCRIPTION
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 .Sh DESCRIPTION
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 This module can be used to iterate, find, remove or create directories.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 Use this module with care.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 .\" CONSTANTS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 .Sh CONSTANTS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 The following constants properties are defined:
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 .Bl -tag -width 18n
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 .It Va Dot No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 List "." directory.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 .It Va DotDot No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 List ".." directory.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 .It Va TypeDir No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 Entry is a directory.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 .It Va TypeFile No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 Entry is a file.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 .It Va TypeLink No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 Entry is a link.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 .It Va TypeUnknown No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 Unknown type file.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 .El
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 .\" METHODS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 .Sh METHODS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 .\" Irccd.Directory.find
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 .Fn Irccd.Directory.find
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 method finds an entry at root
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 .Fa path
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 by a pattern or a regular expression depending on the object
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 .Fa pattern .
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 The optional boolean argument
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 .Fa recursive
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 can be set to true to recursively find. Returns the path to the file if found.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 .\" Irccd.Directory.mkdir
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 .Fn Irccd.Directory.mkdir
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 method creates the directory
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 .Fa path
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 and all its parents.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 .\" Irccd.Directory.remove
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 .Fn Irccd.Directory.remove
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 method removes the directory
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 .Fa path
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 optionally recursively if boolean argument
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 .Fa recursive
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 is true.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 .\" Irccd.Directory [constructor]
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 .Fn Irccd.Directory
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 function constructor opens a directory at the given
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 .Fa path .
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 The optional
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 .Fa flags
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 argument is a bitwise integer containing either
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 .Vt Irccd.Directory.Dot , Irccd.Directory.DotDot
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 to respectively list directories
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 .Pa \&.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 and
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 .Pa .. .
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 When constructed successfully, the object has the following properties:
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 .Bl -tag -width 18n -offset indent -compact
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 .It Va path No (string)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 the path to the directory.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 .It Va entries No (array)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 an array for each entry. See below
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 .El
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 For each entry found, the array
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 .Va entries
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
113 contains as many objects with the following properties:
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 .Bl -tag -width 14n -offset indent-two -compact
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 .It Va name No (string)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 the base file name.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 .It Va type No (int)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 the type of file (Irccd.Directory.Type*).
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 .El
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 .\" Irccd.Directory.prototype.find
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 .Fn Irccd.Directory.prototype.find
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 method is the synonym of
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 .Fn Irccd.Directory.find
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 method but the path is taken from the directory object.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
128 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 .\" Irccd.Directory.prototype.remove
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
130 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 .Fn Irccd.Directory.prototype.remove
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 method is a synonym of
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 .Fn Irccd.Directory.remove
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
134 method but the path is taken from the directory object.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 .\" EXCEPTIONS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
136 .Sh EXCEPTIONS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 .Bl -tag -width 20n
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
138 .It Bq Er Irccd.SystemError
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 On I/O errors.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
140 .It Bq Er Error
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 On other errors.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 .El
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 .\" SEE ALSO
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
144 .Sh SEE ALSO
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 .Xr irccd-api 3