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