From 99df36a50fb39976c6b6086db2f5f640f5d917b7 Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Sat, 16 Apr 2016 04:16:00 +0200 Subject: [PATCH] reincarnation commit --- .dir-locals.el | 1 + .gitignore | 1 + CHANGELOG | 5 + LICENSE | 674 +++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 96 +++++++ README.md | 22 ++ epkg-desc.el | 346 +++++++++++++++++++++++++ epkg-list.el | 242 ++++++++++++++++++ epkg.el | 451 +++++++++++++++++++++++++++++++++ epkg.org | 504 ++++++++++++++++++++++++++++++++++++ epkg.texi | 613 ++++++++++++++++++++++++++++++++++++++++++++ 11 files changed, 2955 insertions(+) create mode 100644 .dir-locals.el create mode 100644 .gitignore create mode 100644 CHANGELOG create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 epkg-desc.el create mode 100644 epkg-list.el create mode 100644 epkg.el create mode 100644 epkg.org create mode 100644 epkg.texi diff --git a/.dir-locals.el b/.dir-locals.el new file mode 100644 index 0000000..df2c4f6 --- /dev/null +++ b/.dir-locals.el @@ -0,0 +1 @@ +((nil . ((indent-tabs-mode . nil)))) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bf12a97 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.info diff --git a/CHANGELOG b/CHANGELOG new file mode 100644 index 0000000..6aa8506 --- /dev/null +++ b/CHANGELOG @@ -0,0 +1,5 @@ +# -*- mode: org -*- + +* 1.0.0 20160415 + + Reincarnation release. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..94a9ed0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public 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. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..a7aeea4 --- /dev/null +++ b/Makefile @@ -0,0 +1,96 @@ +-include config.mk + +ELS = epkg.el +ELS += epkg-desc.el +ELS += epkg-list.el +ELCS = $(ELS:.el=.elc) + +DEPS = closql +DEPS += dash +DEPS += emacsql +DEPS += finalize + +LOADDEFS = epkg-autoloads.el + +EMACS ?= emacs +EFLAGS ?= +DFLAGS ?= $(addprefix -L ../,$(DEPS)) +MFLAGS ?= -L ../org/lisp -L ../ox-texinfo+ + +INFOPAGES = epkg.info +MAKEINFO ?= makeinfo --no-split +INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info) + +.PHONY: help texi clean + +all: lisp info + +help: + $(info make all - generate lisp and manual) + $(info make lisp - generate byte-code and loaddefs) + $(info make info - generate manual) + $(info make texi - generate (tracked) texi file) + $(info make clean - remove generated files) + @printf "\n" + +lisp: $(ELCS) loaddefs + +epkg.elc: +epkg-desc.elc: epkg.elc +epkg-list.elc: epkg.elc + +%.elc: %.el + @printf "Compiling $<\n" + @$(EMACS) -Q --batch $(EFLAGS) -L . $(DFLAGS) -f batch-byte-compile $< + +loaddefs: $(LOADDEFS) + +define LOADDEFS_TMPL +;;; $(LOADDEFS) --- automatically extracted autoloads +;; +;;; Code: +(add-to-list 'load-path (directory-file-name \ +(or (file-name-directory #$$) (car load-path)))) + +;; Local Variables: +;; version-control: never +;; no-byte-compile: t +;; no-update-autoloads: t +;; End: +;;; $(LOADDEFS) ends here +endef +export LOADDEFS_TMPL +#' + +$(LOADDEFS): $(ELS) + @printf "Generating $@\n" + @printf "%s" "$$LOADDEFS_TMPL" > $@ + @$(EMACS) -Q --batch --eval "(progn\ + (setq make-backup-files nil)\ + (setq vc-handled-backends nil)\ + (setq default-directory (file-truename default-directory))\ + (setq generated-autoload-file (expand-file-name \"$@\"))\ + (setq find-file-visit-truename t)\ + (update-directory-autoloads default-directory)))" + +info: $(INFOPAGES) dir + +%.info: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) $< -o $@ + +texi: + @printf "Generating epkg.texi\n" + @$(EMACS) -Q --batch $(EFLAGS) $(DFLAGS) + -l ox-texinfo+.el epkg.org \ + -f org-texinfo+export-to-texinfo + @echo >> epkg.texi + @rm -f epkg.texi~ + +dir: $(INFOPAGES) + @printf "Generating $@\n" + @$(INSTALL_INFO) $< --dir=$@ + +clean: + @printf "Cleaning...\n" + @rm -f $(ELCS) $(LOADDEFS) $(INFOPAGES) diff --git a/README.md b/README.md new file mode 100644 index 0000000..7057bb3 --- /dev/null +++ b/README.md @@ -0,0 +1,22 @@ +Browse the Emacsmirror package database +======================================= + +This package provides access to a local copy of the [Emacsmirror] +package database. It provides low-level functions for querying the +database and a `package.el`-like user interface for browsing the +available packages. + +The Emacsmirror is a growing collection of Emacs Lisp packages. All +mirrored packages are available as Git repositories. In most cases +this is done by mirroring the upstream Git repository, but if upstream +uses something else, then the mirror nevertheless makes the package +available as a Git repository. + +One primary purpose of the Emacsmirror is to provide a comprehensive +list of available Emacs packages, including packages which have gone +out of fashion (but might later prove to be useful still). + +For more information see the [manual] and the [Emacsmirror]. + +[emacsmirror]: https://emacsmirror.net +[manual]: https://emacsmirror.net/manual/epkg diff --git a/epkg-desc.el b/epkg-desc.el new file mode 100644 index 0000000..e6720e6 --- /dev/null +++ b/epkg-desc.el @@ -0,0 +1,346 @@ +;;; epkg-desc.el --- show Epkg descriptions -*- lexical-binding: t -*- + +;; Copyright (C) 2016 Jonas Bernoulli + +;; This file contains code from GNU Emacs, which is +;; Copyright (C) 1976-2016 Free Software Foundation, Inc. + +;; This file is not part of GNU Emacs. + +;; This file is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published +;; by the Free Software Foundation; either version 3 of the License, +;; or (at your option) any later version. + +;; This file is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; For a full copy of the GNU GPL see http://www.gnu.org/licenses. + +;;; Code: + +(require 'epkg) +(require 'find-func) + +;;; Options + +(defconst epkg--custom-slot-choices + (nconc (list (list 'const 'type) + (list 'const 'class)) + (--map (list 'const (cl--slot-descriptor-name it)) + (eieio-class-slots (cl--find-class 'epkg-package))))) + +(defcustom epkg-describe-package-slots + '(summary + epkg-insert-homepage + epkg-insert-repopage + epkg-insert-mirrorpage + nil + type + license + updated + epkg-insert-authors + epkg-insert-maintainers + nil + epkg-insert-provided + epkg-insert-keywords + epkg-insert-commentary + epkg-insert-dependencies + epkg-insert-reverse-dependencies) + "Slots that are displayed when describing an Epkg package. + +The value is a list. Each element can be a slot symbol, a +function, or nil. Functions are called with one argument, the +Epkg object. They should insert something at point. Raw slot +symbols cause its non-nil value to be inserted as-is. If a +slot's value is nil, then nothing is inserted. Elements that +are nil stand for empty lines." + :group 'epkg + :type `(repeat + (choice :format "%[Value Menu%] %v" + (const :tag " Newline" nil) + (choice :tag "Function" + (const epkg-insert-homepage) + (const epkg-insert-repopage) + (const epkg-insert-wikipage) + (const epkg-insert-mirrorpage) + (const epkg-insert-authors) + (const epkg-insert-maintainers) + (const epkg-insert-provided) + (const epkg-insert-keywords) + (const epkg-insert-commentary) + (const epkg-insert-dependencies) + (const epkg-insert-reverse-dependencies) + (function :tag "Other")) + (choice :tag " Slot" ,@epkg--custom-slot-choices)))) + +(defcustom epkg-describe-package-slots-width 12 + "Display width of Epkg slots in Epkg help." + :group 'epkg + :type 'integer) + +(defface epkg-help-slot + '((t :inherit (bold font-lock-function-name-face))) + "Face used for slot names when describing an Epkg package." + :group 'epkg) + +(defface epkg-help-name + '((t :height 1.6)) + "Face used for the name of the described Epkg package." + :group 'epkg) + +;;; Commands + +;;;###autoload +(defun epkg-describe-package (package) + "Display the full documentation of PACKAGE." + (interactive + (list (epkg-read-package "Describe package: " + (or (tabulated-list-get-id) + (--when-let (symbol-at-point) + (symbol-name it)))))) + (help-setup-xref (list #'epkg-describe-package package) + (called-interactively-p 'interactive)) + (with-help-window (help-buffer) + (with-current-buffer standard-output + (epkg-describe-package-1 (epkg package))))) + +(defun epkg-list-describe-package (&optional _button) + "Display the full documentation of the package on the current line." + (interactive) + (if-let ((package (tabulated-list-get-id))) + (epkg-describe-package package) + (call-interactively 'epkg-describe-package))) + +;;; Inserters + +(defun epkg-describe-package-1 (pkg) + (with-slots (name commentary) pkg + (insert (propertize (capitalize (oref pkg name)) 'face 'epkg-help-name)) + (insert " is a ") + (insert (pcase (eieio-object-class pkg) + ('epkg-builtin-package "built-in") + ('epkg-shelved-package "shelved") + (_ "mirrored"))) + (insert " package.\n\n") + (dolist (slot epkg-describe-package-slots) + (unless (= (char-before) ?\n) + (insert ?\n)) + (cl-typecase slot + (null (insert ?\n)) + (function (funcall slot pkg)) + (t (--when-let (if (eq slot 'type) + (epkg-type pkg) + (slot-value pkg slot)) + (epkg--insert-slot slot) + (insert (format "%s\n" it)))))))) + +(defun epkg--insert-slot (slot) + (insert (format (format "%%%ss: " epkg-describe-package-slots-width) + (propertize (capitalize (symbol-name slot)) + 'face 'epkg-help-slot)))) + +(defun epkg-insert-person (value) + (indent-to (+ epkg-describe-package-slots-width 2)) + (-let [(name email) value] + (when name + (insert-button name 'type 'epkg-author 'help-args (list name))) + (when email + (when name + (insert " ")) + (insert "<") + (insert-button email 'type 'epkg-email 'help-args + (list (format "%s <%s>" name email))) + (insert ">"))) + (insert "\n")) + +(defun epkg-insert-authors (pkg) + (--when-let (oref pkg authors) + (epkg--insert-slot 'authors) + (mapc #'epkg-insert-person it))) + +(defun epkg-insert-maintainers (pkg) + (--when-let (oref pkg maintainers) + (epkg--insert-slot 'maintainers) + (mapc #'epkg-insert-person it))) + +(defun epkg-insert-keywords (pkg) + (--when-let (oref pkg keywords) + (epkg--insert-slot 'keywords) + (while it + (let ((symbol (pop it))) + (insert-button (symbol-name symbol) + 'type 'epkg-keyword 'help-args (list symbol)) + (when it (insert ", ")))) + (insert ?\n))) + +(defun epkg-insert-homepage (pkg) + (--when-let (oref pkg homepage) + (epkg--insert-slot 'homepage) + (insert-button it 'type 'help-url 'help-args (list it)) + (insert ?\n))) + +(defun epkg-insert-repopage (pkg) + (--when-let (oref pkg repopage) + (epkg--insert-slot 'repopage) + (insert-button it 'type 'help-url 'help-args (list it)) + (insert ?\n))) + +(defun epkg-insert-wikipage (pkg) + (--when-let (oref pkg wikipage) + (epkg--insert-slot 'wikipage) + (insert-button it 'type 'help-url 'help-args (list it)))) + +(defun epkg-insert-mirrorpage (pkg) + (--when-let (oref pkg mirrorpage) + (epkg--insert-slot 'mirrorpage) + (insert-button it 'type 'help-url 'help-args (list it)))) + +(defun epkg-insert-commentary (pkg) + (--when-let (oref pkg commentary) + (insert ?\n it))) + +(defun epkg-insert-provided (pkg) + (--when-let (oref pkg provided) + (epkg--insert-slot 'provided) + (require 'find-func) + (while it + (let ((library (symbol-name (car (pop it))))) + (when (> (+ (- (point) (line-beginning-position)) (length library) 2) + (window-width)) + (insert ?\n) + (insert (make-string (+ epkg-describe-package-slots-width 2) ?\s))) + (if (ignore-errors (find-library-name library)) + (insert-button library 'type 'epkg-library + 'help-args (list library)) + (insert library)) + (when it (insert ", ")))) + (insert ?\n))) + +(defun epkg-insert-dependencies (pkg) + (require 'tree-widget) + (when (oref pkg required) + (insert ?\n) + (widget-create + (list 'epkg-dependency-tree + :get-dependencies 'epkg-required + :open t + :node (list 'epkg-dependency-node + :value (list pkg) + :format "%{Dependencies:%}\n" + :sample-face 'epkg-help-slot))))) + +(defun epkg-insert-reverse-dependencies (pkg) + (require 'tree-widget) + (when (epkg-reverse-dependencies pkg) + (insert ?\n) + (widget-create + (list 'epkg-dependency-tree + :get-dependencies 'epkg-reverse-dependencies + :open t + :node (list 'epkg-dependency-node + :value (list pkg) + :format "%{Reverse dependencies:%}\n" + :sample-face 'epkg-help-slot))))) + +;;; Buttons + +(define-button-type 'epkg-menu-package + :supertype 'help-xref + 'help-function 'epkg-menu-describe-package + 'help-echo (purecopy "mouse-2, RET: View package")) + +(define-button-type 'epkg-revision + :supertype 'help-xref + 'help-function 'epkg-describe-package + 'help-echo (purecopy "mouse-2, RET: View this revision")) + +(define-button-type 'epkg-keyword + :supertype 'help-xref + 'help-function 'epkg-list-keyworded-packages + 'help-echo (purecopy "mouse-2, RET: List keyworded packages")) + +(define-button-type 'epkg-package + :supertype 'help-xref + 'help-function 'epkg-describe-package + 'help-echo (purecopy "mouse-2, RET: View package")) + +(define-button-type 'epkg-library + :supertype 'help-xref + 'help-function 'find-library + 'help-echo (purecopy "mouse-2, RET: View library")) + +(define-button-type 'epkg-author + :supertype 'help-xref + 'help-function 'epkg-list-packages-by-author + 'help-echo (purecopy "mouse-2, RET: List packages by author")) + +(define-button-type 'epkg-email + :supertype 'help-url + 'help-function #'compose-mail + 'help-echo (purecopy "mouse-2, RET: Compose mail")) + +;;; Widgets + +(declare-function widget-default-format-handler "wid-edit" (_widget escape)) +(declare-function widget-type "wid-edit" (widget)) + +(define-widget 'epkg-dependency-tree 'tree-widget + "The Epkg Dependency Tree widget." + :expander 'epkg-dependency-tree-expander) + +(defun epkg-dependency-tree-expander (widget) + (let ((node (widget-get widget :node)) + (getter (widget-get widget :get-dependencies))) + (-when-let (pkg (car (widget-get node :value))) + (-map (-lambda ((name . features)) + (list 'epkg-dependency-tree + :get-dependencies getter + :node (list (widget-type node) + :value (cons (and name (epkg name)) features)))) + (funcall getter pkg))))) + +(define-widget 'epkg-dependency-node 'default + "The Epkg Dependency Node widget." + :format "%P %T %H\n" + :format-handler 'epkg-dependency-node-format-handler + :value-get 'widget-value-value-get + :keymap widget-keymap) + +(defun epkg-dependency-node-format-handler (widget escape) + (-let [(pkg . features) (widget-get widget :value)] + (pcase escape + (?P (if pkg + (insert-button (oref pkg name) 'type 'epkg-package + 'face (and (-any #'symbolp features) 'bold) + 'help-args (list (oref pkg name))) + (insert (propertize "unknown" 'face + (if (symbolp (car features)) + (list 'font-lock-warning-face 'bold) + 'font-lock-warning-face))))) + (?T (insert (propertize " " 'display '(space :align-to 30))) + (insert (if pkg + (let ((type (symbol-name (epkg-type pkg)))) + (if (epkg-shelved-package-p pkg) + (propertize type 'face 'font-lock-warning-face) + type)) + (propertize "unknown" 'face 'font-lock-warning-face)))) + (?H (insert (propertize " " 'display '(space :align-to 43))) + (while features + (let (hard (library (pop features))) + (when (symbolp library) + (setq hard t) + (setq library (symbol-name library))) + (if (ignore-errors (find-library-name library)) + (insert-button library + 'type 'epkg-library + 'help-args (list library) + 'face (and hard 'bold)) + (insert library))) + (when features (insert ", ")))) + (_ (widget-default-format-handler widget escape))))) + +(provide 'epkg-desc) +;;; epkg-desc.el ends here diff --git a/epkg-list.el b/epkg-list.el new file mode 100644 index 0000000..fbdddf6 --- /dev/null +++ b/epkg-list.el @@ -0,0 +1,242 @@ +;;; epkg-list.el --- list Epkg packages -*- lexical-binding: t -*- + +;; Copyright (C) 2016 Jonas Bernoulli + +;; This file contains code from GNU Emacs, which is +;; Copyright (C) 1976-2016 Free Software Foundation, Inc. + +;; This file is not part of GNU Emacs. + +;; This file is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published +;; by the Free Software Foundation; either version 3 of the License, +;; or (at your option) any later version. + +;; This file is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; For a full copy of the GNU GPL see http://www.gnu.org/licenses. + +;;; Code: + +(require 'epkg) +(require 'epkg-desc) + +;;; Options + +(defcustom epkg-list-packages-omit-shelved t + "Whether shelved packages are omitted when listing packages." + :group 'epkg + :type 'boolean) + +(defcustom epkg-list-columns + '(("Package" 25 t nil name epkg-list-format-name) + ("Type" 12 t nil class nil) + ("Description" 99 nil nil summary nil)) + "Slots displayed in the package menu. + +The value is a list of columns. Each element has the form +\(HEADER WIDTH SORTP PROPS SLOT FORMAT). HEADER is the string +displayed in the header. WIDTH is the width of the column. If +SORTP is t, then the column can be sorted, if it is nil then it +can not. PROPS is an alist, supported keys are `:right-align' +and `:pad-right'. Slot is an Epkg object slot or `type'. FORMAT +is a function. It is called with one argument the slot value and +has to return a representation of that. If FORMAT is nil, then +the value is inserted as-is." + :group 'epkg + :type `(repeat + (list :tag "Column" + (string :tag "Header Label") + (integer :tag "Column Width") + (choice :tag "Sort predicate" + (const :tag "don't sort" nil) + (const :tag "default" t) + (function)) + (repeat :tag "Properties" + (list (choice :tag "Property" + (const :right-align) + (const :pad-right) + (symbol)) + (sexp :tag "Value"))) + (choice :tag "Slot symbol" ,@epkg--custom-slot-choices) + (choice :tag "Format value" + (const :tag "as is" nil) + (const epkg-list-format-name) + (function))))) + +(unless (find-lisp-object-file-name 'epkg-list-mode-hook 'defvar) + (add-hook 'epkg-list-mode-hook 'hl-line-mode)) +(defcustom epkg-list-mode-hook '(hl-line-mode) + "Hook run after entering Epkg-List mode." + :group 'epkg + :type 'hook + :options '(hl-line-mode)) + +(defface epkg-list-name + '((t :inherit link :underline nil)) + "Face used on package names in the package list." + :group 'epkg) + +;;; Commands + +;;;###autoload +(defun epkg-list-packages (&optional all) + "Display a list of packages. + +By default shelved packages are omitted from the output. With a +prefix argument or when `epkg-list-packages-omit-shelved' is nil, +then no packages are omitted." + (interactive (list current-prefix-arg)) + (epkg--list-packages + (epkgs (epkg--list-columns-vector) + (and (not all) + '(epkg-builtin-package-p + epkg-mirrored-package--eieio-childp))))) + +;;;###autoload +(defun epkg-list-matching-packages (pattern &optional all) + "Display a list of packages whose summaries match REGEXP. + +By default shelved packages are omitted from the output. With a +prefix argument or when `epkg-list-packages-omit-shelved' is nil, +then no packages are omitted." + (interactive (list (read-string "pattern: ") current-prefix-arg)) + (epkg--list-packages + (epkg-sql [:select $i1 :from packages + :where (like summary $s2) + :and class :in $v3] + (epkg--list-columns-vector) + (intern (if (string-match-p "%_" pattern) + pattern + (concat "%" pattern "%"))) + (epkg--list-where-class-in all)))) + +;;;###autoload +(defun epkg-list-keyworded-packages (keyword &optional all) + "Display a list of packages that have KEYWORD set. + +Only keywords that are members of `finder-known-keywords' are +offered as completion candidates, but you can also enter other +keywords. + +By default shelved packages are omitted from the output. With a +prefix argument or when `epkg-list-packages-omit-shelved' is nil, +then no packages are omitted." + (interactive (list (intern (completing-read + "List packages with keyword: " + (progn (require 'finder nil t) + (bound-and-true-p finder-known-keywords)))) + current-prefix-arg)) + (epkg--list-packages + (epkg-sql [:select $i1 :from [packages keywords] + :where (= name package) + :and (= keyword $s2) + :and class :in $v3] + (epkg--list-columns-vector) + keyword + (epkg--list-where-class-in all)))) + +;;;###autoload +(defun epkg-list-packages-by-author (author &optional all) + "Display a list of packages authored or maintained by AUTHOR. + +AUTHOR may be a name or an email address. Packages whose +Author(s) or Maintainer(s) header keywords contain that author +are listed. + +By default shelved packages are omitted from the output. With a +prefix argument or when `epkg-list-packages-omit-shelved' is nil, +then no packages are omitted." + (interactive (list (read-string "List packages by author: ") + current-prefix-arg)) + (epkg--list-packages + (let ((email-p (string-match-p "@" author)) + (columns (epkg--list-columns-vector t)) + (classin (epkg--list-where-class-in all))) + (-union (epkg-sql [:select :distinct $i1 :from [packages authors] + :where (= packages:name authors:package) + :and (= $i2 $s3) + :and class :in $v4] + columns (if email-p 'email 'authors:name) + author classin) + (epkg-sql [:select :distinct $i1 :from [packages maintainers] + :where (= packages:name maintainers:package) + :and (= $i2 $s3) + :and class :in $v4] + columns (if email-p 'email 'maintainers:name) + author classin))))) + +;;;###autoload +(defun epkg-list-packages-of-type (type) + "Display a list of all packages of a certain type. + +To list all packages of a certain type as well as its subtypes +use `TYPE*' instead of just `TYPE'." + (interactive (list (epkg-read-type "List packages of type: " nil t))) + (epkg--list-packages + (epkgs (epkg--list-columns-vector) + (if (eq type 'all*) + 'epkg-package + (setq type (symbol-name type)) + (intern (if (string-suffix-p "*" type) + (format "epkg-%s-package--eieio-childp" + (substring type 0 -1)) + (format "epkg-%s-package" type))))))) + +(defun epkg--list-packages (rows) + (with-current-buffer (get-buffer-create "*Epkgs*") + (epkg-list-mode) + (setq tabulated-list-entries + (mapcar (lambda (row) + (list (car row) + (vconcat + (cl-mapcar (lambda (val col) + (if-let ((pp (nth 5 col))) + (funcall pp val) + (if val (format "%s" val) ""))) + row epkg-list-columns)))) + rows)) + (tabulated-list-print) + (switch-to-buffer (current-buffer)))) + +;;; Mode + +(defvar epkg-list-mode-map + (let ((map (make-sparse-keymap))) + (set-keymap-parent map tabulated-list-mode-map) + (define-key map "\r" 'epkg-list-describe-package) + map) + "Local keymap for Epkg-List mode buffers.") + +(define-derived-mode epkg-list-mode tabulated-list-mode "Epkgs" + "Major mode for browsing a list of packages." + (setq x-stretch-cursor nil) + (setq tabulated-list-padding 0) + (setq tabulated-list-sort-key (cons "Package" nil)) + (setq tabulated-list-format (vconcat (--map `(,@(-take 3 it) + ,@(-flatten (nth 3 it))) + epkg-list-columns))) + (tabulated-list-init-header)) + +(defun epkg-list-format-name (name) + (list name + 'face 'epkg-list-name + 'follow-link t + 'action 'epkg-list-describe-package)) + +(defun epkg--list-columns-vector (&optional qualify) + (let ((lst (--map (nth 4 it) epkg-list-columns))) + (vconcat (if qualify (-replace 'name 'packages:name lst) lst)))) + +(defun epkg--list-where-class-in (all) + (closql--where-class-in (epkg-db) + (if (or all (not epkg-list-packages-omit-shelved)) + 'epkg-package--eieio-childp + '(epkg-builtin-package-p + epkg-mirrored-package--eieio-childp)))) + +(provide 'epkg-list) +;;; epkg-list.el ends here diff --git a/epkg.el b/epkg.el new file mode 100644 index 0000000..8915127 --- /dev/null +++ b/epkg.el @@ -0,0 +1,451 @@ +;;; epkg.el --- browse the Emacsmirror package database -*- lexical-binding: t -*- + +;; Copyright (C) 2016 Jonas Bernoulli + +;; Author: Jonas Bernoulli +;; Homepage: https://gitlab.com/tarsius/epkg +;; Package-Requires: ((closql "0.1.0") (dash "2.12.1") (emacs "25.0.92")) +;; Keywords: tools + +;; This file is not part of GNU Emacs. + +;; This file is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published +;; by the Free Software Foundation; either version 3 of the License, +;; or (at your option) any later version. + +;; This file is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; For a full copy of the GNU GPL see http://www.gnu.org/licenses. + +;;; Commentary: + +;; This package provides access to a local copy of the Emacsmirror +;; package database. It provides low-level functions for querying +;; the database and a `package.el'-like user interface for browsing +;; the database. Epkg itself is not a package manager. + +;; For more information see https://gitlab.com/tarsius/epkg and for +;; information about the Emacsmirror see https://emacsmirror.net. + +;;; Code: + +(require 'dash) +(require 'seq) +(require 'subr-x) + +(require 'closql) + +;;; Options + +(defconst epkg-db-version 1) + +(defconst epkg-origin-url "https://github.com/emacsmirror/epkgs.git" + "The url of the remote Emacsmirror repository.") + +(defgroup epkg nil + "Browse the Emacsmirror package database." + :group 'applications) + +(defcustom epkg-repository (expand-file-name "epkgs/" user-emacs-directory) + "The location of the local Emacsmirror repository. + +This repository contains the Epkg SQLite database file and, if +they have been initialized, all package repositories from the +Emacsmirror and Emacsattic as submodules. + +If you change the value of this option, then you should also +manually move the repository. Otherwise it would be cloned +again." + :group 'epkg + :type 'directory) + +;;; Database + +(defclass epkg-database (closql-database) + ((primary-table :initform packages) + (primary-key :initform name) + (object-class :initform epkg-package))) + +(defvar epkg--db-connection nil + "The EmacSQL database connection.") + +(defun epkg-db () + "Return the connection to the Epkg database. + +If the `epkg-repository', which contains the SQLite database +file, does not exist yet, then first ask the user to clone it." + (unless (file-exists-p epkg-repository) + (if (yes-or-no-p (format "Clone %s to %s? " + epkg-origin-url + epkg-repository)) + (let ((dir (file-name-directory (directory-file-name epkg-repository)))) + (make-directory dir t) + (let ((default-directory dir)) + (epkg--call-git "clone" + epkg-origin-url + epkg-repository))) + (user-error "Aborted. Epkg requires the Epkgs repository"))) + (unless (and epkg--db-connection (emacsql-live-p epkg--db-connection)) + (closql-db 'epkg-database 'epkg--db-connection + (expand-file-name "epkg.sqlite" epkg-repository)) + (let ((version (caar (emacsql epkg--db-connection "PRAGMA user_version")))) + (cond + ((> version epkg-db-version) + (emacsql-close epkg--db-connection) + (user-error + (concat "Please update the `epkg' package. The installed " + "version is to old for the current database scheme"))) + ((< version epkg-db-version) + (emacsql-close epkg--db-connection) + (if (yes-or-no-p (concat "The installed `epkg' version requires a new " + "database scheme. Update database now? ")) + (epkg-update) + (user-error "Aborted. A database update is required")))))) + epkg--db-connection) + +;;;###autoload +(defun epkg-update () + "Update the Epkg database. + +In the `epkg-repository', pull the master branch and reload +the Epkg database. Return a connection to the updated Epkg +database." + (interactive) + (when epkg--db-connection + (emacsql-close epkg--db-connection)) + (let ((default-directory epkg-repository)) + (epkg--call-git "pull" "--recurse-submodules" "origin" "master")) + (epkg-db)) + +(defvar magit-process-popup-time) +(declare-function magit-call-git "magit-process" (&rest args)) + +(defun epkg--call-git (&rest args) + (if (require 'magit nil t) + (let ((magit-process-popup-time 0)) + (magit-call-git args)) + (with-current-buffer (generate-new-buffer " *Epkg-Git*") + (switch-to-buffer-other-window (current-buffer)) + (apply #'call-process "git" nil t t args)))) + +(cl-defmethod closql--class-to-sql ((_db closql-database) value) + (intern (substring (setq value (symbol-name value)) + (if (string-prefix-p "eieio-class-tag--" value) 22 5) + -8))) + +(cl-defmethod closql--sql-to-class ((_db closql-database) value) + (intern (format "eieio-class-tag--epkg-%s-package" value))) + +;;; Superclass + +(defclass epkg-package (closql-object) + ((repopage-format :allocation :class :initform nil) + (homepage-format :allocation :class :initform nil) + (mirrorpage-format :allocation :class :initform nil) + (mirror-url-format :allocation :class :initform nil) + (url-format :allocation :class :initform nil) + (name :initarg :name :initform nil) + (hash :initarg :hash :initform nil) + (url :initarg :url :initform nil) + (mirror-url :initarg :mirror-url :initform nil) + (mirror-name :initarg :mirror-name :initform nil) + (upstream-user :initarg :upstream-user :initform nil) + (upstream-name :initarg :upstream-name :initform nil) + (upstream-branch :initarg :upstream-branch :initform nil) + (upstream-tree :initarg :upstream-tree :initform nil) + (library :initarg :library :initform nil) + (repopage :initarg :repopage :initform nil) + (homepage :initarg :homepage :initform nil) + (mirrorpage :initarg :mirrorpage :initform nil) + (wikipage :initarg :wikipage :initform nil) + (license :initarg :license :initform nil) + (created :initarg :created :initform nil) + (updated :initarg :updated :initform nil) + (summary :initarg :summary :initform nil) + (commentary :initarg :commentary :initform nil) + (libraries :initarg :libraries + :columns [package library]) + (provided :initarg :provided + :columns [package feature drop join]) + (required :initarg :required + :columns [package feature hard ease drop]) + (keywords :initarg :keywords + :columns [package keyword]) + (authors :initarg :authors + :columns [package name email] + :primkey [package name email]) + (maintainers :initarg :maintainers + :columns [package name email] + :primkey [package name email])) + :abstract t) + +;;; Subclasses + +(defclass epkg-mirrored-package (epkg-package) + ((mirrorpage-format :initform "https://github.com/emacsmirror/%m") + (mirror-url-format :initform "git@github.com:emacsmirror/%m.git")) + :abstract t) + +(defclass epkg-file-package (epkg-mirrored-package) ()) + +(defclass epkg-gitish-package (epkg-mirrored-package) () :abstract t) + +(defclass epkg-git-package (epkg-gitish-package) ()) + +(defclass epkg-github-package (epkg-git-package) + ((url-format :initform "git@github.com:%u/%n.git") + (repopage-format :initform "https://github.com/%u/%n"))) + +(defclass epkg-orphaned-package (epkg-github-package) + ((url-format :initform "git@github.com:emacsorphanage/%n.git") + (repopage-format :initform "https://github.com/emacsorphanage/%n"))) + +(defclass epkg-gitlab-package (epkg-git-package) + ((url-format :initform "git@gitlab.com:%u/%n.git") + (repopage-format :initform "https://gitlab.com/%u/%n"))) + +(defclass epkg-subtree-package (epkg-git-package) ()) + +(defclass epkg-subset-package (epkg-gitish-package) () :abstract t) + +(defclass epkg-wiki-package (epkg-subset-package) + ((url-format :initform "git@github:emacsmirror/emacswiki.org.git") + (repopage-format :initform "https://github.com/emacsmirror/emacswiki.org") + (homepage-format :initform "http://emacswiki.org/emacs/download/%n.el"))) + +(defclass epkg-elpa-package (epkg-subset-package) + ((url-format :initform "git://git.savannah.gnu.org/emacs/elpa.git") + (repopage-format :initform "http://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/packages/%n") + (homepage-format :initform "https://elpa.gnu.org/packages/%n.html"))) + +(defclass epkg-elpa-branch-package (epkg-subset-package) + ((url-format :initform "git://git.savannah.gnu.org/emacs/elpa.git") + (repopage-format :initform "http://git.savannah.gnu.org/cgit/emacs/elpa.git/log/?h=externals/%n") + (homepage-format :initform "https://elpa.gnu.org/packages/%n.html"))) + +(defclass epkg-hg-package (epkg-gitish-package) ()) + +(defclass epkg-bitbucket-package (epkg-hg-package) + ((url-format :initform "hg::ssh://hg@bitbucket.org/%u/%n") + (repopage-format :initform "https://bitbucket.org/%u/%n"))) + +(defclass epkg-mocking-package (epkg-package) () :abstract t) + +(defclass epkg-builtin-package (epkg-mocking-package) + ((url-format :initform "git://git.savannah.gnu.org/emacs.git") + (repopage-format :initform "http://git.savannah.gnu.org/cgit/emacs.git") + (homepage-format :initform "http://www.gnu.org/software/emacs"))) + +(defclass epkg-shelved-package (epkg-mocking-package) + ((mirrorpage-format :initform "https://github.com/emacsattic/%m") + (mirror-url-format :initform "git@github.com:emacsattic/%m.git"))) + +;;; Interfaces + +(defun epkg-sql (sql &rest args) + "Send SQL s-expression to the Epkg database and return the result." + (if (stringp sql) + (emacsql (epkg-db) (apply #'format sql args)) + (apply #'emacsql (epkg-db) sql args))) + +(defun epkgs (&optional select predicates) + "Return a list of `epkg-package' objects or a list of rows. + +The list is ordered by the package names in ascending order. + +If optional SELECT is non-nil, then it has to be a list of +columns of the `packages' table. In that case the returned +value is a list of database rows. + +If optional PREDICATES is non-nil, then it has to be a list of +package class predicate functions, or a single such function. +Valid functions are named either `epkg-TYPE-package-p' or +`epkg-TYPE-package--eieio-childp'. Only packages are returned +for which one of these predicates returns non-nil." + (if select + (let ((value (closql-select (epkg-db) select predicates))) + (if (and select (symbolp select)) + (mapcar #'car value) + value)) + (closql-entries (epkg-db) predicates))) + +(cl-defmethod epkg ((name string)) + "Return an `epkg-package' object for the package named NAME. +NAME is the name of a package, a string." + (closql-get (epkg-db) name)) + +(cl-defgeneric epkg-provided (package) + "Return a list of features provided by PACKAGE. + +Each element has the form (PACKAGE FEATURE...), where PACKAGE +is the name of a package, a string, and FEATURE is a feature +provided by that package. If FEATURE is a symbol, then it is +a hard (mandatory) dependency; if it is a string, then it is +a soft (optional) dependency.") + +(cl-defmethod epkg-provided ((pkg epkg-package)) + "Return a list of features provided by the package PKG. +PKG is an `epkg-package' object." + (epkg-provided (oref pkg name))) + +(cl-defmethod epkg-provided ((package string)) + "Return a list of features provided by PACKAGE. +PACKAGE is the name of a package, a string." + (mapcar #'car (epkg-sql [:select feature :from provided + :where (= package $s1) + :order-by [(asc feature)]] package))) + +(cl-defgeneric epkg-provided (package) + "Return a list of packages and features required by PACKAGE.") + +(cl-defmethod epkg-required ((pkg epkg-package)) + "Return a list of packages and features required by the package PKG. +PKG is an `epkg-package' object." + (epkg-required (oref pkg name))) + +(cl-defmethod epkg-required ((package string)) + "Return a list of packages and features required by PACKAGE. +PACKAGE is the name of a package, a string." + (let (deps) + (-each (epkg-sql [:select [feature hard] :from required + :where (= package $s1) + :order-by [(asc feature)]] + package) + (-lambda ((feature hard)) + (let ((feature* (if hard feature (symbol-name feature)))) + (if-let ((package* (epkg--required package feature))) + (unless (equal package* package) + (if-let ((elt (assoc package* deps))) + (push feature* (cdr elt)) + (push (list package* feature*) deps))) + (push (list nil feature*) deps))))) + (cl-sort (mapcar (-lambda ((package . features)) + (cons package (sort features #'string<))) + deps) + #'string< :key #'car))) + +(cl-defmethod epkg--required ((package string) feature) + (or (epkg--required (if (symbolp feature) feature (intern feature))) + (let ((string (if (stringp feature) feature (symbol-name feature)))) + ;; Some packages require `NAME-autoloads' or `NAME-loaddefs', + ;; others require `OTHER-autoloads' or `OTHER-loaddefs'. Assume + ;; that building the package which provides `NAME' or `OTHER' + ;; also generates a file which provides the autoloads feature. + (or (and (string-equal string (concat package "-autoloads")) package) + (and (string-equal string (concat package "-loaddefs")) package) + (and (string-suffix-p "-autoloads" string) + (epkg--required (intern (substring string 0 -10)))) + (and (string-suffix-p "-loaddefs" string) + (epkg--required (intern (substring string 0 -9)))) + ;; Some packages require `NAME-version'. Assume that when + ;; `NAME' is build, a file which provides `NAME-version' is + ;; also generated. + (and (string-equal string (concat package "-version")) package) + ;; We ignore files ending with `-test' or `-tests' to avoid + ;; dependencies that are only required to run the tests. In + ;; rare cases `NAME' does require `NAME-test', which might + ;; then lead to unsatisfied, because unlisted, dependencies. + ;; Nevertheless we assume that `NAME-test' is part of `NAME'. + (and (string-equal string (concat package "-test")) package) + (and (string-equal string (concat package "-tests")) package))))) + +(cl-defmethod epkg--required ((feature symbol)) + (let ((packages (mapcar #'car + (epkg-sql [:select package :from provided + :where (= feature $s1) + :order-by [(asc package)]] feature)))) + (if (= (length packages) 1) + (car packages) + (let ((alist (--map (cons it (epkg it)) packages))) + (car (or (--first (cl-typep (cdr it) 'epkg-builtin-package) alist) + (--first (and (cl-typep (cdr it) 'epkg-mirrored-package) + (equal (car it) (symbol-name feature))) + alist) + (--first (cl-typep (cdr it) 'epkg-mirrored-package) alist) + (--first (equal (car it) (symbol-name feature)) alist) + (car alist))))))) + +(cl-defgeneric epkg-reverse-dependencies (package) + "Return a list of packages which depend on PACKAGE. + +Each element has the form (PACKAGE FEATURE...), where PACKAGE +is the name of a package, a string, and FEATURE is a feature +required by that package. If FEATURE is a symbol, then it is +a hard (mandatory) dependency; if it is a string, then it is +a soft (optional) dependency.") + +(cl-defmethod epkg-reverse-dependencies ((pkg epkg-package)) + "Return a list of packages which depend on PKG. +PKG is an `epkg-package' object." + (epkg-reverse-dependencies (oref pkg name))) + +(cl-defmethod epkg-reverse-dependencies ((package string)) + "Return a list of packages which depend on PACKAGE. +PACKAGE is the name of a package, a string." + (mapcar (-lambda ((package . required)) + (cons package (mapcar (-lambda ((_ feature hard)) + (if hard feature (symbol-name feature))) + required))) + (cl-sort + (-group-by #'car + (epkg-sql [:select [package feature hard] :from required + :where feature :in $v1] + (vconcat (epkg-provided package)))) + #'string< :key #'car))) + +(cl-defmethod epkg-type ((pkg epkg-package)) + "Return the type of the Epkg object PKG." + (epkg-type (eieio-object-class pkg))) + +(cl-defmethod epkg-type ((class (subclass epkg-package))) + "Return a short representation of CLASS." + (if (eq class 'epkg-package) + 'all + (setq class (symbol-name class)) + (when (string-match "\\`epkg-\\(.+\\)-package\\'" class) + (intern (match-string 1 class))))) + +(cl-defun epkg-package-types (&optional subtypes) + "Return a list of all package types. + +If optional SUBTYPES is non-nil, then also return symbols of +the form `TYPE*', which stands for `TYPE' and its subtypes." + (cl-labels + ((types (class) + (let ((children (eieio--class-children (cl--find-class class))) + (type (epkg-type class))) + (nconc (and (not (class-abstract-p class)) (list type)) + (and subtypes children + (list (intern (format "%s*" type)))) + (cl-mapcan #'types children))))) + (sort (types 'epkg-package) #'string<))) + +(defvar epkg-type-history nil) + +(defun epkg-read-type (prompt &optional default subtypes) + "Read an Epkg type and return it as a symbol. + +If optional DEFAULT is non-nil, then that is offered as default +choice. If optional CHILDP is non-nil, then entries of the form +`TYPE*', which stands for \"`TYPE' and its subtypes\", are also +offered as completion candidates." + (intern (completing-read prompt (epkg-package-types subtypes) + nil t nil 'epkg-type-history default))) + +(defvar epkg-package-history nil) + +(defun epkg-read-package (prompt &optional default) + "Read the name of an Epkg package and return it as a string. + +Optional DEFAULT, if non-nil, is offered as default choice." + (completing-read prompt (epkgs 'name) nil t nil + 'epkg-package-history default)) + +(provide 'epkg) +(require 'epkg-desc) +(require 'epkg-list) +;;; epkg.el ends here diff --git a/epkg.org b/epkg.org new file mode 100644 index 0000000..4f10b75 --- /dev/null +++ b/epkg.org @@ -0,0 +1,504 @@ +#+TITLE: Epkg User Manual +#+AUTHOR: Jonas Bernoulli +#+EMAIL: jonas@bernoul.li +#+DATE: 2016 +#+LANGUAGE: en + +#+TEXINFO_DIR_CATEGORY: Emacs +#+TEXINFO_DIR_TITLE: Epkg: (epkg). +#+TEXINFO_DIR_DESC: Browse the Emacsmirror's database +#+SUBTITLE: for version 1.0 + +#+OPTIONS: H:4 num:3 toc:2 + +* Copying +:PROPERTIES: +:COPYING: t +:END: + +#+BEGIN_TEXINFO +@ifnottex +With @code{epkg} you can browse the Emacsmirror package database +using an interface similar to that of @code{package.el}. +@end ifnottex + +@quotation +Copyright (C) 2016 Jonas Bernoulli + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +@end quotation +#+END_TEXINFO + +* Introduction + +Epkg is a package that provides access to a local copy of the +Emacsmirror package database. It provides low-level functions for +querying the database and a ~package.el~-like user interface for +browsing the database. Epkg itself is not a package manager. + +The Emacsmirror is a growing collection of Emacs Lisp packages. All +mirrored packages are available as Git repositories. In most cases +this is done by mirroring the upstream Git repository, but if upstream +uses something else, then the mirror nevertheless makes the package +available as a Git repository. + +One primary purpose of the Emacsmirror is to provide a comprehensive +list of available Emacs packages, including packages which have gone +out of fashion (but might later prove to be useful still). + +Older efforts attempting to provide a comprehensive list of available +packages, such as the Emacs Lisp List, over time collected an +impressive list of dead links to packages which were no longer +available anywhere. + +With the Emacsmirror this won't happen. If a package's upstream +disappears, then a copy remains available on the mirror. Once its +upstream has disappeared a package is usually moved from the +Emacsmirror to the Emacsattic, where it is no longer updated. (The +Emacsattic is a Github "organization" separate from the Emacsmirror +organization, but it is considered part of the Emacsmirror project.) + +For more information about the Emacsmirror see +https://emacsmirror.net. + +* Installation + +Epkg currently requires an Emacs pre-release, at least ~25.0.92~. In +the future at least the latest stable release will be supported. +Emacs ~24.5~ cannot be supported because some build-in libraries that +are essential to Epkg have changed drastically since that was +released. + +Epkg is available from Melpa and Melpa-Stable. To install it and its +dependencies run ~M-x install-package RET epkg RET~. + +The Epkg database is stored in an SQLite database, which it accesses +using the EmacSQL package. + +Because the command line tool that comes with SQLite is unreliable, +EmacSQL uses its own binary. By default that binary is compiled every +time EmacSQL is updated, and if that fails, then EmacSQL asks whether +you want to download a pre-build binary. + +The SQLite database file is stored in a Git repository. If Epkg +cannot find your local clone of that repository, then it offers to +clone it to the location specified by the option ~epkg-repository~. It +isn't necessary but preferable to clone the repository manually before +loading ~epkg~. + +#+BEGIN_SRC shell + git clone https://github.com/emacsmirror/epkgs.git ~/.emacs.d/epkgs +#+END_SRC + +If you cloned the repository to a different location, then you have to +set the value of ~epkg-repository~ accordingly. Add the following to +your init file and don't forget to evaluate that form so that it also +takes effect in the current session. To do so place the cursor after +the closing parentheses and type ~C-M-x~. + +#+BEGIN_SRC shell + (setq epkg-repository "/path/to/epkgs/") +#+END_SRC + +- User Option: epkg-repository + + This option specifies the location of the local Emacsmirror + repository. + + This repository contains the Epkg SQLite database and, if they have + been initialized, all package repositories from the Emacsmirror and + Emacsattic as submodules. + + If you change the value of this option, then you should also + manually move the repository. Otherwise it would be cloned again. + +The local clone of the Epkg repository is not updated automatically, +so you should periodically use ~M-x epkg-update RET~ to update the +database. + +* Listing Packages + +Epkg provides several commands for listing packages. + +In the buffer which lists packages, typing ~RET~ displays information +about the package at point in another buffer. + +- User Option: epkg-list-packages-omit-shelved + + This option controls whether commands that list Epkg packages omit + shelved packages. By default that is the case. + + Shelved packages are those that are no longer updated, and which are + available from the Emacsattic instead of the Emacsmirror. + + The command ~epkg-list-packages-of-type~ is not affected by this + option, and neither is ~epkg-describe-package~. + +- User Option: epkg-list-columns + + This option lists the columns used in buffers that list packages. + + Each element has the form ~(HEADER WIDTH SORTP PROPS SLOT FORMAT)~. + HEADER is the string displayed in the header. WIDTH is the width + of the column. If SORTP is ~t~, then the column can be sorted, if + it is ~nil~ then it can not. PROPS is an alist, supported keys are + ~:right-align~ and ~:pad-right~. Slot is an Epkg object slot or ~type~. + FORMAT is a function, which is called with one argument the slot + value and has to return a representation of that. If FORMAT is ~nil~, + then the value is inserted as-is. + +- User Option: epkg-list-mode-hook + + This hook is run after entering Epkg-List mode, the mode used in + buffers which list packages. + +- Command: epkg-list-packages + + This command displays a list of packages. + +- Command: epkg-list-matching-packages + + This command displays a list of packages whose summaries match a + regular expression, which is read in the minibuffer. + +- Command: epkg-list-keyworded-packages + + This command displays a list of packages that have a keyword set, + which is read in the minibuffer. + + Only keywords that are members of ~finder-known-keywords~ are offered + as completion candidates, but you can also enter other keywords. + +- Command: epkg-list-packages-by-author + + This command displays a list of packages which are authored or + maintained by a person. The person, a name or email address, is + read in the minibuffer. + +By default all of the above commands omit shelved +packages from their output. With a prefix argument or when +~epkg-list-packages-omit-shelved~ is ~nil~, then they don't omit any +packages. However the following command ignores this option and +always lists shelved packages when appropriate. + +- Command: epkg-list-packages-of-type + + This command displays a list of packages of a certain type. The + type is read in the minibuffer. To list all packages of a certain + type and its subtypes use ~TYPE*~ instead of just ~TYPE~. + +* Describing a Package + +To display details about a single package in a buffer use the command +~epkg-describe-package~. In buffers which list packages ~RET~ is bound +to ~epkg-list-describe-package~, which displays the package at point in +another buffer. + +By default the description buffer shows a tree of the packages the +described package depends on. Click on a square before the package +name to expand the node to show the dependencies of that dependency. + +The first column lists the names of package which provide the +feature(s) in the third column. The second column shows the type of +the package in the first column. + +The features in the third column are displayed in bold or using the +regular font weight to indicate whether it is a hard (mandatory) or +soft (optional) dependency. + +Note that dependencies are determined automatically and even when a +feature is shown using a bold face it might actually be optional. +This could for example be the case when a feature is only required by +one library that isn't required by any of the other libraries of the +package it belongs to. Or a feature might even only be required by a +single command, and the respective ~require~ form is only evaluated when +that command is called. + +Reverse dependencies are also displayed in a second tree. Here the +first column lists the names of packages which depend on features from +the described package and the third column shows which of these +libraries are required. + +- Command: epkg-describe-package + + This command displays information about a package in a separate + buffer. The name of the package to be displayed is read in the + minibuffer. + +- Command: epkg-list-describe-package + + This command displays information about the package at point in + a separate buffer. + + It is only intended to be used in buffers which list packages. + In other buffers, or in a list buffer when you want to display a + package other than the one at point use ~epkg-describe-package~. + +- User Option: epkg-describe-package-slots + + The value of this option is a list of slots to be displayed when + displaying information about an Epkg package in a help buffer. + + Each element of the list can be a slot symbol, a function, or ~nil~. + Functions are called with one argument, the Epkg object, and should + insert a representation of the value at point. Raw slot symbols + cause its non-nil value to be inserted as-is. If a slot's value is + ~nil~, then nothing is inserted. Elements that are ~nil~ stand for + empty lines. + +- User Option: epkg-describe-package-slots-width + + The value of this option specifies the width used to display slot + names in buffers displaying information about an Epkg package. + +* Package Types + +Each package has a "type", which specifies how the package is +distributed and mirrored. + +Packages are implemented using the Eieio (CLOS) object system. A TYPE +corresponds to the class ~epkg-TYPE-package~. The ~epkg~ package makes +little use of methods, but ~emir~, the package used to maintain the +Emacsmirror, makes extensive use of them. There exist five abstract +classes (there are no instances of abstract classes, only of its +subclasses): ~epkg-package~, ~epkg-mirrored-package~, ~epkg-gitish-package~, +~epkg-subset-package~, and ~epkg-mocking-package~. Except for the second +these classes are mostly an implementation detail and not relevant +when merely using Epkg to browse the packages. + +- ~mirrored~ + + This is an abstract type. Unlike other abstract types it is also + useful on the client side, e.g. when you want to list mirrored + packages, but not built-in and shelved packages. + + Packages that are available as a repository on the Emacsmirror + (https://github.com/emacsmirror). + + - ~file~ + + Packages that are distributed as plain files. + + - ~gitish~ + + This is an abstract type, useful when maintaining the mirror. + + Git and Mercurial packages. The name is due to an implementation + detail: ~hg~ is never run directly, instead ~git-remote-hg~ is used. + + - ~git~ + + Git packages. + + - ~github~ + + Packages hosted on https://github.com. + + - ~orphaned~ + + Packages that are no longer maintained, but which still have + to be mirrored because other packages depend on them. + Please consider adopting an orphaned package. + + - ~gitlab~ + + Packages hosted on https://gitlab.com. + + - ~subtree~ + + Packages that are located in a subtree of a Git repository. + The repository on the Emacsmirror limits the history to just + that directory using ~git subtree~. + + - ~subset~ + + This is an abstract type, useful when maintaining the mirror. + + - ~wiki~ + + Packages hosted as plain files on https://emacswiki.org. + + - ~elpa~ + + Packages hosted in a directory inside the ~master~ branch of + the GNU Elpa repository. + + - ~elpa-branch~ + + Packages hosted in the GNU Elpa repository, using a + dedicated branch. + + - ~hg~ + + Mercurial packages. + + - ~bitbucket~ + + Packages hosted on https://bitbucket.org in a Mercurial + repository. Packages hosted in a Git repository on Bitbucket + have the type ~git~. + +- ~mocking~ + + This is an abstract type, useful when maintaining the mirror. + + Packages that are /not/ available as a repository on the Emacsmirror + (https://github.com/emacsmirror). + + - ~builtin~ + + Packages that are part of GNU Emacs version 25.0.92 (in the future + the latest stable release will be targeted). ~emacs~ is on of the + packages that are "part of Emacs"; it contains all libraries that + are not explicitly declared to be part of some built-in package. + + - ~shelved~ + + Packages that are available as a repository on the Emacsattic + (https://github.com/emacsattic). + + These repository are not being updated anymore, because upstream + has disappeared or because the package has issues which have to be + resolved before it can be moved back to the Emacsmirror. + +* Updating the Database + +- Command: epkg-update + + This command updates the Epkg database by pulling the ~master~ branch + in the ~epkg-repository~ and then reloading the Epkg database. It + returns the database connection. + +* Querying the Database + +- Function: epkg-db + + This function returns the connection to the Epkg database. + + If the ~epkg-repository~, which contains the SQLite database file, + does not exist yet, then this function first asks the user whether + they want to clone the repository. + +- Function: epkg-sql sql &rest args + + This function sends the SQL s-expression to the Epkg database and + returns the result. This is a wrapper around ~emacsql~ that lacks the + CONNECTION argument. Instead it uses the connection returned by + ~epkg-db~. + +- Function: epkg name + + This function returns an ~epkg-package~ object for the package named + NAME. NAME is the name of a package, a string. + +- Function: epkgs &optional select predicates + + This function returns a list of ~epkg-package~ objects or a list of + database rows. The list is ordered by the package names in + ascending order. + + If optional SELECT is non-nil, then it has to be a list of columns + of the ~packages~ table. In that case the returned value is a list of + database rows. + + If optional PREDICATES is non-nil, then it has to be a list of + package class predicate functions, or a single such function. + Valid functions are named either ~epkg-TYPE-package-p~ or + ~epkg-TYPE-package--eieio-childp~. Only packages are returned + for which one of these predicates returns non-nil. + + This function is more limited than ~epkg-sql~ but it's often much less + verbose. For example ~(epkgs nil 'epkg-gitlab-package-p)~ returns the + same value as: + + #+BEGIN_SRC emacs-lisp + (mapcar (apply-partially #'closql--remake-instance (epkg-db)) + (epkg-sql [:select * :from packages + :where class :in $v1 + :order-by [(asc name)]] + (closql--where-class-in (epkg-db) + 'epkg-gitlab-package-p))) + #+END_SRC + +While it is possible to get a list of provided or required features, +or a package's type using ~oref~, the values of these slots contains +additional information, which is mostly useful when maintaining the +Emacsmirror, but not in a client. And the ~required~ slot only lists +features but not the packages that provide them. The following +functions return these values in a form that is generally more useful. + +- Function: epkg-provided package + + This function returns a list of features provided by the package + PACKAGE. PACKAGE is an ~epkg-package~ object or a package name, a + string. + +- Function: epkg-required package + + This function returns a list of packages and features required by + the package PACKAGE. PACKAGE is an ~epkg-package~ object or a package + name, a string. + + Each element has the form ~(PACKAGE FEATURE...)~, where PACKAGE is the + name of a package, a string, and FEATURE is a feature provided by + that package. If FEATURE is a symbol, then it is a hard (mandatory) + dependency; if it is a string, then it is a soft (optional) + dependency. + + PACKAGE is ~nil~ if it is unknown which package provides the FEATURE. + When a dependency cannot be resolved then this function in some + cases uses a heuristic to guess the correct package or to ignore a + self-referential dependency. This is the case when the FEATURE is + one of ~NAME-autoloads~, ~NAME-loaddefs~, ~NAME-version~, ~NAME-test~, and + ~NAME-tests~. + +- Function: epkg-reverse-dependencies package + + This function returns a list of packages which depend on PACKAGE. + + Each element has the form ~(PACKAGE FEATURE...)~, where PACKAGE is the + name of a package, a string, and FEATURE is a feature required by + that package. If FEATURE is a symbol, then it is a hard (mandatory) + dependency; if it is a string, then it is a soft (optional) + dependency. + +- Function: epkg-type pkg + + This function returns the type of the ~epkg-package~ object PKG. + + A package's type is a short representation of its class, as in + ~epkg-TYPE-package~. The argument may also be a class symbol, in + which case the respective type is returned. The type of ~epkg-package~ + itself is ~all~. + +- Function: epkg-package-types subtypes + + This function returns a list of all package types. + + If optional SUBTYPES is non-nil, then it also returns symbols of the + form ~TYPE*~, which stands for "~TYPE~ and its subtypes". + +- Function: epkg-read-type prompt &optional default subtypes + + This function reads an Epkg type in the minibuffer and returns it as + a symbol. + + If optional DEFAULT is non-nil, then that is offered as default + choice. If optional CHILDP is non-nil, then entries of the form + ~TYPE*~, which stands for "~TYPE~ and its subtypes", are also offered + as completion candidates. + +- Function: epkg-read-package prompt &optional default + + This function reads the name of an Epkg package in the minibuffer + and returns it as a string. + + Optional DEFAULT, if non-nil, is offered as default choice. diff --git a/epkg.texi b/epkg.texi new file mode 100644 index 0000000..b1ecd3e --- /dev/null +++ b/epkg.texi @@ -0,0 +1,613 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename ./epkg.info +@settitle Epkg User Manual +@documentencoding UTF-8 +@documentlanguage en +@c %**end of header + +@copying +@ifnottex +With @code{epkg} you can browse the Emacsmirror package database +using an interface similar to that of @code{package.el}. +@end ifnottex + +@quotation +Copyright (C) 2016 Jonas Bernoulli + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Epkg: (epkg). Browse the Emacsmirror's database. +@end direntry + +@finalout +@titlepage +@title Epkg User Manual +@subtitle for version 1.0 +@author Jonas Bernoulli +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Epkg User Manual +@insertcopying +@end ifnottex + +@menu +* Introduction:: +* Installation:: +* Listing Packages:: +* Describing a Package:: +* Package Types:: +* Updating the Database:: +* Querying the Database:: +@end menu + + + +@node Introduction +@chapter Introduction + +Epkg is a package that provides access to a local copy of the +Emacsmirror package database. It provides low-level functions for +querying the database and a @code{package.el}-like user interface for +browsing the database. Epkg itself is not a package manager. + +The Emacsmirror is a growing collection of Emacs Lisp packages. All +mirrored packages are available as Git repositories. In most cases +this is done by mirroring the upstream Git repository, but if upstream +uses something else, then the mirror nevertheless makes the package +available as a Git repository. + +One primary purpose of the Emacsmirror is to provide a comprehensive +list of available Emacs packages, including packages which have gone +out of fashion (but might later prove to be useful still). + +Older efforts attempting to provide a comprehensive list of available +packages, such as the Emacs Lisp List, over time collected an +impressive list of dead links to packages which were no longer +available anywhere. + +With the Emacsmirror this won't happen. If a package's upstream +disappears, then a copy remains available on the mirror. Once its +upstream has disappeared a package is usually moved from the +Emacsmirror to the Emacsattic, where it is no longer updated. (The +Emacsattic is a Github "organization" separate from the Emacsmirror +organization, but it is considered part of the Emacsmirror project.) + +For more information about the Emacsmirror see +@uref{https://emacsmirror.net}. + +@node Installation +@chapter Installation + +Epkg currently requires an Emacs pre-release, at least @code{25.0.92}. In +the future at least the latest stable release will be supported. +Emacs @code{24.5} cannot be supported because some build-in libraries that +are essential to Epkg have changed drastically since that was +released. + +Epkg is available from Melpa and Melpa-Stable. To install it and its +dependencies run @code{M-x install-package RET epkg RET}. + +The Epkg database is stored in an SQLite database, which it accesses +using the EmacSQL package. + +Because the command line tool that comes with SQLite is unreliable, +EmacSQL uses its own binary. By default that binary is compiled every +time EmacSQL is updated, and if that fails, then EmacSQL asks whether +you want to download a pre-build binary. + +The SQLite database file is stored in a Git repository. If Epkg +cannot find your local clone of that repository, then it offers to +clone it to the location specified by the option @code{epkg-repository}. It +isn't necessary but preferable to clone the repository manually before +loading @code{epkg}. + +@example +git clone https://github.com/emacsmirror/epkgs.git ~/.emacs.d/epkgs +@end example + +If you cloned the repository to a different location, then you have to +set the value of @code{epkg-repository} accordingly. Add the following to +your init file and don't forget to evaluate that form so that it also +takes effect in the current session. To do so place the cursor after +the closing parentheses and type @code{C-M-x}. + +@example +(setq epkg-repository "/path/to/epkgs/") +@end example + +@defopt epkg-repository + +This option specifies the location of the local Emacsmirror +repository. + +This repository contains the Epkg SQLite database and, if they have +been initialized, all package repositories from the Emacsmirror and +Emacsattic as submodules. + +If you change the value of this option, then you should also +manually move the repository. Otherwise it would be cloned again. +@end defopt + +The local clone of the Epkg repository is not updated automatically, +so you should periodically use @code{M-x epkg-update RET} to update the +database. + +@node Listing Packages +@chapter Listing Packages + +Epkg provides several commands for listing packages. + +In the buffer which lists packages, typing @code{RET} displays information +about the package at point in another buffer. + +@defopt epkg-list-packages-omit-shelved + +This option controls whether commands that list Epkg packages omit +shelved packages. By default that is the case. + +Shelved packages are those that are no longer updated, and which are +available from the Emacsattic instead of the Emacsmirror. + +The command @code{epkg-list-packages-of-type} is not affected by this +option, and neither is @code{epkg-describe-package}. +@end defopt + +@defopt epkg-list-columns + +This option lists the columns used in buffers that list packages. + +Each element has the form @code{(HEADER WIDTH SORTP PROPS SLOT FORMAT)}. +HEADER is the string displayed in the header. WIDTH is the width +of the column. If SORTP is @code{t}, then the column can be sorted, if +it is @code{nil} then it can not. PROPS is an alist, supported keys are +@code{:right-align} and @code{:pad-right}. Slot is an Epkg object slot or @code{type}. +FORMAT is a function, which is called with one argument the slot +value and has to return a representation of that. If FORMAT is @code{nil}, +then the value is inserted as-is. +@end defopt + +@defopt epkg-list-mode-hook + +This hook is run after entering Epkg-List mode, the mode used in +buffers which list packages. +@end defopt + +@cindex epkg-list-packages +@deffn Command epkg-list-packages + +This command displays a list of packages. +@end deffn + +@cindex epkg-list-matching-packages +@deffn Command epkg-list-matching-packages + +This command displays a list of packages whose summaries match a +regular expression, which is read in the minibuffer. +@end deffn + +@cindex epkg-list-keyworded-packages +@deffn Command epkg-list-keyworded-packages + +This command displays a list of packages that have a keyword set, +which is read in the minibuffer. + +Only keywords that are members of @code{finder-known-keywords} are offered +as completion candidates, but you can also enter other keywords. +@end deffn + +@cindex epkg-list-packages-by-author +@deffn Command epkg-list-packages-by-author + +This command displays a list of packages which are authored or +maintained by a person. The person, a name or email address, is +read in the minibuffer. +@end deffn + +By default all of the above commands omit shelved +packages from their output. With a prefix argument or when +@code{epkg-list-packages-omit-shelved} is @code{nil}, then they don't omit any +packages. However the following command ignores this option and +always lists shelved packages when appropriate. + +@cindex epkg-list-packages-of-type +@deffn Command epkg-list-packages-of-type + +This command displays a list of packages of a certain type. The +type is read in the minibuffer. To list all packages of a certain +type and its subtypes use @code{TYPE*} instead of just @code{TYPE}. +@end deffn + +@node Describing a Package +@chapter Describing a Package + +To display details about a single package in a buffer use the command +@code{epkg-describe-package}. In buffers which list packages @code{RET} is bound +to @code{epkg-list-describe-package}, which displays the package at point in +another buffer. + +By default the description buffer shows a tree of the packages the +described package depends on. Click on a square before the package +name to expand the node to show the dependencies of that dependency. + +The first column lists the names of package which provide the +feature(s) in the third column. The second column shows the type of +the package in the first column. + +The features in the third column are displayed in bold or using the +regular font weight to indicate whether it is a hard (mandatory) or +soft (optional) dependency. + +Note that dependencies are determined automatically and even when a +feature is shown using a bold face it might actually be optional. +This could for example be the case when a feature is only required by +one library that isn't required by any of the other libraries of the +package it belongs to. Or a feature might even only be required by a +single command, and the respective @code{require} form is only evaluated when +that command is called. + +Reverse dependencies are also displayed in a second tree. Here the +first column lists the names of packages which depend on features from +the described package and the third column shows which of these +libraries are required. + +@cindex epkg-describe-package +@deffn Command epkg-describe-package + +This command displays information about a package in a separate +buffer. The name of the package to be displayed is read in the +minibuffer. +@end deffn + +@cindex epkg-list-describe-package +@deffn Command epkg-list-describe-package + +This command displays information about the package at point in +a separate buffer. + +It is only intended to be used in buffers which list packages. +In other buffers, or in a list buffer when you want to display a +package other than the one at point use @code{epkg-describe-package}. +@end deffn + +@defopt epkg-describe-package-slots + +The value of this option is a list of slots to be displayed when +displaying information about an Epkg package in a help buffer. + +Each element of the list can be a slot symbol, a function, or @code{nil}. +Functions are called with one argument, the Epkg object, and should +insert a representation of the value at point. Raw slot symbols +cause its non-nil value to be inserted as-is. If a slot's value is +@code{nil}, then nothing is inserted. Elements that are @code{nil} stand for +empty lines. +@end defopt + +@defopt epkg-describe-package-slots-width + +The value of this option specifies the width used to display slot +names in buffers displaying information about an Epkg package. +@end defopt + +@node Package Types +@chapter Package Types + +Each package has a "type", which specifies how the package is +distributed and mirrored. + +Packages are implemented using the Eieio (CLOS) object system. A TYPE +corresponds to the class @code{epkg-TYPE-package}. The @code{epkg} package makes +little use of methods, but @code{emir}, the package used to maintain the +Emacsmirror, makes extensive use of them. There exist five abstract +classes (there are no instances of abstract classes, only of its +subclasses): @code{epkg-package}, @code{epkg-mirrored-package}, @code{epkg-gitish-package}, +@code{epkg-subset-package}, and @code{epkg-mocking-package}. Except for the second +these classes are mostly an implementation detail and not relevant +when merely using Epkg to browse the packages. + +@itemize +@item +@code{mirrored} + +This is an abstract type. Unlike other abstract types it is also +useful on the client side, e.g. when you want to list mirrored +packages, but not built-in and shelved packages. + +Packages that are available as a repository on the Emacsmirror +(@uref{https://github.com/emacsmirror}). + +@itemize +@item +@code{file} + +Packages that are distributed as plain files. + + +@item +@code{gitish} + +This is an abstract type, useful when maintaining the mirror. + +Git and Mercurial packages. The name is due to an implementation +detail: @code{hg} is never run directly, instead @code{git-remote-hg} is used. + +@itemize +@item +@code{git} + +Git packages. + +@itemize +@item +@code{github} + +Packages hosted on @uref{https://github.com}. + +@itemize +@item +@code{orphaned} + +Packages that are no longer maintained, but which still have +to be mirrored because other packages depend on them. +Please consider adopting an orphaned package. +@end itemize + + +@item +@code{gitlab} + +Packages hosted on @uref{https://gitlab.com}. + + +@item +@code{subtree} + +Packages that are located in a subtree of a Git repository. +The repository on the Emacsmirror limits the history to just +that directory using @code{git subtree}. + + +@item +@code{subset} + +This is an abstract type, useful when maintaining the mirror. + +@itemize +@item +@code{wiki} + +Packages hosted as plain files on @uref{https://emacswiki.org}. + + +@item +@code{elpa} + +Packages hosted in a directory inside the @code{master} branch of +the GNU Elpa repository. + + +@item +@code{elpa-branch} + +Packages hosted in the GNU Elpa repository, using a +dedicated branch. +@end itemize +@end itemize + + +@item +@code{hg} + +Mercurial packages. + +@itemize +@item +@code{bitbucket} + +Packages hosted on @uref{https://bitbucket.org} in a Mercurial +repository. Packages hosted in a Git repository on Bitbucket +have the type @code{git}. +@end itemize +@end itemize +@end itemize + + +@item +@code{mocking} + +This is an abstract type, useful when maintaining the mirror. + +Packages that are @emph{not} available as a repository on the Emacsmirror +(@uref{https://github.com/emacsmirror}). + +@itemize +@item +@code{builtin} + +Packages that are part of GNU Emacs version 25.0.92 (in the future +the latest stable release will be targeted). @code{emacs} is on of the +packages that are "part of Emacs"; it contains all libraries that +are not explicitly declared to be part of some built-in package. + + +@item +@code{shelved} + +Packages that are available as a repository on the Emacsattic +(@uref{https://github.com/emacsattic}). + +These repository are not being updated anymore, because upstream +has disappeared or because the package has issues which have to be +resolved before it can be moved back to the Emacsmirror. +@end itemize +@end itemize + +@node Updating the Database +@chapter Updating the Database + +@cindex epkg-update +@deffn Command epkg-update + +This command updates the Epkg database by pulling the @code{master} branch +in the @code{epkg-repository} and then reloading the Epkg database. It +returns the database connection. +@end deffn + +@node Querying the Database +@chapter Querying the Database + +@defun epkg-db + +This function returns the connection to the Epkg database. + +If the @code{epkg-repository}, which contains the SQLite database file, +does not exist yet, then this function first asks the user whether +they want to clone the repository. +@end defun + +@defun epkg-sql sql &rest args + +This function sends the SQL s-expression to the Epkg database and +returns the result. This is a wrapper around @code{emacsql} that lacks the +CONNECTION argument. Instead it uses the connection returned by +@code{epkg-db}. +@end defun + +@defun epkg name + +This function returns an @code{epkg-package} object for the package named +NAME. NAME is the name of a package, a string. +@end defun + +@defun epkgs &optional select predicates + +This function returns a list of @code{epkg-package} objects or a list of +database rows. The list is ordered by the package names in +ascending order. + +If optional SELECT is non-nil, then it has to be a list of columns +of the @code{packages} table. In that case the returned value is a list of +database rows. + +If optional PREDICATES is non-nil, then it has to be a list of +package class predicate functions, or a single such function. +Valid functions are named either @code{epkg-TYPE-package-p} or +@code{epkg-TYPE-package--eieio-childp}. Only packages are returned +for which one of these predicates returns non-nil. + +This function is more limited than @code{epkg-sql} but it's often much less +verbose. For example @code{(epkgs nil 'epkg-gitlab-package-p)} returns the +same value as: + +@lisp +(mapcar (apply-partially #'closql--remake-instance (epkg-db)) + (epkg-sql [:select * :from packages + :where class :in $v1 + :order-by [(asc name)]] + (closql--where-class-in (epkg-db) + 'epkg-gitlab-package-p))) +@end lisp +@end defun + +While it is possible to get a list of provided or required features, +or a package's type using @code{oref}, the values of these slots contains +additional information, which is mostly useful when maintaining the +Emacsmirror, but not in a client. And the @code{required} slot only lists +features but not the packages that provide them. The following +functions return these values in a form that is generally more useful. + +@defun epkg-provided package + +This function returns a list of features provided by the package +PACKAGE. PACKAGE is an @code{epkg-package} object or a package name, a +string. +@end defun + +@defun epkg-required package + +This function returns a list of packages and features required by +the package PACKAGE. PACKAGE is an @code{epkg-package} object or a package +name, a string. + +Each element has the form @code{(PACKAGE FEATURE...)}, where PACKAGE is the +name of a package, a string, and FEATURE is a feature provided by +that package. If FEATURE is a symbol, then it is a hard (mandatory) +dependency; if it is a string, then it is a soft (optional) +dependency. + +PACKAGE is @code{nil} if it is unknown which package provides the FEATURE. +When a dependency cannot be resolved then this function in some +cases uses a heuristic to guess the correct package or to ignore a +self-referential dependency. This is the case when the FEATURE is +one of @code{NAME-autoloads}, @code{NAME-loaddefs}, @code{NAME-version}, @code{NAME-test}, and +@code{NAME-tests}. +@end defun + +@defun epkg-reverse-dependencies package + +This function returns a list of packages which depend on PACKAGE. + +Each element has the form @code{(PACKAGE FEATURE...)}, where PACKAGE is the +name of a package, a string, and FEATURE is a feature required by +that package. If FEATURE is a symbol, then it is a hard (mandatory) +dependency; if it is a string, then it is a soft (optional) +dependency. +@end defun + +@defun epkg-type pkg + +This function returns the type of the @code{epkg-package} object PKG. + +A package's type is a short representation of its class, as in +@code{epkg-TYPE-package}. The argument may also be a class symbol, in +which case the respective type is returned. The type of @code{epkg-package} +itself is @code{all}. +@end defun + +@defun epkg-package-types subtypes + +This function returns a list of all package types. + +If optional SUBTYPES is non-nil, then it also returns symbols of the +form @code{TYPE*}, which stands for "@code{TYPE} and its subtypes". +@end defun + +@defun epkg-read-type prompt &optional default subtypes + +This function reads an Epkg type in the minibuffer and returns it as +a symbol. + +If optional DEFAULT is non-nil, then that is offered as default +choice. If optional CHILDP is non-nil, then the returned value also +contains entries of the form @code{TYPE*}, which stands for "@code{TYPE} and its +subtypes". +@end defun + +@defun epkg-read-package prompt &optional default + +This function reads the name of an Epkg package in the minibuffer +and returns it as a string. + +Optional DEFAULT, if non-nil, is offered as default choice. +@end defun + +@bye