Mercurial > octave-antonio
annotate scripts/miscellaneous/dir.m @ 20164:df437a52bcaf stable
doc: Update more docstrings to have one sentence summary as first line.
Reviewed miscellaneous, sparse, strings in scripts directory.
* scripts/miscellaneous/bzip2.m, scripts/miscellaneous/citation.m,
scripts/miscellaneous/compare_versions.m, scripts/miscellaneous/computer.m,
scripts/miscellaneous/debug.m, scripts/miscellaneous/dir.m,
scripts/miscellaneous/edit.m, scripts/miscellaneous/error_ids.m,
scripts/miscellaneous/fileattrib.m, scripts/miscellaneous/fullfile.m,
scripts/miscellaneous/genvarname.m, scripts/miscellaneous/gzip.m,
scripts/miscellaneous/mkoctfile.m, scripts/miscellaneous/news.m,
scripts/miscellaneous/open.m, scripts/miscellaneous/parseparams.m,
scripts/miscellaneous/recycle.m, scripts/miscellaneous/run.m,
scripts/miscellaneous/swapbytes.m, scripts/miscellaneous/tar.m,
scripts/miscellaneous/tmpnam.m, scripts/miscellaneous/unpack.m,
scripts/miscellaneous/what.m, scripts/sparse/bicg.m, scripts/sparse/bicgstab.m,
scripts/sparse/cgs.m, scripts/sparse/colperm.m, scripts/sparse/eigs.m,
scripts/sparse/etreeplot.m, scripts/sparse/gmres.m, scripts/sparse/gplot.m,
scripts/sparse/ichol.m, scripts/sparse/ilu.m, scripts/sparse/pcg.m,
scripts/sparse/pcr.m, scripts/sparse/qmr.m, scripts/sparse/spaugment.m,
scripts/sparse/spconvert.m, scripts/sparse/spdiags.m, scripts/sparse/spfun.m,
scripts/sparse/spones.m, scripts/sparse/sprandsym.m, scripts/sparse/spstats.m,
scripts/sparse/spy.m, scripts/sparse/svds.m, scripts/sparse/treelayout.m,
scripts/sparse/treeplot.m, scripts/strings/base2dec.m,
scripts/strings/bin2dec.m, scripts/strings/blanks.m, scripts/strings/cstrcat.m,
scripts/strings/deblank.m, scripts/strings/dec2base.m,
scripts/strings/dec2bin.m, scripts/strings/dec2hex.m,
scripts/strings/findstr.m, scripts/strings/hex2dec.m, scripts/strings/index.m,
scripts/strings/isletter.m, scripts/strings/isstrprop.m,
scripts/strings/mat2str.m, scripts/strings/ostrsplit.m,
scripts/strings/regexptranslate.m, scripts/strings/rindex.m,
scripts/strings/str2num.m, scripts/strings/strcat.m, scripts/strings/strchr.m,
scripts/strings/strjoin.m, scripts/strings/strjust.m,
scripts/strings/strmatch.m, scripts/strings/strsplit.m,
scripts/strings/strtok.m, scripts/strings/strtrim.m,
scripts/strings/strtrunc.m, scripts/strings/substr.m,
scripts/strings/untabify.m, scripts/time/datenum.m:
Update more docstrings to have one sentence summary as first line.
| author | Rik <rik@octave.org> |
|---|---|
| date | Mon, 04 May 2015 14:22:02 -0700 |
| parents | 4197fc428c7d |
| children |
| rev | line source |
|---|---|
|
19697
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
19596
diff
changeset
|
1 ## Copyright (C) 2004-2015 John W. Eaton |
| 4694 | 2 ## |
| 3 ## This file is part of Octave. | |
| 4 ## | |
| 5 ## Octave is free software; you can redistribute it and/or modify it | |
| 6 ## under the terms of the GNU General Public License as published by | |
| 7016 | 7 ## the Free Software Foundation; either version 3 of the License, or (at |
| 8 ## your option) any later version. | |
| 4694 | 9 ## |
| 10 ## Octave is distributed in the hope that it will be useful, but | |
| 11 ## WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| 13 ## General Public License for more details. | |
| 14 ## | |
| 15 ## You should have received a copy of the GNU General Public License | |
| 7016 | 16 ## along with Octave; see the file COPYING. If not, see |
| 17 ## <http://www.gnu.org/licenses/>. | |
| 4694 | 18 |
| 19 ## -*- texinfo -*- | |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
20 ## @deftypefn {Function File} {} dir |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
21 ## @deftypefnx {Function File} {} dir (@var{directory}) |
| 4694 | 22 ## @deftypefnx {Function File} {[@var{list}] =} dir (@var{directory}) |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
23 ## Display file listing for directory @var{directory}. |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
24 ## |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
25 ## If @var{directory} is not specified then list the present working directory. |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
26 ## |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
27 ## If a return value is requested, return a structure array with the fields |
| 4694 | 28 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
29 ## @table @asis |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
30 ## @item name |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17908
diff
changeset
|
31 ## File or directory name. |
|
17513
fedcd3717ebc
doc: grammarcheck of documentation before 3.8 release.
Rik <rik@octave.org>
parents:
17397
diff
changeset
|
32 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
33 ## @item date |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
34 ## Timestamp of file modification (string value). |
|
17513
fedcd3717ebc
doc: grammarcheck of documentation before 3.8 release.
Rik <rik@octave.org>
parents:
17397
diff
changeset
|
35 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
36 ## @item bytes |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
37 ## File size in bytes. |
|
17513
fedcd3717ebc
doc: grammarcheck of documentation before 3.8 release.
Rik <rik@octave.org>
parents:
17397
diff
changeset
|
38 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
39 ## @item isdir |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17908
diff
changeset
|
40 ## True if name is a directory. |
|
17513
fedcd3717ebc
doc: grammarcheck of documentation before 3.8 release.
Rik <rik@octave.org>
parents:
17397
diff
changeset
|
41 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
42 ## @item datenum |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
43 ## Timestamp of file modification as serial date number (double). |
|
17513
fedcd3717ebc
doc: grammarcheck of documentation before 3.8 release.
Rik <rik@octave.org>
parents:
17397
diff
changeset
|
44 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
45 ## @item statinfo |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
46 ## Information structure returned from @code{stat}. |
|
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
47 ## @end table |
| 4694 | 48 ## |
|
17397
0bf2fc8562c9
doc: Update documentation for file and directory functions.
Rik <rik@octave.org>
parents:
17338
diff
changeset
|
49 ## If @var{directory} is a filename, rather than a directory, then return |
|
17908
7df8f5372ea8
doc: Add note about wildcard expansion in ls and dir functions (bug #40544).
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
50 ## information about the named file. @var{directory} may also be a list rather |
|
7df8f5372ea8
doc: Add note about wildcard expansion in ls and dir functions (bug #40544).
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
51 ## than a single directory or file. |
|
7df8f5372ea8
doc: Add note about wildcard expansion in ls and dir functions (bug #40544).
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
52 ## |
|
7df8f5372ea8
doc: Add note about wildcard expansion in ls and dir functions (bug #40544).
Rik <rik@octave.org>
parents:
17744
diff
changeset
|
53 ## @var{directory} is subject to shell expansion if it contains any wildcard |
| 19198 | 54 ## characters @samp{*}, @samp{?}, @samp{[]}. To find a literal example of a |
| 55 ## wildcard character the wildcard must be escaped using the backslash operator | |
| 56 ## @samp{\}. | |
| 6955 | 57 ## |
|
20164
df437a52bcaf
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
58 ## Note that for symbolic links, @code{dir} returns information about the |
|
df437a52bcaf
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
59 ## file that the symbolic link points to rather than the link itself. |
| 7007 | 60 ## However, if the link points to a nonexistent file, @code{dir} returns |
| 6955 | 61 ## information about the link. |
| 19198 | 62 ## @seealso{ls, readdir, glob, what, stat, lstat} |
| 4694 | 63 ## @end deftypefn |
| 64 | |
| 65 ## Author: jwe | |
| 66 | |
| 19198 | 67 ## FIXME: This is quite slow for large directories. |
| 68 ## Perhaps it should be converted to C++? | |
| 4694 | 69 |
|
11469
c776f063fefe
Overhaul m-script files to use common variable name between code and documentation.
Rik <octave@nomad.inbox5.com>
parents:
10793
diff
changeset
|
70 function retval = dir (directory) |
| 4694 | 71 |
| 5689 | 72 if (nargin == 0) |
|
11469
c776f063fefe
Overhaul m-script files to use common variable name between code and documentation.
Rik <octave@nomad.inbox5.com>
parents:
10793
diff
changeset
|
73 directory = "."; |
| 5689 | 74 elseif (nargin > 1) |
| 6046 | 75 print_usage (); |
| 4694 | 76 endif |
| 77 | |
| 19198 | 78 if (! ischar (directory)) |
| 79 error ("dir: DIRECTORY argument must be a string"); | |
| 80 endif | |
| 81 | |
| 5690 | 82 ## Prep the retval. |
| 6947 | 83 info = struct (zeros (0, 1), |
| 10549 | 84 {"name", "date", "bytes", "isdir", "datenum", "statinfo"}); |
| 5689 | 85 |
| 86 | |
| 19198 | 87 if (strcmp (directory, "*")) |
| 88 directory = "."; | |
| 89 endif | |
| 90 if (strcmp (directory, ".")) | |
| 91 flst = {"."}; | |
| 92 nf = 1; | |
| 93 else | |
| 94 flst = glob (directory); | |
| 95 nf = numel (flst); | |
| 96 endif | |
| 5689 | 97 |
| 19198 | 98 ## Determine the file list for the case where a single directory is specified. |
| 99 if (nf == 1) | |
| 100 fn = flst{1}; | |
| 101 [st, err, msg] = stat (fn); | |
| 102 if (err < 0) | |
| 103 warning ("dir: 'stat (%s)' failed: %s", fn, msg); | |
| 104 nf = 0; | |
| 105 elseif (S_ISDIR (st.mode)) | |
| 106 flst = readdir (flst{1}); | |
| 107 nf = numel (flst); | |
| 108 for i = 1:nf | |
| 109 flst{i} = fullfile (fn, flst{i}); | |
| 5689 | 110 endfor |
| 5690 | 111 endif |
| 19198 | 112 endif |
| 5689 | 113 |
| 19198 | 114 if (numel (flst) > 0) |
| 115 ## Collect results. | |
| 116 for i = nf:-1:1 | |
| 117 fn = flst{i}; | |
| 118 [st, err, msg] = lstat (fn); | |
| 119 if (err < 0) | |
| 120 warning ("dir: 'lstat (%s)' failed: %s", fn, msg); | |
| 121 else | |
| 122 ## If we are looking at a link that points to something, | |
| 123 ## return info about the target of the link, otherwise, return | |
| 124 ## info about the link itself. | |
| 125 if (S_ISLNK (st.mode)) | |
| 126 [xst, err, msg] = stat (fn); | |
| 127 if (! err) | |
| 128 st = xst; | |
| 129 endif | |
| 130 endif | |
| 131 [dummy, fn, ext] = fileparts (fn); | |
| 132 fn = [fn ext]; | |
| 133 info(i,1).name = fn; | |
| 134 lt = localtime (st.mtime); | |
| 135 info(i,1).date = strftime ("%d-%b-%Y %T", lt); | |
| 136 info(i,1).bytes = st.size; | |
| 137 info(i,1).isdir = S_ISDIR (st.mode); | |
| 138 info(i,1).datenum = datenum (lt.year + 1900, lt.mon + 1, lt.mday, | |
| 139 lt.hour, lt.min, lt.sec); | |
| 140 info(i,1).statinfo = st; | |
| 141 endif | |
| 142 endfor | |
| 5689 | 143 endif |
| 144 | |
| 5690 | 145 ## Return the output arguments. |
| 5689 | 146 if (nargout > 0) |
| 5690 | 147 ## Return the requested structure. |
| 5689 | 148 retval = info; |
| 19198 | 149 elseif (numel (info) > 0) |
| 5690 | 150 ## Print the structure to the screen. |
| 151 printf ("%s", list_in_columns ({info.name})); | |
| 5689 | 152 else |
|
15466
d174210ce1ec
use ' instead of ` in error messages, warnings and most comments
John W. Eaton <jwe@octave.org>
parents:
14327
diff
changeset
|
153 warning ("dir: nonexistent directory '%s'", directory); |
| 5689 | 154 endif |
| 155 | |
| 4694 | 156 endfunction |
|
17338
1c89599167a6
maint: End m-files with 1 blank line.
Rik <rik@octave.org>
parents:
16994
diff
changeset
|
157 |
| 19198 | 158 |
| 159 %!test | |
| 160 %! list = dir (); | |
| 161 %! assert (isstruct (list) && ! isempty (list)); | |
| 162 %! assert (fieldnames (list), | |
| 163 %! {"name"; "date"; "bytes"; "isdir"; "datenum"; "statinfo"}); | |
| 164 %! | |
| 165 %! if (isunix ()) | |
| 166 %! assert ({list(1:2).name}, {".", ".."}); | |
| 167 %! assert ([list(1:2).isdir], [true true]); | |
| 168 %! endif | |
| 169 %! | |
| 170 %! ## test that specifying a filename works the same as using a directory. | |
| 171 %! found = find (! [list.isdir], 1); | |
| 172 %! if (! isempty (found)) | |
| 173 %! list2 = dir (list(found).name); | |
| 174 %! assert (list(found), list2); | |
| 175 %! endif | |
| 176 | |
| 177 ## Test input validation | |
| 178 %!error <DIRECTORY argument must be a string> dir (1) | |
| 179 %!warning <nonexistent directory> dir ("_%UNLIKELY_DIR_NAME%_"); | |
| 180 |