GopherProxy

	tREADME.md - clic - Clic is an command line interactive client for gopher writt…
	git clone git://bitreich.org/clic/ git://hg6vgqziawt5s4dj.onion/clic/
	Log
	Files
	Refs
	Tags
	LICENSE
	---
	tREADME.md (10361B)
	---
	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 implement…
	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 pa…
	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 `.…
	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 mai…
	28 Supported without serious issues are:
	29 ABCL, Allegro, CCL, CMUCL, CLASP, CLISP, ECL, LispWorks, MKCL, SBCL, S…
	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, cla…
	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 fun…
	40
	41 * [os](os.lisp):
	42 extracts information from your environment, including an ABI identifie…
	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 f…
	49 and a sensible, usable abstraction to specify relative pathnames.
	50 It has a function `merge-pathnames*` to use instead of `merge-pathname…
	51 even better, `subpathname` and its variant `subpathname*`; it has also…
	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 …
	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 debu…
	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 subproces…
	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 …
	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 libr…
	95 (i.e. ASDF internals that have leaked, ASDF-UTILS, or older versions o…
	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 …
	105
	106 All the exported functions, macros and variables ought to have proper do…
	107 If not, then it's a legitimate bug that we invite you to report.
	108
	109 Maybe some automated tool will extract all that information and
	110 make a webpage from it, at which point it would be nice to insert a link…
	111
	112 One tool with which you can extract all the documentation is HEΛP.
	113 At this time, the interface is not great: it isn't obvious at all that y…
	114 use a scrollbar on the right of the top left side panel to navigate the …
	115 once you click on the package you're interested in, you can see its defi…
	116
	117 * <http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELA…
	118
	119 Another automated documentation tool is quickdocs, but unhappily, at the…
	120 it only extracts information from the first package
	121 (see [bug #24](https://github.com/fukamachi/quickdocs/issues/24)):
	122
	123 * <http://quickdocs.org/uiop/api>
	124
	125
	126 Help wanted extracting working documentation from UIOP's docstrings.
	127
	128
	129 Using UIOP
	130 ----------
	131
	132 UIOP is part of ASDF 3, and any modern Common Lisp implementation
	133 will have all of UIOP available when you `(require "asdf")`.
	134 NB: `(require :asdf)` also works on all implementations but CLISP.
	135 Every implementation has sported ASDF 3 for years, and if yours only pro…
	136 ASDF 2, we recommend you install ASDF 3 on top of it,
	137 using the facility in [tools/install-asdf.lisp](../tools/install-asdf.li…
	138
	139 If you need some functionality only available in a recent version of UIO…
	140 but cannot or will not upgrade ASDF, UIOP is also distributed separately;
	141 see e.g. in Quicklisp. You may then have to load it like any other libra…
	142 by adding `"uiop"` or some versioned constraint `(:version "uiop" "3.2.0…
	143 in your system's `:depends-on` declaration, or at the REPL using:
	144
	145 (asdf:load-system :uiop)
	146
	147 When refering to symbols in UIOP, we recommend you either have your pack…
	148 `:use` the package `:uiop` or `:import-from` it, or that you shall use `…
	149 as a prefix to the symbols. Please DO NOT refer to specific subpackage…
	150 `uiop/run-program` from the outside of UIOP, because functions may occas…
	151 be moved from one internal package to the other, without notification.
	152 They have in the past and will in the future.
	153
	154
	155 When to use UIOP
	156 ----------------
	157
	158 UIOP is the ideal tool to use when:
	159
	160 * You need utilities that are always available,
	161 portably, with no installation needed.
	162 * You work in a cooperative environment, where the user is a developer
	163 who understands what he's doing and is trusted not to be malicious.
	164 * You are writing a build system, build tools, developer-facing tools.
	165 * You are writing bootstrap scripts, in which you cannot suppose
	166 that any third-party library has been installed (yet),
	167 much less a C compiler or any external tool.
	168 * You are trying to make existing Common Lisp code more robust and por…
	169 or replacing developer "scripts"
	170 (in shell, perl, python, ruby, js, and other blub languages)
	171 with Common Lisp code, but without concerns about
	172 either end-user usability or security
	173 (at the very least, you, not end-users, are fully controlling pathna…
	174 and filtering off or portably encoding any unusual character, etc.)
	175
	176 UIOP is the wrong tool when:
	177
	178 * You need to have total control on syscalls,
	179 to use special characters in pathnames, to handle symlinks yourself,
	180 or otherwise to have low-level system access.
	181 * You work in an adversarial environment, where some users are stupid,
	182 uneducated or outright malicious, and cannot be trusted not to try a…
	183 abuse the system with pathnames, symlinks, race conditions, etc.
	184 (or be tricked into it by attackers).
	185 * You are writing end-user facing tools that pass along user-provided
	186 pathnames, with bad usability implications if a user tries to use we…
	187 pathnames, or even security implications if an attackers crafts bad
	188 pathnames or filesystem setups.
	189
	190 In those latter cases, we recommend you use IOlib, or osicat,
	191 or some similar library that isn't as portable as UIOP,
	192 but provides fine-grained control over low-level system access.
	193 Also, please use extreme caution.
	194
	195
	196 Some history
	197 ------------
	198
	199 UIOP, formerly known as ASDF-DRIVER (the package and system nicknames are
	200 deprecated), evolved from ASDF 2's internal utilities and portability la…
	201 It has since fully superseded functionality from the following libraries:
	202 ASDF-UTILS (UIOP carries on the ASDF 2 utilities that this exported),
	203 CL-FAD (UIOP completely replaces it with better design and implementatio…
	204 CL-LAUNCH (UIOP took its image and command-line argument handling),
	205 EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER
	206 (UIOP's `run-program` and now `launch-program` evolved from XCVB-DRIVER,
	207 from which UIOP also initially got its condition muffling),
	208 SLIME's swank-loader (UIOP has better compilation and ABI identification…
	209 TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc.
	210
	211 UIOP also captures a large subset of the functionality from TRIVIAL-FEAT…
	212 and a small subset of the functionality from ALEXANDRIA or FARE-UTILS.
	213
	214 We recommend you use UIOP instead of any of the above, where applicable,
	215 since UIOP is more portable, more robust, more ubiquitous, better design…
	216 better documented, etc. If you see any way in which UIOP isn't superior,
	217 please tell us: we're interested in improving it so it become so.