marcuskammer/emacs.d
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
emacs.d/clones/lispcookbook.github.io/cl-cookbook/packages.html

317 lines
12 KiB
HTML
Raw Normal View History

Add clones websites
2022-08-02 12:34:59 +02:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for HTML5 for Linux version 5.2.0">
<title>Packages</title>
<meta charset="utf-8">
<meta name="description" content="A collection of examples of using Common Lisp">
<meta name="viewport" content=
"width=device-width, initial-scale=1">
<link rel="stylesheet" href=
"assets/style.css">
<script type="text/javascript" src=
"assets/highlight-lisp.js">
</script>
<script type="text/javascript" src=
"assets/jquery-3.2.1.min.js">
</script>
<script type="text/javascript" src=
"assets/jquery.toc/jquery.toc.min.js">
</script>
<script type="text/javascript" src=
"assets/toggle-toc.js">
</script>
<link rel="stylesheet" href=
"assets/github.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
</head>
<body>
<h1 id="title-xs"><a href="index.html">The Common Lisp Cookbook</a> &ndash; Packages</h1>
<div id="logo-container">
<a href="index.html">
<img id="logo" src="assets/cl-logo-blue.png"/>
</a>
<div id="searchform-container">
<form onsubmit="duckSearch()" action="javascript:void(0)">
<input id="searchField" type="text" value="" placeholder="Search...">
</form>
</div>
<div id="toc-container" class="toc-close">
<div id="toc-title">Table of Contents</div>
<ul id="toc" class="list-unstyled"></ul>
</div>
</div>
<div id="content-container">
<h1 id="title-non-xs"><a href="index.html">The Common Lisp Cookbook</a> &ndash; Packages</h1>
<!-- Announcement we can keep for 1 month or more. I remove it and re-add it from time to time. -->
<p class="announce">
📹 <a href="https://www.udemy.com/course/common-lisp-programming/?couponCode=6926D599AA-LISP4ALL">NEW! Learn Lisp in videos and support our contributors with this 40% discount.</a>
</p>
<p class="announce-neutral">
📕 <a href="index.html#download-in-epub">Get the EPUB and PDF</a>
</p>
<div id="content"
<p>See: <a href="http://www.flownet.com/gat/packages.pdf">The Complete Idiot’s Guide to Common Lisp Packages</a></p>
<h2 id="creating-a-package">Creating a package</h2>
<p>Here’s an example package definition. It takes a name, and you
probably want to <code>:use</code> the Common Lisp symbols and functions.</p>
<pre><code class="language-lisp">(defpackage :my-package
(:use :cl))
</code></pre>
<p>To start writing code for this package, go inside it:</p>
<pre><code class="language-lisp">(in-package :my-package)
</code></pre>
<h3 id="accessing-symbols-from-a-package">Accessing symbols from a package</h3>
<p>As soon as you have defined a package or loaded one (with Quicklisp,
or if it was defined as a dependency in your <code>.asd</code> system
definition), you can access its symbols with <code>package:a-symbol</code>, or
with a double colon if the symbol is not exported:
<code>package::non-exported-symbol</code>.</p>
<p>Now we can choose to import individual symbols to access them right
away, without the package prefix.</p>
<h3 id="importing-symbols-from-another-package">Importing symbols from another package</h3>
<p>You can import exactly the symbols you need with <code>:import-from</code>:</p>
<pre><code class="language-lisp">(defpackage :my-package
(:import-from :ppcre :regex-replace)
(:use :cl))
</code></pre>
<p>Sometimes, we see <code>(:import-from :ppcre)</code>, without an explicit
import. This helps people using ASDF’s <em>package inferred system</em>.</p>
<h3 id="about-use-ing-packages-being-a-bad-practice">About “use”-ing packages being a bad practice</h3>
<p><code>:use</code> is a well spread idiom. You could do:</p>
<pre><code class="language-lisp">(defpackage :my-package
(:use :cl :ppcre))
</code></pre>
<p>and now, <strong>all</strong> symbols that are exported by <code>cl-ppcre</code> (aka <code>ppcre</code>)
are available to use directly in your package. However, this should be
considered bad practice, unless you <code>use</code> another package of your
project that you control. Indeed, if the external package adds a
symbol, it could conflict with one of yours, or you could add one
which will hide the external symbol and you might not see a warning.</p>
<p>To quote <a href="https://gist.github.com/phoe/2b63f33a2a4727a437403eceb7a6b4a3">this thorough explanation</a> (a recommended read):</p>
<blockquote>
<p>USE is a bad idea in contemporary code except for internal packages that you fully control, where it is a decent idea until you forget that you mutate the symbol of some other package while making that brand new shiny DEFUN. USE is the reason why Alexandria cannot nowadays even add a new symbol to itself, because it might cause name collisions with other packages that already have a symbol with the same name from some external source.</p>
</blockquote>
<h2 id="list-all-symbols-in-a-package">List all Symbols in a Package</h2>
<p>Common Lisp provides some macros to iterate through the symbols of a
package. The two most interesting are:
<a href="http://www.lispworks.com/documentation/HyperSpec/Body/m_do_sym.htm"><code>DO-SYMBOLS</code> and <code>DO-EXTERNAL-SYMBOLS</code></a>. <code>DO-SYMBOLS</code> iterates over the
symbols accessible in the package and <code>DO-EXTERNAL-SYMBOLS</code> only iterates over
the external symbols (you can see them as the real package API).</p>
<p>To print all exported symbols of a package named “PACKAGE”, you can write:</p>
<pre><code class="language-lisp">(do-external-symbols (s (find-package "PACKAGE"))
(print s))
</code></pre>
<p>You can also collect all these symbols in a list by writing:</p>
<pre><code class="language-lisp">(let (symbols)
(do-external-symbols (s (find-package "PACKAGE"))
(push s symbols))
symbols)
</code></pre>
<p>Or you can do it with <a href="http://www.lispworks.com/documentation/HyperSpec/Body/06_a.htm"><code>LOOP</code></a>.</p>
<pre><code class="language-lisp">(loop for s being the external-symbols of (find-package "PACKAGE")
collect s)
</code></pre>
<h2 id="package-nickname">Package nickname</h2>
<h3 id="nickname-provided-by-packages">Nickname Provided by Packages</h3>
<p>When defining a package, it is trivial to give it a nickname for better user
experience. The following example is a snippet of <code>PROVE</code> package:</p>
<pre><code class="language-lisp">(defpackage prove
(:nicknames :cl-test-more :test-more)
(:export :run
:is
:ok)
</code></pre>
<p>Afterwards, a user may use nickname instead of the package name to refer to this
package. For example:</p>
<pre><code class="language-lisp">(prove:run)
(cl-test-more:is)
(test-more:ok)
</code></pre>
<p>Please note that although Common Lisp allows defining multiple nicknames for
one package, too many nicknames may bring maintenance complexity to the
users. Thus the nicknames shall be meaningful and straightforward. For
example:</p>
<pre><code class="language-lisp">(defpackage #:iterate
(:nicknames #:iter))
(defpackage :cl-ppcre
(:nicknames :ppcre)
</code></pre>
<h4 id="package-local-nicknames-pln">Package Local Nicknames (PLN)</h4>
<p>Sometimes it is handy to give a local name to an imported package to
save some typing, especially when the imported package does not
provide nice nicknames.</p>
<p>Many implementations (SBCL, CCL, ECL, Clasp, ABCL, ACL, LispWorks &gt;= 7.2…) support Package Local Nicknames (PLN).</p>
<pre><code class="language-lisp">(defpackage :mypackage
(:use :cl)
(:local-nicknames (:nickname :original-package-name)
(:alex :alexandria)
(:re :cl-ppcre)))
(in-package :mypackage)
;; You can use :nickname instead of :original-package-name
(nickname:some-function "a" "b")
</code></pre>
<p>The effect of <code>PLN</code> is totally within <code>mypackage</code> i.e. the <code>nickname</code> won’t work in other packages unless defined there too. So, you don’t have to worry about unintended package name clash in other libraries.</p>
<p>Another facility exists for adding nicknames to packages. The function <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rn_pkg.htm"><code>RENAME-PACKAGE</code></a> can be used to replace the name and nicknames of a package. But it’s use would mean that other libraries may not be able to access the package using the original name or nicknames. There is rarely any situation to use this. Use Package Local Nicknames instead.</p>
<h3 id="package-locks">Package locks</h3>
<p>The package <code>common-lisp</code> and SBCL internal implementation packages are locked
by default, including <code>sb-ext</code>.</p>
<p>In addition, any user-defined package can be declared to be locked so that it
cannot be modified by the user. Attempts to change its symbol table or
redefine functions which its symbols name result in an error.</p>
<p>More detailed information can be obtained from documents of
<a href="http://www.sbcl.org/manual/#Package-Locks">SBCL</a> and <a href="https://clisp.sourceforge.io/impnotes/pack-lock.html">CLisp</a>.</p>
<p>For example, if you try the following code:</p>
<pre><code class="language-lisp">(asdf:load-system :alexandria)
(rename-package :alexandria :alex)
</code></pre>
<p>You will get the following error (on SBCL):</p>
<pre><code>Lock on package ALEXANDRIA violated when renaming as ALEX while
in package COMMON-LISP-USER.
[Condition of type PACKAGE-LOCKED-ERROR]
See also:
SBCL Manual, Package Locks [:node]
Restarts:
0: [CONTINUE] Ignore the package lock.
1: [IGNORE-ALL] Ignore all package locks in the context of this operation.
2: [UNLOCK-PACKAGE] Unlock the package.
3: [RETRY] Retry SLIME REPL evaluation request.
4: [*ABORT] Return to SLIME's top level.
5: [ABORT] abort thread (#&lt;THREAD "repl-thread" RUNNING {10047A8433}&gt;)
...
</code></pre>
<p>If a modification is required anyway, a package named
<a href="https://www.cliki.net/CL-PACKAGE-LOCKS">cl-package-lock</a> can be used to ignore package locks. For
example:</p>
<pre><code class="language-lisp">(cl-package-locks:without-package-locks
(rename-package :alexandria :alex))
</code></pre>
<h2 id="see-also">See also</h2>
<ul>
<li><a href="https://gist.github.com/phoe/2b63f33a2a4727a437403eceb7a6b4a3">Package Local Nicknames in Common Lisp</a> article.</li>
</ul>
<p class="page-source">
Page source: <a href="https://github.com/LispCookbook/cl-cookbook/blob/master/packages.md">packages.md</a>
</p>
</div>
<script type="text/javascript">
// Don't write the TOC on the index.
if (window.location.pathname != "/cl-cookbook/") {
$("#toc").toc({
content: "#content", // will ignore the first h1 with the site+page title.
headings: "h1,h2,h3,h4"});
}
$("#two-cols + ul").css({
"column-count": "2",
});
$("#contributors + ul").css({
"column-count": "4",
});
</script>
<div>
<footer class="footer">
<hr/>
&copy; 2002&ndash;2021 the Common Lisp Cookbook Project
</footer>
</div>
<div id="toc-btn">T<br>O<br>C</div>
</div>
<script text="javascript">
HighlightLisp.highlight_auto({className: null});
</script>
<script type="text/javascript">
function duckSearch() {
var searchField = document.getElementById("searchField");
if (searchField && searchField.value) {
var query = escape("site:lispcookbook.github.io/cl-cookbook/ " + searchField.value);
window.location.href = "https://duckduckgo.com/?kj=b2&kf=-1&ko=1&q=" + query;
// https://duckduckgo.com/params
// kj=b2: blue header in results page
// kf=-1: no favicons
}
}
</script>
<script async defer data-domain="lispcookbook.github.io/cl-cookbook" src="https://plausible.io/js/plausible.js"></script>
</body>
</html>
Reference in a new issue Copy permalink