f-shortdoc.el (14270B)
1 ;;; f-shortdoc.el --- Shortdoc for f.el -*- lexical-binding: t; no-byte-compile: t; -*- 2 3 ;; Author: Lucien Cartier-Tilet <lucien@phundrak.com> 4 ;; Maintainer: Lucien Cartier-Tilet <lucien@phundrak.com> 5 ;; Package-Requires: ((emacs "28.1")) 6 ;; Homepage: https://github.com/rejeep/f.el 7 8 ;; This file is not part of GNU Emacs 9 10 ;; This program is free software: you can redistribute it and/or modify 11 ;; it under the terms of the GNU General Public License as published by 12 ;; the Free Software Foundation, either version 3 of the License, or 13 ;; (at your option) any later version. 14 15 ;; This program is distributed in the hope that it will be useful, 16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 ;; GNU General Public License for more details. 19 20 ;; You should have received a copy of the GNU General Public License 21 ;; along with this program. If not, see <https://www.gnu.org/licenses/>. 22 23 24 ;;; Commentary: 25 26 ;; Shortdoc implementation for f.el 27 28 ;;; Code: 29 30 (when (version<= "28.1" emacs-version) 31 (require 'shortdoc) 32 33 (define-short-documentation-group f 34 "Paths" 35 (f-join 36 :eval (f-join "path") 37 :eval (f-join "path" "to") 38 :eval (f-join "/" "path" "to" "heaven") 39 :eval (f-join "path" "/to" "file")) 40 41 (f-split 42 :eval (f-split "path") 43 :eval (f-split "path/to") 44 :eval (f-split "/path/to/heaven") 45 :eval (f-split "~/back/to/earth")) 46 47 (f-expand 48 :no-eval (f-expand "name") 49 :result-string "/default/directory/name" 50 :no-eval (f-expand "name" "other/directory") 51 :result-string "other/directory/name") 52 53 (f-filename 54 :eval (f-filename "path/to/file.ext") 55 :eval (f-filename "path/to/directory")) 56 57 (f-dirname 58 :eval (f-dirname "path/to/file.ext") 59 :eval (f-dirname "path/to/directory") 60 :eval (f-dirname "/")) 61 62 (f-common-parent 63 :eval (f-common-parent '("foo/bar/baz" "foo/bar/qux" "foo/bar/mux")) 64 :eval (f-common-parent '("/foo/bar/baz" "/foo/bar/qux" "/foo/bax/mux")) 65 :eval (f-common-parent '("foo/bar/baz" "quack/bar/qux" "lack/bar/mux"))) 66 67 (f-ext 68 :eval (f-ext "path/to/file") 69 :eval (f-ext "path/to/file.txt") 70 :eval (f-ext "path/to/file.txt.org")) 71 72 (f-no-ext 73 :eval (f-no-ext "path/to/file") 74 :eval (f-no-ext "path/to/file.txt") 75 :eval (f-no-ext "path/to/file.txt.org")) 76 77 (f-swap-ext 78 :eval (f-swap-ext "path/to/file.ext" "org")) 79 80 (f-base 81 :eval (f-base "path/to/file.ext") 82 :eval (f-base "path/to/directory")) 83 84 (f-relative 85 :eval (f-relative "/some/path/relative/to/my/file.txt" "/some/path/") 86 :eval (f-relative "/default/directory/my/file.txt")) 87 88 (f-short 89 :no-eval (f-short "/Users/foo/Code/on/macOS") 90 :result-string "~/Code/on/macOS" 91 :no-eval (f-short "/home/foo/Code/on/linux") 92 :result-string "~/Code/on/linux" 93 :eval (f-short "/path/to/Code/bar")) 94 95 (f-long 96 :eval (f-long "~/Code/bar") 97 :eval (f-long "/path/to/Code/bar")) 98 99 (f-canonical 100 :eval (f-canonical "/path/to/real/file") 101 :no-eval (f-canonical "/link/to/file") 102 :result-string "/path/to/real/file") 103 104 (f-slash 105 :no-eval (f-slash "/path/to/file") 106 :result-string "/path/to/file" 107 :no-eval (f-slash "/path/to/dir") 108 :result-string "/path/to/dir/" 109 :no-eval (f-slash "/path/to/dir/") 110 :result-string "/path/to/dir/") 111 112 (f-full 113 :eval (f-full "~/path/to/file") 114 :eval (f-full "~/path/to/dir") 115 :eval (f-full "~/path/to/dir/")) 116 117 (f-uniquify 118 :eval (f-uniquify '("/foo/bar" "/foo/baz" "/foo/quux")) 119 :eval (f-uniquify '("/foo/bar" "/www/bar" "/foo/quux")) 120 :eval (f-uniquify '("/foo/bar" "/www/bar" "/www/bar/quux")) 121 :eval (f-uniquify '("/foo/bar" "/foo/baz" "/home/www/bar" "/home/www/baz" "/var/foo" "/opt/foo/www/baz"))) 122 123 (f-uniquify-alist 124 :eval (f-uniquify-alist '("/foo/bar" "/foo/baz" "/foo/quux")) 125 :eval (f-uniquify-alist '("/foo/bar" "/www/bar" "/foo/quux")) 126 :eval (f-uniquify-alist '("/foo/bar" "/www/bar" "/www/bar/quux")) 127 :eval (f-uniquify-alist '("/foo/bar" "/foo/baz" "/home/www/bar" "/home/www/baz" "/var/foo" "/opt/foo/www/baz"))) 128 129 "I/O" 130 (f-read-bytes 131 :no-eval* (f-read-bytes "path/to/binary/data")) 132 133 (f-write-bytes 134 :no-eval* (f-write-bytes (unibyte-string 72 101 108 108 111 32 119 111 114 108 100) "path/to/binary/data")) 135 136 (f-append-bytes 137 :no-eval* (f-append-bytes "path/to/file" (unibyte-string 72 101 108 108 111 32 119 111 114 108 100))) 138 139 (f-read-text 140 :no-eval* (f-read-text "path/to/file.txt" 'utf-8) 141 :no-eval* (f-read "path/to/file.txt" 'utf-8)) 142 143 (f-write-text 144 :no-eval* (f-write-text "Hello world" 'utf-8 "path/to/file.txt") 145 :no-eval* (f-write "Hello world" 'utf-8 "path/to/file.txt")) 146 147 (f-append-text 148 :no-eval* (f-append-text "Hello world" 'utf-8 "path/to/file.txt") 149 :no-eval* (f-append "Hello world" 'utf-8 "path/to/file.txt")) 150 151 "Destructive" 152 (f-mkdir 153 :no-eval (f-mkdir "dir") 154 :result-string "creates /default/directory/dir" 155 :no-eval (f-mkdir "other" "dir") 156 :result-string "creates /default/directory/other/dir" 157 :no-eval (f-mkdir "/" "some" "path") 158 :result-string "creates /some/path" 159 :no-eval (f-mkdir "~" "yet" "another" "dir") 160 :result-string "creates ~/yet/another/dir") 161 162 (f-mkdir-full-path 163 :no-eval (f-mkdir-full-path "dir") 164 :result-string "creates /default/directory/dir" 165 :no-eval (f-mkdir-full-path "other/dir") 166 :result-string "creates /default/directory/other/dir" 167 :no-eval (f-mkdir-full-path "/some/path") 168 :result-string "creates /some/path" 169 :no-eval (f-mkdir-full-path "~/yet/another/dir") 170 :result-string "creates ~/yet/another/dir") 171 172 (f-delete 173 :no-eval* (f-delete "dir") 174 :no-eval* (f-delete "other/dir" t) 175 :no-eval* (f-delete "path/to/file.txt")) 176 177 (f-symlink 178 :no-eval* (f-symlink "path/to/source" "path/to/link")) 179 180 (f-move 181 :no-eval* (f-move "path/to/file.txt" "new-file.txt") 182 :no-eval* (f-move "path/to/file.txt" "other/path")) 183 184 (f-copy 185 :no-eval* (f-copy "path/to/file.txt" "new-file.txt") 186 :no-eval* (f-copy "path/to/dir" "other/dir")) 187 188 (f-copy-contents 189 :no-eval* (f-copy-contents "path/to/dir" "path/to/other/dir")) 190 191 (f-touch 192 :no-eval* (f-touch "path/to/existing/file.txt") 193 :no-eval* (f-touch "path/to/non/existing/file.txt")) 194 195 "Predicates" 196 (f-exists-p 197 :no-eval* (f-exists-p "path/to/file.txt") 198 :no-eval* (f-exists-p "path/to/dir")) 199 200 (f-directory-p 201 :no-eval* (f-directory-p "path/to/file.txt") 202 :no-eval* (f-directory-p "path/to/dir")) 203 204 (f-file-p 205 :no-eval* (f-file-p "path/to/file.txt") 206 :no-eval* (f-file-p "path/to/dir")) 207 208 (f-symlink-p 209 :no-eval* (f-symlink-p "path/to/file.txt") 210 :no-eval* (f-symlink-p "path/to/dir") 211 :no-eval* (f-symlink-p "path/to/link")) 212 213 (f-readable-p 214 :no-eval* (f-readable-p "path/to/file.txt") 215 :no-eval* (f-readable-p "path/to/dir")) 216 217 (f-writable-p 218 :no-eval* (f-writable-p "path/to/file.txt") 219 :no-eval* (f-writable-p "path/to/dir")) 220 221 (f-executable-p 222 :no-eval* (f-executable-p "path/to/file.txt") 223 :no-eval* (f-executable-p "path/to/dir")) 224 225 (f-absolute-p 226 :eval (f-absolute-p "path/to/dir") 227 :eval (f-absolute-p "/full/path/to/dir")) 228 229 (f-relative-p 230 :eval (f-relative-p "path/to/dir") 231 :eval (f-relative-p "/full/path/to/dir")) 232 233 (f-root-p 234 :eval (f-root-p "/") 235 :eval (f-root-p "/not/root")) 236 237 (f-ext-p 238 :eval (f-ext-p "path/to/file.el" "el") 239 :eval (f-ext-p "path/to/file.el" "txt") 240 :eval (f-ext-p "path/to/file.el") 241 :eval (f-ext-p "path/to/file")) 242 243 (f-same-p 244 :eval (f-same-p "foo.txt" "foo.txt") 245 :eval (f-same-p "foo/bar/../baz" "foo/baz") 246 :eval (f-same-p "/path/to/foo.txt" "/path/to/bar.txt")) 247 248 (f-parent-of-p 249 :no-eval (f-parent-of-p "/path/to" "/path/to/dir") 250 :result t 251 :no-eval (f-parent-of-p "/path/to/dir" "/path/to") 252 :result nil 253 :no-eval (f-parent-of-p "/path/to" "/path/to") 254 :result nil) 255 256 (f-child-of-p 257 :no-eval (f-child-of-p "/path/to" "/path/to/dir") 258 :result nil 259 :no-eval (f-child-of-p "/path/to/dir" "/path/to") 260 :result t 261 :no-eval (f-child-of-p "/path/to" "/path/to") 262 :result nil) 263 264 (f-ancestor-of-p 265 :no-eval (f-ancestor-of-p "/path/to" "/path/to/dir") 266 :result t 267 :no-eval (f-ancestor-of-p "/path" "/path/to/dir") 268 :result t 269 :no-eval (f-ancestor-of-p "/path/to/dir" "/path/to") 270 :result nil 271 :no-eval (f-ancestor-of-p "/path/to" "/path/to") 272 :result nil) 273 274 (f-descendant-of-p 275 :no-eval (f-descendant-of-p "/path/to/dir" "/path/to") 276 :result t 277 :no-eval (f-descendant-of-p "/path/to/dir" "/path") 278 :result t 279 :no-eval (f-descendant-of-p "/path/to" "/path/to/dir") 280 :result nil 281 :no-eval (f-descendant-of-p "/path/to" "/path/to") 282 :result nil) 283 284 (f-hidden-p 285 :eval (f-hidden-p "path/to/foo") 286 :eval (f-hidden-p ".path/to/foo") 287 :eval (f-hidden-p "path/.to/foo") 288 :eval (f-hidden-p "path/to/.foo") 289 :eval (f-hidden-p ".path/to/foo" 'any) 290 :eval (f-hidden-p "path/.to/foo" 'any) 291 :eval (f-hidden-p "path/to/.foo" 'any) 292 :eval (f-hidden-p ".path/to/foo" 'last) 293 :eval (f-hidden-p "path/.to/foo" 'last) 294 :eval (f-hidden-p "path/to/.foo" 'last)) 295 296 (f-empty-p 297 :no-eval (f-empty-p "/path/to/empty-file") 298 :result t 299 :no-eval (f-empty-p "/path/to/file-with-contents") 300 :result nil 301 :no-eval (f-empty-p "/path/to/empty-dir/") 302 :result t 303 :no-eval (f-empty-p "/path/to/dir-with-contents/") 304 :result nil) 305 306 (f-older-p 307 :no-eval (f-older-p "older-file.txt" "newer-file.txt") 308 :result t 309 :no-eval (f-older-p "newer-file.txt" "older-file.txt") 310 :result nil 311 :no-eval (f-older-p "same-time1.txt" "same-time2.txt") 312 :result nil) 313 314 (f-newer-p 315 :no-eval (f-newer-p "newer-file.txt" "older-file.txt") 316 :result t 317 :no-eval (f-newer-p "older-file.txt" "newer-file.txt") 318 :result nil 319 :no-eval (f-newer-p "same-time1.txt" "same-time2.txt") 320 :result nil) 321 322 (f-same-time-p 323 :no-eval (f-same-time-p "same-time1.txt" "same-time2.txt") 324 :result t 325 :no-eval (f-same-time-p "newer-file.txt" "older-file.txt") 326 :result nil 327 :no-eval (f-same-time-p "older-file.txt" "newer-file.txt") 328 :result nil) 329 330 "Stats" 331 (f-size 332 :no-eval* (f-size "path/to/file.txt") 333 :no-eval* (f-size "path/to/dir")) 334 335 (f-depth 336 :eval (f-depth "/") 337 :eval (f-depth "/var/") 338 :eval (f-depth "/usr/local/bin")) 339 340 (f-change-time 341 :no-eval (f-change-time "path/to/file.txt") 342 :result (25517 48756 26337 111000) 343 :no-eval (f-change-time "path/to/dir") 344 :result (25517 57887 344657 210000) 345 :no-eval (f-change-time "path/to/file.txt" t) 346 :result (1672330868026337111 . 1000000000) 347 :no-eval (f-change-time "path/to/dir" t) 348 :result (1672339999344657210 . 1000000000) 349 :no-eval (f-change-time "path/to/file.txt" 'seconds) 350 :result 1672330868 351 :no-eval (f-change-time "path/to/dir" 'seconds) 352 :result 1672339999) 353 354 (f-modification-time 355 :no-eval (f-modification-time "path/to/file.txt") 356 :result (25517 48756 26337 111000) 357 :no-eval (f-modification-time "path/to/dir") 358 :result (25517 57887 344657 210000) 359 :no-eval (f-modification-time "path/to/file.txt" t) 360 :result (1672330868026337111 . 1000000000) 361 :no-eval (f-modification-time "path/to/dir" t) 362 :result (1672339999344657210 . 1000000000) 363 :no-eval (f-modification-time "path/to/file.txt" 'seconds) 364 :result 1672330868 365 :no-eval (f-modification-time "path/to/dir" 'seconds) 366 :result 1672339999) 367 368 (f-access-time 369 :no-eval (f-access-time "path/to/file.txt") 370 :result (25517 48756 26337 111000) 371 :no-eval (f-access-time "path/to/dir") 372 :result (25517 57887 344657 210000) 373 :no-eval (f-access-time "path/to/file.txt" t) 374 :result (1672330868026337111 . 1000000000) 375 :no-eval (f-access-time "path/to/dir" t) 376 :result (1672339999344657210 . 1000000000) 377 :no-eval (f-access-time "path/to/file.txt" 'seconds) 378 :result 1672330868 379 :no-eval (f-access-time "path/to/dir" 'seconds) 380 :result 1672339999) 381 382 "Misc" 383 (f-this-file 384 :no-eval* (f-this-file)) 385 386 (f-path-separator 387 :eval (f-path-separator)) 388 389 (f-glob 390 :no-eval* (f-glob "path/to/*.el") 391 :no-eval* (f-glob "*.el" "path/to")) 392 393 (f-entries 394 :no-eval* (f-entries "path/to/dir") 395 :no-eval* (f-entries "path/to/dir" (lambda (file) (s-matches? "test" file))) 396 :no-eval* (f-entries "path/to/dir" nil t) 397 :no-eval* (f--entries "path/to/dir" (s-matches? "test" it))) 398 399 (f-directories 400 :no-eval* (f-directories "path/to/dir") 401 :no-eval* (f-directories "path/to/dir" (lambda (dir) (equal (f-filename dir) "test"))) 402 :no-eval* (f-directories "path/to/dir" nil t) 403 :no-eval* (f--directories "path/to/dir" (equal (f-filename it) "test"))) 404 405 (f-files 406 :no-eval* (f-files "path/to/dir") 407 :no-eval* (f-files "path/to/dir" (lambda (file) (equal (f-ext file) "el"))) 408 :no-eval* (f-files "path/to/dir" nil t) 409 :no-eval* (f--files "path/to/dir" (equal (f-ext it) "el"))) 410 411 (f-root 412 :eval (f-root)) 413 414 (f-traverse-upwards 415 :no-eval* (f-traverse-upwards 416 (lambda (path) 417 (f-exists? (f-expand ".git" path))) 418 start-path) 419 420 :no-eval* (f--traverse-upwards (f-exists? (f-expand ".git" it)) start-path)) 421 422 (f-with-sandbox 423 :no-eval (f-with-sandbox foo-path 424 (f-touch (f-expand "foo" foo-path))) 425 :no-eval (f-with-sandbox (list foo-path bar-path) 426 (f-touch (f-expand "foo" foo-path)) 427 (f-touch (f-expand "bar" bar-path))) 428 :no-eval (f-with-sandbox foo-path 429 (f-touch (f-expand "bar" bar-path)))))) ;; "Destructive operation outside sandbox" 430 431 (eval-when-compile 432 (when (version< emacs-version "28.1") 433 (warn "Emacs should not be compiling this file"))) 434 435 (provide 'f-shortdoc) 436 437 ;;; f-shortdoc.el ends here