From: Kevin M. Rosenberg Date: Mon, 9 Dec 2002 09:31:27 +0000 (+0000) Subject: r3585: *** empty log message *** X-Git-Tag: debian-2.11.0-2~241 X-Git-Url: http://git.kpe.io/?p=hyperobject.git;a=commitdiff_plain;h=26013f0c832eb9ca60310fab0dca0bed8c4a9061;hp=31bfe50a3006d439e073be4336e50aae98707eb1 r3585: *** empty log message *** --- diff --git a/doc/.cvsignore b/doc/.cvsignore new file mode 100755 index 0000000..6aed28e --- /dev/null +++ b/doc/.cvsignore @@ -0,0 +1,8 @@ +uffi.pdf +uffi.ps +uffi.tex +uffi.dvi +uffi.aux +uffi.log +uffi.out +html diff --git a/doc/COPYING.GFDL b/doc/COPYING.GFDL new file mode 100644 index 0000000..99ab861 --- /dev/null +++ b/doc/COPYING.GFDL @@ -0,0 +1,330 @@ + GNU Free Documentation License + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..782ae8b --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,107 @@ +# FILE IDENTIFICATION +# +# Name: Makefile +# Purpose: Makefile for the hyperobject hyperobject documentation +# Programer: Kevin M. Rosenberg +# Date Started: Mar 2002 +# +# CVS Id: $Id: Makefile,v 1.1 2002/12/09 09:31:27 kevin Exp $ +# +# This file, part of Hyperobject, is Copyright (c) 2002 by Kevin M. Rosenberg +# +# System variable to select catalog file +SYSTEM=debian +# SYSTEM=redhat + +# Nothing to configure beyond this point + +CATALOG=catalog.$(SYSTEM) + +# Custom DSSSL's +DSSSL_HTML=../dsssl/html/docbook.dsl +DSSSL_PRINT=dsssl/print/docbook.dsl + +DOCFILE_BASE_DEFAULT=hyperobject +DOCFILE_EXT_DEFAULT=sgml + +# Standard docfile processing + +ifndef DOCFILE_BASE +DOCFILE_BASE=${DOCFILE_BASE_DEFAULT} +endif + +ifndef DOCFILE_EXT +DOCFILE_EXT=${DOCFILE_EXT_DEFAULT} +endif + +DOCFILE=${DOCFILE_BASE}.${DOCFILE_EXT} +TEXFILE=${DOCFILE_BASE}.tex +PDFFILE=${DOCFILE_BASE}.pdf +PSFILE=${DOCFILE_BASE}.ps +DVIFILE=${DOCFILE_BASE}.dvi +TMPFILES=${DOCFILE_BASE}.aux ${DOCFILE_BASE}.out ${DOCFILE_BASE}.log +DOCFILES=$(shell echo *.sgml) + +.PHONY: all +all: html pdf + +.PHONY: dist +dist: html pdf + +.PHONY: doc +doc: html pdf + +CHECK=nsgmls -s -C ${CATALOG} || exit 1 + +.PHONY: check +check: + @$(CHECK) + +.PHONY: html +html: html.tar.gz + +html.tar.gz: $(DOCFILES) Makefile + @$(CHECK) + @( rm -rf html ; mkdir html; cd html ; jade -t sgml -c ../${CATALOG} -d ${DSSSL_HTML} ../${DOCFILE} > /dev/null; cp book1.html index.html; cd ..; GZIP='-9' tar czf html.tar.gz html) + +.PHONY: tex +tex: ${TEXFILE} + +${TEXFILE}: ${DOCFILES} + @$(CHECK) + @jade -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null + +.PHONY: pdf +pdf: ${PDFFILE} + +${PDFFILE}: ${DOCFILES} + @jade -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null + @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null + @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null + @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null + @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null + +.PHONY: dvi +dvi: ${DVIFILE} + +${DVIFILE}: ${TEXFILE} + @jadetex ${TEXFILE} > /dev/null + @jadetex ${TEXFILE} > /dev/null + @jadetex ${TEXFILE} > /dev/null + @jadetex ${TEXFILE} > /dev/null + +.PHONY: ps +ps: ${PSFILE} + +${PSFILE}: ${DVIFILE} + @dvips -o ${PSFILE} ${DVIFILE} > /dev/null + +.PHONY: clean +clean: + @rm -f *~ *.bak *.orig \#*\# .\#* texput.log + @rm -rf html ${PSFILE} + @rm -f ${TMPFILES} + @rm -f ${DVIFILE} ${TEXFILE} + +.PHONY: distclean +distclean: clean diff --git a/doc/appendix.sgml b/doc/appendix.sgml new file mode 100644 index 0000000..cf1b4cd --- /dev/null +++ b/doc/appendix.sgml @@ -0,0 +1,30 @@ + + + + Installation + + Download &uffi; + +You need to download the &uffi; package from its web +home. +You also need to have a copy of &asdf;. If you need a copy of +&asdf;, it is included in the + + CCLAN package. You can download +the file defsystem.lisp from the CVS +tree. + + + + Installation + + After downloading and installing &asdf;, simply + push the + directory containing &uffi; into + asdf:*central-registry* variable. Whenever you +want to load the &uffi; package, use the function + (asdf:oos 'asdf:load-op :uffi). + + + diff --git a/doc/bookinfo.sgml b/doc/bookinfo.sgml new file mode 100644 index 0000000..587a888 --- /dev/null +++ b/doc/bookinfo.sgml @@ -0,0 +1,71 @@ + + + + + &hyperobject; Reference Guide + + Kevin + M. + Rosenberg + + Heart Hospital of New Mexico +
+ kevin@rosenberg.net + 504 Elm Street N.E. + Albuquerque + New Mexico + 87102 +
+ + + + + $Id: bookinfo.sgml,v 1.1 2002/12/09 09:31:27 kevin Exp $ + File $Date: 2002/12/09 09:31:27 $ + + + 2002 + Kevin M. Rosenberg + + + + + The &hyperobject; package was designed and + written by Kevin M. Rosenberg. + + + + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with the no + Front-Cover Texts, and with no Back-Cover Texts. + A copy of the license is included in the &uffi; distribution. + + + + Allegro CL® is a registered + trademark of Franz Inc. + + + + Lispworks® is a registered + trademark of Xanalys Inc. + + + + Microsoft + Windows® is a registered trademark of + Microsoft Inc. + + + + Other brand or + product names are the registered trademarks or trademarks of + their respective holders. + + + + + diff --git a/doc/catalog.debian b/doc/catalog.debian new file mode 100644 index 0000000..e082e53 --- /dev/null +++ b/doc/catalog.debian @@ -0,0 +1,3 @@ +CATALOG /etc/sgml/docbook.cat +CATALOG /etc/sgml/docbook-dsssl.cat +DOCUMENT hyperobject.sgml diff --git a/doc/catalog.redhat b/doc/catalog.redhat new file mode 100644 index 0000000..1e8a521 --- /dev/null +++ b/doc/catalog.redhat @@ -0,0 +1,2 @@ +CATALOG /etc/sgml/sgml-docbook-4.1.cat +DOCUMENT hyperobject.sgml diff --git a/doc/design.sgml b/doc/design.sgml new file mode 100644 index 0000000..f4c3dcd --- /dev/null +++ b/doc/design.sgml @@ -0,0 +1,9 @@ + + + + Design + + Class Options + + + diff --git a/doc/dsssl/COPYRIGHT b/doc/dsssl/COPYRIGHT new file mode 100644 index 0000000..871b60b --- /dev/null +++ b/doc/dsssl/COPYRIGHT @@ -0,0 +1,5 @@ +These stylesheets are written and Copyright (c) 1999-2002 by Pierre +R. Mai. + +He has graciously placed them in the public domain without +restrictions. diff --git a/doc/dsssl/html/docbook.dsl b/doc/dsssl/html/docbook.dsl new file mode 100644 index 0000000..e0f1668 --- /dev/null +++ b/doc/dsssl/html/docbook.dsl @@ -0,0 +1,30 @@ + +]> + + + + +(element envar ($mono-seq$)) +(element symbol ($mono-seq$)) +(element type ($mono-seq$)) +(element errortype ($mono-seq$)) +(element returnvalue ($italic-mono-seq$)) +(define (book-titlepage-recto-elements) + (list (normalize "title") + (normalize "subtitle") + (normalize "graphic") + (normalize "corpauthor") + (normalize "authorgroup") + (normalize "author") + (normalize "editor") + (normalize "printhistory") + (normalize "copyright") + (normalize "abstract") + (normalize "legalnotice"))) +(define %use-id-as-filename% #t) +(define use-output-dir #t) + + + + diff --git a/doc/dsssl/print/docbook.dsl b/doc/dsssl/print/docbook.dsl new file mode 100644 index 0000000..a114d93 --- /dev/null +++ b/doc/dsssl/print/docbook.dsl @@ -0,0 +1,30 @@ + +]> + + + + +(element envar ($mono-seq$)) +(element symbol ($mono-seq$)) +(element type ($mono-seq$)) +(element errortype ($mono-seq$)) +(element returnvalue ($italic-mono-seq$)) +(define (book-titlepage-verso-elements) + (list (normalize "title") + (normalize "subtitle") + (normalize "corpauthor") + (normalize "authorgroup") + (normalize "author") + (normalize "editor") + (normalize "edition") + (normalize "pubdate") + (normalize "printhistory") + (normalize "copyright") + (normalize "abstract") + (normalize "legalnotice") + (normalize "revhistory"))) + + + + diff --git a/doc/glossary.sgml b/doc/glossary.sgml new file mode 100644 index 0000000..008ada1 --- /dev/null +++ b/doc/glossary.sgml @@ -0,0 +1,16 @@ + + + + + Foreign Function Interface + FFI) + + + + An interface to a C-compatible library. + + + + + + diff --git a/doc/hyperobject.sgml b/doc/hyperobject.sgml new file mode 100644 index 0000000..0763f7f --- /dev/null +++ b/doc/hyperobject.sgml @@ -0,0 +1,35 @@ + + +Hyperobject"> +UFFI"> +CLSQL"> +KMRCL"> +CMUCL"> +SBCL"> +SCL"> +Lispworks"> +OpenMCL"> +MCL"> +AllegroCL"> +ANSI Common Lisp"> +T"> +NIL"> +NULL"> +C"> +defsystem"> +ASDF"> + + + + + +]> + + +&bookinfo; +&preface; +&intro; +&design; +&ref; + diff --git a/doc/intro.sgml b/doc/intro.sgml new file mode 100644 index 0000000..6a9e666 --- /dev/null +++ b/doc/intro.sgml @@ -0,0 +1,73 @@ + + + + Introduction + + Purpose + This reference guide describes + &hyperobject;, which provides an object representation + library for Common Lisp programs. + + + + + Supported Implementations + The primary tested and supported platforms for &hyperobject; are: + + + &acl; v6.2 + &lw; v4.2 + &cmucl; 18d + &sbcl; 0.7.10 + &scl; 1.1.1 + + + + + Installation + + Download + +You need to download the &hyperobject; package from its web +home. +Other require packages are: + +&kmrcl; from it's home. +&uffi; from it's home. +&clsql; from it's home. +&asdf; from it's home CCLAN package. You can download +the file asdf.lisp from the CVS +tree. + + + + + Loading + + After downloading and installing &asdf;, simply + push the + directories containing &hyperobject;, &kmrcl;, &uffi;, and &clsql; onto + asdf:*central-registry* variable. Whenever you +want to load the &hyperobject; package, use the function + (asdf:oos 'asdf:load-op :hyperobject). + + + + + + Design + + Overview + + &hyperobject; was designed as a cross-implementation + compatible Foreign Function Interface. + Necessarily, + only a common subset of functionality can be + provided. Likewise, not every optimization for that a specific + implementation provides can be supported. Wherever possible, + though, implementation-specific optimizations are invoked. + + + + + diff --git a/doc/preface.sgml b/doc/preface.sgml new file mode 100644 index 0000000..16ed906 --- /dev/null +++ b/doc/preface.sgml @@ -0,0 +1,8 @@ + + + + Preface + This reference guide describes the usage and features + of &hyperobject;. + + diff --git a/doc/ref.sgml b/doc/ref.sgml new file mode 100644 index 0000000..f299c19 --- /dev/null +++ b/doc/ref.sgml @@ -0,0 +1,2218 @@ + + + + + Declarations + + + + Overview + Declarations are used to give the compiler optimizing + information about foreign types. Currently, only &cmucl; + supports declarations. On &acl; and &lw;, these expressions + declare the type generically as &t; + + + + + + + def-type + Defines a Common Lisp type. + + Macro + + + Syntax + + def-type name type + + + + Arguments and Values + + + name + + A symbol naming the type + + + + type + + A form that is evaluated that specifies the &uffi; type. + + + + + + + Description + Defines a Common Lisp type based on a &uffi; type. + + + + Examples + +(def-type char-ptr '(* :char)) +... +(defun foo (ptr) + (declare (type char-ptr ptr)) + ... + + + + Side Effects + Defines a new &cl; type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + Primitive Types + + Overview + + Primitive types have a single value, these include + characters, numbers, and pointers. They are all symbols in + the keyword package. + + + + :char - Signed 8-bits. A +dereferenced :char pointer returns an character. + + + :unsigned-char - Unsigned 8-bits. A dereferenced :unsigned-char +pointer returns an character. + + + :byte - Signed 8-bits. A +dereferenced :byte pointer returns an integer. + + + :unsigned-byte - Unsigned 8-bits. A +dereferenced :unsigned-byte pointer returns an integer. + + + :short - Signed 16-bits. + + + :unsigned-short - Unsigned 16-bits. + + + :int - Signed 32-bits. + + + :unsigned-int - Unsigned 32-bits. + + + :long - Signed 32-bits. + + + :unsigned-long - Unsigned 32-bits. + + + :float - 32-bit floating point. + + + :double - 64-bit floating point. + + + :cstring - +A &null; terminated string used for passing and returning characters strings with a &c; function. + + + + :void - +The absence of a value. Used to indicate that a function does not return a value. + + + :pointer-void - +Points to a generic object. + + + * - Used to declare a pointer to an object + + + + + + + def-constant + Binds a symbol to a constant. + + Macro + + + Syntax + + def-constant name value &key export + + + + Arguments and Values + + + name + + A symbol that will be bound to the value. + + + + + value + + An evaluated form that is bound the the name. + + + + + export + + When &t;, the name is exported from the current package. The default is &nil; + + + + + + Description + + This is a thin wrapper around + defconstant. It evaluates at + compile-time and optionally exports the symbol from the package. + + + + Examples + +(def-constant pi2 (* 2 pi)) +(def-constant exported-pi2 (* 2 pi) :export t) + + + + Side Effects + Creates a new special variable.. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + def-foreign-type + Defines a new foreign type. + + Macro + + + Syntax + + def-foreign-type name type + + + + Arguments and Values + + + name + + A symbol naming the new foreign type. + + + + + value + + A form that is not evaluated that defines the new +foreign type. + + + + + + + Description + Defines a new foreign type. + + + + Examples + +(def-foreign-type my-generic-pointer :pointer-void) +(def-foreign-type a-double-float :double-float) +(def-foreign-type char-ptr (* :char)) + + + + Side Effects + Defines a new foreign type. + + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + null-char-p + Tests a character for &null; value. + + Macro + + + Syntax + + null-char-p char => is-null + + + + Arguments and Values + + + char + + A character or integer. + + + + + is-null + + A boolean flag indicating if char is a &null; value. + + + + + + + Description + + A predicate testing if a character or integer is &null;. This +abstracts the difference in implementations where some return a +character and some return a +integer whence dereferencing a +C character pointer. + + + + Examples + +(def-array-pointer ca :unsigned-char) +(let ((fs (convert-to-foreign-string "ab"))) + (values (null-char-p (deref-array fs 'ca 0)) + (null-char-p (deref-array fs 'ca 2)))) +=> &nil; + &t; + + + + Side Effects + None. + + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + Aggregate Types + + Overview + + Aggregate types are comprised of one or more primitive types. + + + + + + def-enum + Defines a &c; enumeration. + + Macro + + + Syntax + + def-enum name fields &key separator-string + + + + Arguments and Values + + + name + + A symbol that names the enumeration. + + + + + fields + + A list of field defintions. Each definition can be +a symbol or a list of two elements. Symbols get assigned a value of the +current counter which starts at 0 and +increments by 1 for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second +position is the value to assign the the symbol. The current counter gets set +to 1+ this value. + + + + + separator-string + + A string that governs the creation of constants. The +default is "#". + + + + + + Description + + Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant +values are created by the concatenation of the +enumeration name, separator-string, and field symbol. Also creates +a foreign type with the name name of type +:int. + + + + Examples + +(def-enum abc (:a :b :c)) +;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines +;; the foreign type "abc" to be :int + +(def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-") +;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines +;; the foreign type efoo to be :int + + + + Side Effects + Creates a :int foreign type, defines constants. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-struct + Defines a &c; structure. + + Macro + + + Syntax + + def-struct name &rest fields + + + + Arguments and Values + + + name + + A symbol that names the structure. + + + + + fields + + A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type. + + + + + + + Description + + Declares a structure. A special type is available as a slot +in the field. It is a pointer that points to an instance of the parent +structure. It's type is :pointer-self. + + + + + Examples + +(def-struct foo (a :unsigned-int) + (b (* :char)) + (c (:array :int 10)) + (next :pointer-self)) + + + + Side Effects + Creates a foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + get-slot-value + Retrieves a value from a slot of a structure. + + Macro + + + Syntax + + get-slot-value obj type field => value + + + + Arguments and Values + + + obj + + A pointer to foreign structure. + + + + + type + + A name of the foreign structure. + + + + + field + + A name of the desired field in foreign structure. + + + + + value + + The value of the field in the structure. + + + + + + + Description + + Accesses a slot value from a structure. + + + + Examples + +(get-slot-value foo-ptr 'foo-structure 'field-name) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + get-slot-pointer + Retrieves a pointer from a slot of a structure. + + Macro + + + Syntax + + get-slot-pointer obj type field => pointer + + + + Arguments and Values + + + obj + + A pointer to foreign structure. + + + + + type + + A name of the foreign structure. + + + + + field + + A name of the desired field in foreign structure. + + + + + pointer + + The value of the field in the structure. + + + + + + + Description + + This is similar to get-slot-value. It + is used when the value of a slot is a pointer type. + + + + Examples + +(get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-array-pointer + Defines a pointer to a array of type. + + Macro + + + Syntax + + def-array-pointer name type + + + + Arguments and Values + + + name + + A name of the new foreign type. + + + + + type + + The foreign type of the array elements. + + + + + + + Description + + Defines a type tat is a pointer to an array of type. + + + + Examples + +(def-array-pointer byte-array-pointer :unsigned-char) + + + + Side Effects + Defines a new foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + deref-array + Deference an array. + + Macro + + + Syntax + + deref-array array type positon => value + + + + Arguments and Values + + + array + + A foreign array. + + + + + type + + The foreign type of the array. + + + + + position + + An integer specifying the position to retrieve from +the array. + + + + + value + + The value stored in the position of the array. + + + + + + + Description + + Dereferences (retrieves) the value of an array element. + + + + Examples + +(def-array ca :char) +(let ((fs (convert-to-foreign-string "ab"))) + (values (null-char-p (deref-array fs 'ca 0)) + (null-char-p (deref-array fs 'ca 2)))) +=> &nil; + &t; + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + def-union + Defines a foreign union type. + + Macro + + + Syntax + + def-union name &rest fields + + + + Arguments and Values + + + name + + A name of the new union type. + + + + + fields + + A list of fields of the union. + + + + + + + Description + + Defines a foreign union type. + + + + Examples + +(def-union test-union + (a-char :char) + (an-int :int)) + +(let ((u (allocate-foreign-object 'test-union)) + (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256))) + (prog1 + (ensure-char-character (get-slot-value u 'test-union 'a-char)) + (free-foreign-object u))) +=> #\A + + + + Side Effects + Defines a new foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + + Objects + +Overview + + Objects are entities that can allocated, referred to by pointers, and +can be freed. + + + + + + + allocate-foreign-object + Allocates an instance of a foreign object. + + Macro + + + Syntax + + allocate-foreign-object type &optional size => ptr + + + + Arguments and Values + + + type + + The type of foreign object to allocate. This parameter is evaluated. + + + + + size + + An optional size parameter that is evaluated. If specified, allocates and returns an +array of type that is size members long. This parameter is evaluated. + + + + + ptr + + A pointer to the foreign object. + + + + + + + Description + + Allocates an instance of a foreign object. It returns a pointer to the object. + + + + Examples + +(def-struct ab (a :int) (b :double)) +(allocate-foreign-object 'ab) +=> #<ptr> + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + free-foreign-object + Frees memory that was allocated for a foreign boject. + + Macro + + + Syntax + + free-foreign-object ptr + + + + Arguments and Values + + + ptr + + A pointer to the allocated foreign object to free. + + + + + + + Description + + Frees the memory used by the allocation of a foreign object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + with-foreign-object + Wraps the allocation of a foreign object around a body of code. + + Macro + + + Syntax + + with-foreign-object (var type) &body body => form-return + + + + Arguments and Values + + + var + + The variable name to bind. + + + + + type + + The type of foreign object to allocate. This parameter is evaluated. + + + + + form-return + + The result of evaluating the body. + + + + + + + Description + +This function wraps the allocation, binding, and destruction of a foreign object. +On &cmucl; and +&lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs +much better with static allocation. + + + + Examples + +(defun gethostname2 () + "Returns the hostname" + (uffi:with-foreign-object (name '(:array :unsigned-char 256)) + (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256)) + (uffi:convert-from-foreign-string name) + (error "gethostname() failed.")))) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + size-of-foreign-type + Returns the number of data bytes used by a foreign object type. + + Macro + + + Syntax + + size-of-foreign-type ftype + + + + Arguments and Values + + + ftype + + A foreign type specifier. This parameter is evaluated. + + + + + + + Description + + Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead. + + + + Examples + + +(size-of-foreign-object :unsigned-byte) +=> 1 +(size-of-foreign-object 'my-100-byte-vector-type) +=> 100 + + + + + Side Effects + None. + + Affected by + None. + + + Exceptional Situations + None. + + + + + + pointer-address + Returns the address of a pointer. + + Macro + + + Syntax + + pointer-address ptr => address + + + + Arguments and Values + + + ptr + + A pointer to a foreign object. + + + + + address + + An integer representing the pointer's address. + + + + + + + Description + + Returns the address as an integer of a pointer. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + deref-pointer + Deferences a pointer. + + Macro + + + Syntax + + deref-pointer ptr type => value + + + + Arguments and Values + + + ptr + + A pointer to a foreign object. + + + + + type + + A foreign type of the object being pointed to. + + + + + value + + The value of the object where the pointer points. + + + + + + + Description + + Returns the object to which a pointer points. + + + + Examples + + +(let ((intp (allocate-foreign-object :int))) + (setf (deref-pointer intp :int) 10) + (prog1 + (deref-pointer intp :int) + (free-foreign-object intp))) +=> 10 + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + ensure-char-character + Ensures that a dereferenced :char pointer is +a character. + + Macro + + + Syntax + + ensure-char-character object => char + + + + Arguments and Values + + + object + + Either a character or a integer specifying a character code. + + + + + char + + A character. + + + + + + + Description + + Ensures that an object obtained by dereferencing a +:char pointer is a character. + + + + Examples + + +(let ((fs (convert-to-foreign-string "a"))) + (prog1 + (ensure-char-character (deref-pointer fs :char)) + (free-foreign-object fs))) +=> #\a + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + Depending upon the implementation and what &uffi; expects, this +macro may signal an error if the object is not a character or +integer. + + + + + + ensure-char-integer + Ensures that a dereferenced :char pointer is +an integer. + + Macro + + + Syntax + + ensure-char-integer object => int + + + + Arguments and Values + + + object + + Either a character or a integer specifying a character code. + + + + + int + + An integer. + + + + + + + Description + + Ensures that an object obtained by dereferencing a +:char pointer is an integer. + + + + Examples + + +(let ((fs (convert-to-foreign-string "a"))) + (prog1 + (ensure-char-integer (deref-pointer fs :char)) + (free-foreign-object fs))) +=> 96 + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + Depending upon the implementation and what &uffi; expects, this +macro may signal an error if the object is not a character or +integer. + + + + + + make-null-pointer + Create a &null; pointer. + + Macro + + + Syntax + + make-null-pointer type => ptr + + + + Arguments and Values + + + type + + A type of object to which the pointer refers. + + + + + ptr + + The &null; pointer of type type. + + + + + + + Description + + Creates a &null; pointer of a specified type. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + null-pointer-p + Tests a pointer for &null; value. + + Macro + + + Syntax + + null-pointer-p ptr => is-null + + + + Arguments and Values + + + ptr + + A foreign object pointer. + + + + + is-null + + The boolean flag. + + + + + + + Description + + A predicate testing if a pointer is has a &null; value. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + +null-cstring-pointer+ + A constant &null; cstring pointer. + + Constant + + + Description + + A &null; cstring pointer. This can be used for testing +if a cstring returned by a function is &null;. + + + + + + + + Strings + +Overview + + + &uffi; has functions to two types of +C-compatible + strings: cstring and +foreign strings. + +cstrings are used only as parameters to and from +functions. In some implementations a cstring is not a foreign type but +rather the Lisp string itself. On other platforms a cstring is a newly +allocated foreign vector for storing characters. The following is an +example of using cstrings to both send and return a value. + + + +(uffi:def-function ("getenv" c-getenv) + ((name :cstring)) + :returning :cstring) + +(defun my-getenv (key) + "Returns an environment variable, or NIL if it does not exist" + (check-type key string) + (uffi:with-cstring (key-native key) + (uffi:convert-from-cstring (c-getenv key-native)))) + + + In contrast, foreign strings are always a foreign vector of +characters which have memory allocated. Thus, if you need to allocate +memory to hold the return value of a string, you must use a foreign +string and not a cstring. The following is an example of using a foreign +string for a return value. + + +(uffi:def-function ("gethostname" c-gethostname) + ((name (* :unsigned-char)) + (len :int)) + :returning :int) + +(defun gethostname () + "Returns the hostname" + (let* ((name (uffi:allocate-foreign-string 256)) + (result-code (c-gethostname name 256)) + (hostname (when (zerop result-code) + (uffi:convert-from-foreign-string name)))) + (uffi:free-foreign-object name) + (unless (zerop result-code) + (error "gethostname() failed.")))) + + + + + + + convert-from-cstring + Converts a cstring to a Lisp string. + + Macro + + + Syntax + + convert-from-cstring cstring => string + + + + Arguments and Values + + + cstring + + A cstring. + + + + + string + + A Lisp string. + + + + + + + Description + + Converts a Lisp string to a cstring. This is +most often used when processing the results of a foreign function +that returns a cstring. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-cstring + Converts a Lisp string to a cstring. + + Macro + + + Syntax + + convert-to-cstring string => cstring + + + + Arguments and Values + + + string + + A Lisp string. + + + + + cstring + + A cstring. + + + + + + + Description + + Converts a Lisp string to a + cstring. The + cstring should be freed with + free-cstring. + + + + Side Effects + On some implementations, this function allocates memory. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + free-cstring + Free memory used by cstring. + + Macro + + + Syntax + + free-cstring cstring + + + + Arguments and Values + + + cstring + + A cstring. + + + + + + + Description + + Frees any memory possibly allocated by + convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + with-cstring + Binds a newly created cstring. + + Macro + + + Syntax + + with-cstring (cstring string) {body} + + + + Arguments and Values + + + cstring + + A symbol naming the cstring to be created. + + + + + string + + A Lisp string that will be translated to a cstring. + + + + + body + + The body of where the cstring will be bound. + + + + + + + Description + + Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring. + + + + Examples + + +(def-function ("getenv" c-getenv) + ((name :cstring)) + :returning :cstring) + +(defun getenv (key) + "Returns an environment variable, or NIL if it does not exist" + (check-type key string) + (with-cstring (key-cstring key) + (convert-from-cstring (c-getenv key-cstring)))) + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-from-foreign-string + Converts a foreign string into a Lisp string. + + Macro + + + Syntax + + convert-from-foreign-string foreign-string &key length null-terminated-p => string + + + + Arguments and Values + + + foreign-string + + A foreign string. + + + + + length + + The length of the foreign string to +convert. The default is the length of the string until a &null; +character is reached. + + + + + null-terminated-p + + A boolean flag with a default value of &t; When true, +the string is converted until the first &null; character is reached. + + + + + string + + A Lisp string. + + + + + + + Description + + Returns a Lisp string from a foreign string. +Can translated ASCII and binary strings. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-foreign-string + Converts a Lisp string to a foreign string. + + Macro + + + Syntax + + convert-to-foreign-string string => foreign-string + + + + Arguments and Values + + + string + + A Lisp string. + + + + + foreign-string + + A foreign string. + + + + + + + Description + + Converts a Lisp string to a foreign string. Memory should be + freed with free-foreign-object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + + allocate-foreign-string + Allocates space for a foreign string. + + Macro + + + Syntax + + allocate-foreign-string size &key unsigned => foreign-string + + + + Arguments and Values + + + size + + The size of the space to be allocated in bytes. + + + + + unsigned + + A boolean flag with a default value of &t;. When true, +marks the pointer as an :unsigned-char. + + + + + foreign-string + + A foreign string which has undefined contents. + + + + + + + Description + + Allocates space for a foreign string. Memory should + be freed with free-foreign-object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + Functions & Libraries + + + + def-function + Declares a function. + + Macro + + + Syntax + + def-function name args &key module returning + + + + Arguments and Values + + + name + + A string or list specificying the function name. If it is a string, that names the foreign function. A Lisp name is created by translating #\_ to #\- and by converting to upper-case in case-insensitive Lisp implementations. If it is a list, the first item is a string specifying the foreign function name and the second it is a symbol stating the Lisp name. + + + + + args + + A list of argument declarations. If &nil;, indicates that the function does not take any arguments. + + + + + module + + A string specifying which module (or library) that the foreign function resides. (Required by Lispworks) + + + + returning + + A declaration specifying the result type of the +foreign function. If :void indicates module does not return any value. + + + + + + + Description + Declares a foreign function. + + + + Examples + +(def-function "gethostname" + ((name (* :unsigned-char)) + (len :int)) + :returning :int) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + load-foreign-library + Loads a foreign library. + + Function + + + Syntax + + load-foreign-library filename &key module supporting-libraries => success + + + + Arguments and Values + + + filename + + A string or pathname specifying the library location +in the filesystem. At least one implementation (&lw;) can not +accept a logical pathname. + + + + + module + + A string designating the name of the module to apply +to functions in this library. (Required for Lispworks) + + + + + supporting-libraries + + A list of strings naming the libraries required to +link the foreign library. (Required by CMUCL) + + + + + success + + A boolean flag, &t; if the library was able to be +loaded successfully or if the library has been previously loaded, +otherwise &nil;. + + + + + + + Description + Loads a foreign library. Applies a module name to functions +within the library. Ensures that a library is only loaded once during +a session. + + + + Examples + + (load-foreign-library #p"/usr/lib/libmysqlclient.so" + :module "mysql" + :supporting-libraries '("c")) + => T + + + + Side Effects + Loads the foreign code into the Lisp system. + + + + Affected by + Ability to load the file. + + + Exceptional Situations + None. + + + + + + find-foreign-library + Finds a foreign library file. + + Function + + + Syntax + + find-foreign-library names directories & drive-letters types => path + + + + Arguments and Values + + + names + + A string or list of strings containing the base name of the library file. + + + + + directories + + A string or list of strings containing the directory the library file. + + + + + drive-letters + + A string or list of strings containing the drive letters for the library file. + + + + + types + + A string or list of strings containing the file type of the library file. Default +is &nil;. If &nil;, will use a default type based on the currently running implementation. + + + + + path + + A path containing the path found, or &nil; if the library file was not found. + + + + + + + Description + Finds a foreign library by searching through a number of possible locations. Returns +the path of the first found file. + + + + Examples + +(find-foreign-library '("libmysqlclient" "libmysql") + '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/") + :types '("so" "dll") + :drive-letters '("C" "D" "E")) +=> #P"D:\\mysql\\lib\\opt\\libmysql.dll" + + + + Side Effects + None. + + + + Affected by + None. + + + Exceptional Situations + None. + + + + + +