README.md - clic - Clic is an command line interactive client for gopher written in Common LISP (HTM) git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/clic/ (DIR) Log (DIR) Files (DIR) Refs (DIR) Tags (DIR) README (DIR) LICENSE --- README.md (10734B) --- 1 UIOP, the Utilities for Implementation- and OS- Portability 2 =========================================================== 3 4 UIOP is the portability layer of ASDF. 5 It provides utilities that abstract over discrepancies between implementations, 6 between operating systems, and between what the standard provides and 7 what programmers actually need, to write portable Common Lisp programs. 8 9 It is organized by topic in many files, each of which defines its own package 10 according to its topic: e.g [pathname.lisp](pathname.lisp) 11 will define package `UIOP/PATHNAME` and contain utilities related to 12 the handling of pathname objects. 13 All exported symbols are reexported in a convenience package `UIOP`, 14 except for those from `UIOP/COMMON-LISP`. 15 We recommend package `UIOP` be used to access all the symbols. 16 17 The files that constitute UIOP are, in dependency loading order: 18 19 * [package](package.lisp): 20 deals with packages and their symbols, most notably including 21 `define-package`, a variant of `defpackage` capable of hot-upgrade, 22 or `symbol-call` and `find-symbol*` that are also useful for use in `.asd` 23 files before packages have been defined. 24 25 * [common-lisp](common-lisp.lisp): 26 lets you paper over various sub-standard implementations. 27 Big offenders are Corman, GCL, Genera, MCL, none of them regularly maintained. 28 Supported without serious issues are: 29 ABCL, Allegro, CCL, CMUCL, CLASP, CLISP, ECL, LispWorks, MKCL, SBCL, SCL, XCL. 30 31 * [utility](utility.lisp): 32 provides macros and functions that do not involve I/O; 33 it handles control-flow, (p)lists, characters, strings, functions, classes, 34 conditions, "stamps" (real number or boolean for +/- infinity), etc. 35 It also sports `uiop-debug`, a useful tool to help you debug programs. 36 37 * [version](version.lisp): 38 manages ASDF-style versioning and a related `with-deprecation` facility 39 to gracefully declare that users should stop using some deprecated functions. 40 41 * [os](os.lisp): 42 extracts information from your environment, including an ABI identifier, 43 features that distinguish Unix vs Windows, 44 `getenv`, `hostname`, `getcwd` and `chdir`, etc. 45 46 * [pathname](pathname.lisp): 47 overcomes the gruesome non-portability trap that are CL pathnames 48 (and their lovecraftian "logical" variant), offering a vast array of functions 49 and a sensible, usable abstraction to specify relative pathnames. 50 It has a function `merge-pathnames*` to use instead of `merge-pathnames`, or 51 even better, `subpathname` and its variant `subpathname*`; it has also plenty 52 of functions for dealing with pathnames being directory vs file, 53 physical vs logical, absolute vs relative, and more. 54 55 * [filesystem](filesystem.lisp): 56 provides portable access to the filesystem, inspecting it, 57 only using truename when desired, using native OS namestrings, 58 atomic file renaming, creating or deleting directories, etc. 59 60 * [stream](stream.lisp): 61 portably deals with `*stderr*` vs `*error-output*`, character encodings 62 (external formats), element types, safe `read`ing and `write`ing, 63 opening files, using temporary files, flushing output buffers, 64 providing `format`-like designators for streams, consuming or copying streams, 65 concatenating streams or files, copying files, etc. 66 67 * [image](image.lisp): 68 portably deals with images, dumping them, restoring from them, 69 registering hooks to run at suitable events in the image lifetime, 70 printing backtraces, handling fatal conditions, using or avoiding debug modes, 71 accessing command line arguments or quitting the process. 72 73 * [lisp-build](lisp-build.lisp): 74 portably compiles Common Lisp code, handles compilation results, 75 muffles uninteresting conditions, saves and restores deferred warnings, 76 runs hooks around compilation (to e.g. control optimizations or syntax), 77 identifies the pathname of the current file, combines FASLs, etc. 78 79 * [launch-program](launch-program.lisp): 80 semi-portably launches a program as an asynchronous external subprocess. 81 Available functionality may depend on the underlying implementation. 82 83 * [run-program](run-program.lisp): 84 fully portably runs a program as a synchronous external subprocess, 85 feed it input and capture its output. 86 Most implementations also allow interactive console subprocesses. 87 88 * [configuration](configuration.lisp): 89 portably locates and parses configuration files, using best practices to 90 define and validate syntax, search standard paths, 91 let users specify pathnames or pathname patterns, etc. 92 93 * [backward-driver](backward-driver.lisp): 94 provides backward-compatibility with earlier incarnations of this library 95 (i.e. ASDF internals that have leaked, ASDF-UTILS, or older versions of UIOP). 96 97 * [driver](driver.lisp): 98 reexports all the above utilities in a single package `UIOP`. 99 100 101 Documentation 102 ------------- 103 104 Each file starts with a package definition form that lists the exported symbols. 105 106 All the exported functions, macros and variables ought to have proper docstrings. 107 If not, then it's a legitimate bug that we invite you to report. 108 109 You can extract a manual from the docstrings 110 by running `make` in the directory `uiop/doc`. 111 112 Other automated tools may hopefully extract all that information and 113 make a webpage from it, at which point it would be nice to insert a link here. 114 But many tools fail to extract useful data. 115 116 Tools with which you can extract all the documentation include 117 [Declt](https://www.lrde.epita.fr/~didier/software/lisp/misc.php#declt) 118 and [HEΛP](http://helambdap.sourceforge.net/). 119 See the Quickref UIOP reference manual <https://quickref.common-lisp.net/uiop.html> 120 as extracted by Declt. 121 122 There is also a pre-extracted HEΛP documentation page 123 <http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html>. 124 Note however that the HEΛP interface is not very usable at this time: 125 it isn't obvious at all that you can indeed use a scrollbar 126 on the right of the top left side panel to navigate the many packages; 127 once you click on the package you're interested in, you can see its defined symbols. 128 129 Another automated documentation tool is quickdocs, but unhappily, at the time of this writing, 130 it only extracts information from the first package 131 (see [bug #24](https://github.com/fukamachi/quickdocs/issues/24)): 132 <http://quickdocs.org/uiop/api> 133 134 135 Using UIOP 136 ---------- 137 138 UIOP is part of ASDF 3, and any modern Common Lisp implementation 139 will have all of UIOP available when you `(require "asdf")`. 140 NB: `(require :asdf)` also works on all implementations but CLISP. 141 Every implementation has sported ASDF 3 for years, and if yours only provides 142 ASDF 2, we recommend you install ASDF 3 on top of it, 143 using the facility in [tools/install-asdf.lisp](../tools/install-asdf.lisp). 144 145 If you need some functionality only available in a recent version of UIOP, 146 but cannot or will not upgrade ASDF, UIOP is also distributed separately; 147 see e.g. in Quicklisp. You may then have to load it like any other library, 148 by adding `"uiop"` or some versioned constraint `(:version "uiop" "3.2.0")` 149 in your system's `:depends-on` declaration, or at the REPL using: 150 151 (asdf:load-system :uiop) 152 153 When refering to symbols in UIOP, we recommend you either have your package 154 `:use` the package `:uiop` or `:import-from` it, or that you shall use `uiop:` 155 as a prefix to the symbols. Please *DO NOT* refer to specific subpackages such as 156 `uiop/run-program` from the outside of UIOP, because functions may occasionally 157 be moved from one internal package to the other, without notification. 158 They have in the past and will in the future. 159 160 161 When to use UIOP 162 ---------------- 163 164 UIOP is the ideal tool to use when: 165 166 * You need utilities that are always available, 167 portably, with no installation needed. 168 * You work in a cooperative environment, where the user is a developer 169 who understands what he's doing and is trusted not to be malicious. 170 * You are writing a build system, build tools, developer-facing tools. 171 * You are writing bootstrap scripts, in which you cannot suppose 172 that any third-party library has been installed (yet), 173 much less a C compiler or any external tool. 174 * You are trying to make existing Common Lisp code more robust and portable, 175 or replacing developer "scripts" 176 (in shell, perl, python, ruby, js, and other blub languages) 177 with Common Lisp code, but without concerns about 178 either end-user usability or security 179 (at the very least, you, not end-users, are fully controlling pathnames, 180 and filtering off or portably encoding any unusual character, etc.) 181 182 UIOP is the wrong tool when: 183 184 * You need to have total control on syscalls, 185 to use special characters in pathnames, to handle symlinks yourself, 186 or otherwise to have low-level system access. 187 * You work in an adversarial environment, where some users are stupid, 188 uneducated or outright malicious, and cannot be trusted not to try and 189 abuse the system with pathnames, symlinks, race conditions, etc. 190 (or be tricked into it by attackers). 191 * You are writing end-user facing tools that pass along user-provided 192 pathnames, with bad usability implications if a user tries to use weird 193 pathnames, or even security implications if an attackers crafts bad 194 pathnames or filesystem setups. 195 196 In those latter cases, we recommend you use IOlib, or osicat, 197 or some similar library that isn't as portable as UIOP, 198 but provides fine-grained control over low-level system access. 199 Also, please use extreme caution. 200 201 202 Some history 203 ------------ 204 205 UIOP, formerly known as ASDF-DRIVER (the package and system nicknames are 206 deprecated), evolved from ASDF 2's internal utilities and portability layer. 207 It has since fully superseded functionality from the following libraries: 208 ASDF-UTILS (UIOP carries on the ASDF 2 utilities that this exported), 209 CL-FAD (UIOP completely replaces it with better design and implementation), 210 CL-LAUNCH (UIOP took its image and command-line argument handling), 211 EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER 212 (UIOP's `run-program` and now `launch-program` evolved from XCVB-DRIVER, 213 from which UIOP also initially got its condition muffling), 214 SLIME's swank-loader (UIOP has better compilation and ABI identification), 215 TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc. 216 217 UIOP also captures a large subset of the functionality from TRIVIAL-FEATURES, 218 and a small subset of the functionality from ALEXANDRIA or FARE-UTILS. 219 220 We recommend you use UIOP instead of any of the above, where applicable, 221 since UIOP is more portable, more robust, more ubiquitous, better designed, 222 better documented, etc. If you see any way in which UIOP isn't superior, 223 please tell us: we're interested in improving it so it become so.