+ "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.
+
Lutz Mueller, 2004-2007. Last edit 2007-8-28 rev 19
+
+
+
+ORO (One Reference Only) automatic memory management developed for newLISP is a fast and resources saving alternative to classic garbage collection algorithms in dynamic, interactive programming languages. This article explains how ORO memory management works
+
+
+
newLISP and any other interactive language system will constantly generate new memory objects during expression evaluation. The new memory objects are intermediate evaluation results, reassigned memory objects, or memory objects whose content was changed. If newLISP did not delete these objects, it would eventually run out of available memory.
+
+
In order to understand newLISP's automatic memory management, it is necessary to first review the traditional methods employed by other languages.
+
+
Traditional automatic memory management (Garbage Collection)
+
+
In most programming languages, a process registers allocated memory, and another process finds and recycles the unused parts of the allocated memory pool. The recycling process can be triggered by some memory allocation limit or can be scheduled to happen between evaluation steps. This form of automatic memory management is called Garbage Collection.
+
+
Traditional garbage collection schemes developed for LISP employed one of two algorithms¹:
+
+
(1) The mark-and-sweep algorithm registers each allocated memory object. A mark phase periodically flags each object in the allocated memory pool. A named object (a variable) directly or indirectly references each memory object in the system. The sweep phase frees the memory of the marked objects when they are no longer in use.
+
+
(2) A reference-counting scheme registers each allocated memory object together with a count of references to the object. This reference count gets incremented or decremented during expression evaluation. Whenever an object's reference count reaches zero, the object's allocated memory is freed.
+
+
Over time, many elaborate garbage collection schemes have been attempted using these algorithms. The first garbage collection algorithms appeared in LISP. The inventors of the Smalltalk language used more elaborate garbage collection schemes. The history of Smalltalk-80 is an exciting account of the challenges of implementing memory management in an interactive programming language; see [Glenn Krasner, 1983: Smalltalk-80, Bits of History, Words of Advice]. A more recent overview of garbage collection methods can be found in [Richard Jones, Rafael Lins, 1996: Garbage Collection, Algorithms for Automatic Dynamic Memory Management].
+
+
+
One reference only, (ORO) memory management
+
+
Memory management in newLISP does not rely on a garbage collection algorithm. Memory is not marked or reference-counted. Instead, a decision whether to delete a newly created memory object is made right after the memory object is created.
+
+
Empirical studies of LISP have shown that most LISP cells are not shared and so can be reclaimed during the evaluation process. Aside from some optimizations for primitives like set, define, and eval, newLISP deletes memory objects containing intermediate evaluation results once it reaches a higher evaluation level. newLISP does this by pushing a reference to each created memory object onto a result stack. When newLISP reaches a higher evaluation level, it removes the last evaluation result's reference from the result stack and deletes the evaluation result's memory object. This should not be confused with one-bit reference counting. ORO memory management does not set bits to mark objects as sticky.
+
+
newLISP follows a one reference only (ORO) rule. Every memory object not referenced by a symbol or context reference is obsolete once newLISP reaches a higher evaluation level during expression evaluation. Objects in newLISP (excluding symbols and contexts) are passed by value to other functions. As a result, each newLISP object only requires one reference.
+
+
newLISP's ORO rule has advantages. It simplifies not only memory management but also other aspects of the newLISP language. For example, while users of traditional LISP have to distinguish between equality of copied memory objects and equality of references to memory objects, newLISP users do not.
+
+
newLISP's ORO rule forces newLISP to constantly allocate and then free LISP cells. newLISP optimizes this process by allocating large chunks of cell memory from the host operating system. newLISP will request LISP cells from a free cell list and then recycle those cells back into that list. As a result, only a few CPU instructions (pointer assignments) are needed to unlink a free cell or to re-insert a deleted cell.
+
+
The overall effect of ORO memory management is a faster evaluation time and a smaller memory and disk footprint than traditional interpreted LISP's can offer. The lack of garbage collection in newLISP more than compensates for its high frequency of cell creation/deletion. Note that under error conditions, newLISP will employ a mark and sweep algorithm to free un-referenced cells.
+
+
Performance considerations with value-passing
+
+
Passing parameters by value (memory copying) instead of by reference poses a potential disadvantage when dealing with large lists. For practical purposes, however, the overhead needed to copy a large list is negligible compared to the processing done on the list. Nevertheless, to achieve maximum performance, newLISP offers a group of destructive functions that can efficiently create and modify large lists. While cons and set-nth return a new memory object of the changed list, push, pop and nth-set change the existing list and only return a copy of the list elements that they added or removed. In order for any user defined function to operate destructively on a large list, the large list must be passed by reference. If a list is packaged in a context (a namespace) in newLISP, then newLISP can pass the list by reference. newLISP contexts are the best choice when passing big lists or string buffers by reference.
+
+
In most cases where lists are less than a few hundred elements long, the speed of ORO memory management more than compensates for the overhead required to pass parameters by value.
+
+
Memory and datatypes in newLISP
+
+
The memory objects of newLISP strings are allocated from and freed to the host's OS whenever newLISP recycles the cells from its allocated chunks of cell memory. This means that newLISP handles cell memory more efficiently than string memory. As a result, it is often better to use symbols than strings for efficient text processing. For example, when handling natural language it is more efficient to handle natural language words as individual symbols in a separated name-space, rather than as a single string.
+The bayes-train function in newLISP uses this method. newLISP can handle millions of symbols without degrading performance.
+
+
Programmers coming from other programming languages frequently overlook that symbols in LISP can act as more than just variables or object references. The symbol is a useful data type in itself, which in many cases can replace the string data type.
+
+
Integer numbers and double floating-point numbers are stored directly in newLISP's LISP cells and do not need a separate memory allocation cycle.
+
+
For efficiency during matrix operations like matrix multiplication or inversion, newLISP allocates non-cell memory objects for matrices, converts the results to LISP cells, and then frees the matrix memory objects.
+
+
newLISP allocates an array as a group of LISP cells. The LISP cells are allocated linearly. As a result, array indices have faster random access to the LISP cells. Only a subset of newLISP list functions can be used on arrays. Automatic memory management in newLISP handles arrays in a manner similar to how it handles lists.
+
+
Implementing ORO memory management ²
+
+
The following pseudo code illustrates the algorithm implemented in newLISP in the context of LISP expression evaluation. Only two functions and one data structure are necessary to implement ORO memory management:
The first two functions pushResultStack and popResultStack push or pop a LISP object handle on or off a stack. pushResultStack increases the value resultStackIndex while popResultStack decreases it. In newLISP every object is contained in a LISP cell structure. The object handle of that structure is simply the memory pointer to the cell structure. The cell itself may contain pointer addresses to other memory objects like string buffers or other LISP cells linked to the original object. Small objects like numbers are stored directly. In this paper function popResultStack() also implies that the popped object gets deleted.
+
+
The two resultStack management functions described are called by newLISP's evaluateExpression function:
+
+
+function evaluateExpression(expr)
+ {
+ resultStackIndexSave = resultStackIndex
+
+ if typeOf(expr) is BOOLEAN or NUMBER or STRING
+ return(expr)
+
+ if typeOf(expr) is SYMBOL
+ return(symbolContents(expr))
+
+ if typeOf(expr) is QUOTE
+ return(quoteContents(expr))
+
+ if typeOf(expr) is LIST
+ {
+ func = evaluateExpression(firstOf(expr))
+ args = rest(expr)
+ if typeOf(func) is BUILTIN_FUNCTION
+ result = evaluateFunc(func, args)
+ else if typeOf(func) = LAMBDA_FUNCTION
+ result = evaluateLambda(func, args)
+ }
+ }
+
+ while (resultStackIndex > resultStackIndexSave)
+ deleteList(popResultStack())
+
+ pushResultStack(result)
+
+ return(result)
+ }
+
+
+
The function evaluateExpression introduces the two variables resultStackIndexSave and resultStackIndex and a few other functions:
+
+
+
+resultStackIndex is an index pointing to the top element in the resultStack. The deeper the level of evaluation the higher the value of resultStackIndex.
+
+
+
+resultStackIndexSave serves as a temporary storage for the value of resultStackIndex upon entry of the evaluateExpression(func, args) function. Before exit the resultStack is popped to the saved level of resultStackIndex. Popping the resultStack implies deleting the memory objects pointed to by entries in the resultStack.
+
+
+
+resultStack[] is a preallocated stack area for saving pointers to LISP cells and indexed by resultStackIndex.
+
+
+
+symbolContents(expr) and quoteContents(expr) extract contents from symbols or quote-envelope cells.
+
+
+
+typeOf(expr) extracts the type of an expression, which is either a BOOLEAN constant like nil or true or a NUMBER or STRING, or is a variable SYMBOL holding some contents, or a QUOTE serving as an envelope to some other LIST expression expr.
+
+
+
+evaluateFunc(func, args) is the application of a built-in function to its arguments. The built-in function is the evaluated first member of a list in expr and the arguments are the rest of the list in expr. The function func is extracted calling evaluateExpression(first(expr)) recursively. For example if the expression (expr is (foo x y) than foo is a built-in function and x and y are the function arguments or parameters.
+
+
+evaluateLambda(func, args) works simlar to evaluateFunc(func, args), applying a user-defined function first(expr) to its arguments in rest(expr). In case of a user-defined function we have two types of arguments in rest(expr), a list of local parameters followed by one or more body expressions evaluated in sequence.
+
+
+
+
Both, evaluateFunc(func, args) and evaluateLambda(func, args) will return a newly created LISP cell object, which may be any type of the above mentioned expressions. The result values from these functions will always be newly created LISP cell objects destined to be destroyed on the next higher evaluation level, after the current evaluateExpression(expr) function excution returned.
+
+
Both functions will recursively call evaluateExpression(expr) to evaluate their arguments. As recursion deepens it increases the recursion level of the function.
+
+
Before evaluateExpression(func, args) returns it will pop the resultStack deleting the result values from deeper level of evaluation and returned by one of the two functions, either evaluateFunc or evaluateLambda.
+
+
Any result expression is destined to be destroyed later but its deletion is delayed at a lower level of evaluation. This permits results to be used or copied by calling functions.
+
+
The following example shows the evaluation of a small user-defined LISP function sum-of-squares and the creation and deletion of associated memory objects:
+
+
+(define (sum-of-squares x y)
+ (+ (* x x) (* y y)))
+
+(sum-of-squares 3 4) => 25
+
+
+
sum-of-squares is a user-define lambda-function calling to built-in functions + and *.
+
+
The following trace shows the relevant steps when defining the sum-of-squares function and when executing it with the arguments 3 and 4.
The actual C-language implementation is optimized in some places to avoid pushing the resultStack and avoid calling evaluateExpression(expr). Only the most relevant steps are shown. The function evaluateLambda(func, args) does not need to evaluate its arguments 3 and 4 becuase they are constants, but evaluateLambda(func, args) will call evaluateExpression(expr) twice to evaluate the two body expressions (+ (* x x) and (+ (* x x). Lines preceded by the prompt > show the command-line entry.
+
+
evaluateLambda(func, args) also saves the environment for the variable symbols x and y, copies parameters into local variables and restores the old environment upon exit. These actions too involve creation and deletion of memory objects. Details are omitted, becuase they are similar to to methods in other dynamic languages.
+
+
+
References
+– Glenn Krasner, 1983: Smalltalk-80, Bits of History, Words of
+Advice
+Addison Wesley Publishing Company
+
+– Richard Jones, Rafael Lins, 1996: Garbage Collection, Algorithms
+for Automatic Dynamic Memory Management
+John Wiley & Sons
+
+¹ Reference counting and mark-and-sweep algorithms where specifically developed for LISP. Other schemes like copying or generational algorithms where developed for other languages like Smalltalk and later also used in LISP.
+
+
+
+
diff --git a/doc/TRU64BUILD b/doc/TRU64BUILD
new file mode 100644
index 0000000..62dbe10
--- /dev/null
+++ b/doc/TRU64BUILD
@@ -0,0 +1,14 @@
+Building newLISP for HP's Tru64 OS
+==================================
+
+The following now will make newLISP for the tru64 OS and using the Compaq
+C compiler for the Alpha CPU:
+
+ make
+
+Note that since version 8.9.4 ffi libraries are not required anymore.
+
+Note that since version 9.0.14 newLisp compiles in 64-bit completely.
+
+Please contact Peter van Eerten (peter AT gtk-server DOT org) for any
+remaining questions.
diff --git a/doc/manual_frame.html b/doc/manual_frame.html
new file mode 100644
index 0000000..95174f3
--- /dev/null
+++ b/doc/manual_frame.html
@@ -0,0 +1,15 @@
+
+
+
+
+
+
+
+ newLISP Manual and Reference
+
+
+
diff --git a/doc/newLISP-9.3-Release.html b/doc/newLISP-9.3-Release.html
new file mode 100644
index 0000000..b374b2f
--- /dev/null
+++ b/doc/newLISP-9.3-Release.html
@@ -0,0 +1,208 @@
+
+
+
+
+
+
+
+
+
+
+
+
newLISPtm
+v.9.3 Release Notes February 1st, 2008, rev 4
+
Improved newLISP-GS
+Graphics Server module and editor
+
This is the
+second release with the new Java based graphical user interface (GUI)
+server for newLISP. Since newLISP-GS appeared for the first time in
+release 9.2 new functions have been added, many bugs where fixed, and
+the newLISP-GS based multi tab editor has much improved behavior when
+launching applications. The monitor area at the bottom of the editor
+now works as an interactive newLISP shell.
+
+
The new way
+of doing Graphics and GUIs in newLISP using the Java based newLISP-GS
+module has been well received by the community. newLISP can also
+still be used with GTK-Server
+or Tcl/Tk.
+
+As in previous releases, most new functionality and changes where
+asked for or contributed by the community of newLISP users.
+
Full support for nested association
+lists
+
+This version has a new set of functions for managing nested
+association lists. Nested association lists are frequently the result
+from converting XML into Lisp s-expressions. XML has established
+itself as a format for data interchange on the internet. The new
+functions permit access, modification and deletion of associations in
+nested association lists. These functions also work together with
+FOOP, which represents objects as associations.
+
FOOP – Functional
+Object Oriented Programming
+
Using the :
+colon operator to implement polymorphism
+in method application and using context namespaces to encapsulate all
+methods of an object class, an object oriented programming system for
+newLISP has been designed. Thanks to Michael Michaels from
+neglOOk for designing most of
+this new way of object oriented programming in newLISP and for
+creating the training video series: “Towards FOOP”. FOOP melts
+contexts, the new colon operator :
+and functional programming into a simple and efficient way of
+object oriented programming
+in newLISP. The system features polymorphism and inheritance and can
+have anonymous objects, which are memory managed automatically by
+newLISP.
+
A very
+short description of FOOP can be found in the Users Manual. For a
+more in depth treatment of this topic see Michael Michaels's
+video series accessible from the newLISP
+documentation page and the neglOOk
+website.
+
New functions
+
assoc-set,
+set-assoc, pop-assoc – change or delete an association,
+handle nested associations.
+
bind
+– the function binds expressions to symbols from an association
+list and is normally used in logic programming together with unify.
+This function was already persent in earlier versions, but was not
+documented.
+
destroy
+– destroys a process addressed by the process id returned by yhr
+newLISP functions process
+or fork.
+
dostring
+– iterates over a string with the character value in the loop
+variable. On UTF-8 compiled newLISP UTF8 character values are
+returned by the loop variable.
+
NEWLISPDIR
+- this environment variable will be registered on startup as
+/usr/share/newlisp
+on Unix and Unix like OSs and as %PROGRAMFILES%/newlisp
+on Win32. This allows writing platform independent code for loading
+modules. An already existing definition of NEWLISPDIR
+will not be overwritten during startup.
+
ref-set,
+set-ref, ref-set-all – these functions modify one or all
+elements in a list searched by a key. The key can be any type of
+expression and unify,
+match or a
+user-defined function can be specified as comparison function. Like
+the nth, set-nth
+and nth-set
+family of functions these new list search-and-replace functions can
+pass lists by reference using a context name which is interpreted as
+a default functor.
+
when
+– works like if
+without the else clause evaluating a block
+conditionally and without the necessity of begin.
+
The :
+(colon) now also works as a function and can be attached to a
+symbol following it. The operator forms a context symbol from the
+symbol following it and the context symbol found as the first element
+of the list contained in the next argument. The colon operator is
+used to implement polymorphism in FOOP.
+
Enhancements and
+changes to existing functionality
+
assoc
+– now handles nested multilevel associations.
+
count
+– has been rewritten to be many times faster on Unix and Unix like
+OSs.
+
dup
+- without the repetition parameter will assume 2.
+
find
+– when used with a comparison functor puts the last found
+expression into $0.
+
find-all
+– can now be used on lists too.
+
get-url,
+post-url, put-url, delete-url - have been extended and
+reworked to return more error information as supplied by the server
+and have improved debugging support.
+
last,
+nth, nth-set, set-nth – now have last element speed
+optimization as previously only present in push
+and pop.
+
nth,
+set-nth, nth-set, push, pop – when used on lists, indices
+overshooting the beginning or the end of the list now will cause an
+error to be thrown. Before, out of range indices would pick the first
+or last element in a list. The new behavior is consistent with the
+behavior of indexing arrays.
+
pack
+– now can take lists for data.
+
process
+– this reworked function now creates the new process without the
+previous time and memory overhead on Unix. No extra newLISP fork will
+be created to launch the new process. In most cases the full path
+must now be given for the command in process.
+
rand
+– integer random number generation with better statistical quality
+on Win32.
+
ref
+– when used with a comparison function puts the last found
+expression into $0.
+
set-assoc
+– renamed replace-assoc
+changes an association, handles nested associations.
+
set-nth,
+nth-set – now return the old list or value when the second
+argument is not present. They behave now like set
+without the value argument. Before both, set-nth
+and nth-set returned
+nil when the
+value argument was missing.
+
signal
+– the nil flag
+now specifies SIG_IGN
+and the true
+flag SIG_DFL.
+Before 9.3 nil
+would specify an empty newLISP handler and the true
+flag was not available. This allows to reset the signal handler for a
+specific signal to its OS default.
+
Other additions and changes
+
newlisp.vim
+– the syntax highlighting and editing control file for the VIM
+text editor has been much improved by Cyril
+Slobin.
+
crypto.lsp
+– this module has been expanded to offer hmac
+encryption using MD5 or SHA-1 hashing.
+
amazon.lsp
+– this new module interfaces to the Amazon Web Services, S3 storage
+API.
+
newlispdoc
+– this utility has been improved to handle indices and links to
+external module collections.
+
wordnet.lsp
+- this new module interfaces to the WordNet 3.o datebase
+
The amazon.lsp and wordet.lsp modules
+are not part of the distribution, but can be accessed in the new
+http://newlisp.org/modules
+section.
+
Bug fixes and
+documentation corrections
+
Many bugs
+have been fixed in this release stabilizing some of the new features
+in the previous 9.2 release and fixing older previously undetected
+bugs. For more detail on bug fixes and changes see the CHANGES file
+in the source distribution of newLISP v.9.3.0 in
+newlisp-9.3.0/doc/CHANGES. This file details fixes changes for the
+development versions between 9.2.0 and to 9.3.0.
Comments in newLISP source files can be converted
+to HTML documentation using only a few tags in comments. The newLISPdoc system
+is designed to use a minimum of tags and leave the tagged comments still readable.
+
+
newLISPdoc also generates an index page for all newLISP source files
+generated.
+
+
See here for the source of newLISPdoc .
+The program and this documentation are also part of the
+source distribution of newLISP since version 9.0. Since newLISP version 9.1 syntax
+highlighting is built into newlispdoc which is installed
+in the same directory as the main newLISP executable program. The script
+syntax.cgi is still available for web site installations, but is not
+required anymore for newlispdoc.
+
+
Usage
+
From within the directory where the modules are, execute with all module filenames
+to process on the commandline. For example to process the files mysql.lsp,
+odbc.lsp and sqlite3.lsp do:
This will generate index.html, mysql.lsp.html, odbc.lsp.html
+and sqlite.lsp.html all in the same directory, where the command was executed.
+ The page index.html contains links to all other pages.
+
+
The command line flag -s can be supplied to additionally
+generate syntax highlighted HTML versions of the source files and put a link
+to the highlighted version of the source file on the documentation page:
Since version 1.3 of newLISPdoc a file containing URLs of source file locations
+can be specified. This allows indexing and documenting of newLISP source code distributed
+on different sites:
http:// and file:// URLs can be used. Like with individual files,
+the -s switch can be specified to generate also syntax highlighted source files.
+A URL file contains one URL per line. No other information is allowed in the file. The
+following is a sample URL file:
The last line shows a file URL from the local filesystem.
+
+
All generated files will be written to the current directory.
+
+
Tags
+
+
The following tags start at the beginning of a line with
+2 semicolons and one space before the tag:
+
+
+;; @module one word for module name
+;; @index Title and URL for index page
+;; @description one line description of the module
+;; @location the original URL location of the source file
+;; @version one line version info
+;; @author one line for author info
+;; @syntax one line syntax pattern
+;; @param name description on one line
+;; @return description on one line
+;; @example multiline code example starting on next line
+
+
+
The only required tag is either the @module tag or alternatively
+the @index tag. If neither one tag is present in the file, it will
+not be processed. All other tags are optional. Only lines starting with ;;
+(2 semicolons) are processed. Program comment text which should not appear
+in the documentation should start with only one semicolon.
+
+
The one line description of the @description tag will be put under the module
+name on the index and module doc page. This and the @location where added in
+June 2007, and are not part of the newlispdoc program in the newLISP v. 9.1 release.
+
+
A function may have multiple @syntax tags each on consecutive lines.
+
+
The following is the only tag, which can be embedded anywhere in
+the text. Between the tag link specificaton and description is exactly on
+space:
+
+
+@link link description
+
+
+
All words between <...> angle braces are displayed in italic.
+Internally newLISPdoc uses <em>,</em> tags for formatting. They
+should be used for parameter specs after the @param tag and in text referring
+to those parameters..
+
+
All words between single quotes ' ... ' are printed in monospace.
+Internally newLISPdoc uses <tt>,</tt> tags for formatting.
+
+
All other lines starting with 2 semicolons contain descriptive
+text. An empty line with only 2 semicolons at the beginning
+is a break between paragraphs of text.
+
+
Lines not starting with 2 semicolons are ignored by newLISPdoc. This
+allows doing code comments with just one semicolon.
+
+
If more formatting is required than what is offered by newLISPdoc, the
+following simple HTML tags and their closing forms may also be used:
+<h1>,<h2>,<h3>,<h4>,
+<i>,<em>,<b>,<tt>,<p>,
+<br>,<pre>,<center>,<blockquote>
+and <hr>.
+
Linking to other module collections
+
newLISPdoc generates and index page for all modules documented. A special tag @index
+can be used to show a link on the index page to an index of other module collections. This way
+multilevel indices of modules can be created. To display a link to another module collection
+ on the index page, create a file containing a @index and a @descrption link:
Use one or more of these files on the newLISPdoc command line as any other
+source file:
+
+
+newlispdoc -s other-collection.txt *.lsp
+
+
+
This will show the index entry for OtherCollection on the module index before listing
+all modules in *.lsp.
+
+
+
+
+
Examples
+
+
The following is the commented source of and example program
+followed by the pages generated in HTML:
+
+
+;; @module example.lsp
+;; @author John Doe, johndoe@example.com
+;; @version 1.0
+;;
+;; This module is an example module for the newlispdoc
+;; program, which generates automatic newLISP module
+;; documentation.
+
+
+;; @syntax (example:foo <num-repeat> <str-message>)
+;; @param <num-repeat> The number of times to repeat.
+;; @param <str-message> The messsage string to be printed.
+;; @return Returns the message in <str-message>
+;;
+;; The function 'foo' repeatedly prints a string to
+;; standard out terminated by a line feed.
+;;
+;; @example
+;; (example:foo 5 "hello world")
+;; =>
+;; "hello world"
+;; "hello world"
+;; "hello world"
+;; "hello world"
+;; "hello world"
+
+(context 'example)
+
+(define (foo n msg)
+ (dotimes (i n)
+ (println msg))
+)
+
+;; See the @link http://example.com/example.lsp source .
+
+
+
Below the example.lsp.html and index.html page generated:
Author: John Doe, johndoe@example.com
+Version: 1.0
+
+ This module is an example module for the newlispdoc
+ program, which generates automatic newLISP module
+ documentation.
+
+
+
- § -
+
Syntax: (example:foo num-repeatstr-message)
+parameter: num-repeat - The number of times to repeat.
+parameter: str-message - The messsage string to be printed.
+
return: Returns the message in str-message
+
+ The function foo repeatedly prints a string to
+ standard out terminated by a line feed.
+
+example:
Below the index page index.html which was generated. When more than one module is
+specified on the command line, the index page will show one link line for
+each module.
+
+
+
+
+
diff --git a/doc/newlisp.1 b/doc/newlisp.1
new file mode 100644
index 0000000..1a146ca
--- /dev/null
+++ b/doc/newlisp.1
@@ -0,0 +1,102 @@
+.TH newlisp 1 "January 2008" "version 9.3" "Commandline Parameters"
+.SH NAME
+newlisp \- lisp like programming language
+.SH SYNOPSIS
+.B newlisp
+[\-h] [\-c | \-C | \-http] [\-s stacksize] [\-m max\-mem\-megabyte] [[\-l path\-file | \-L path\-file] [\-p port\-number | \-d port\-number]] [\-w diectory] [lisp\-files ...] [\-e programtext]
+.SH DESCRIPTION
+Invokes newLISP which first loads init.lsp if present. Then one or more options and one or more newLISP source files can be specified. The options and source files are executed in the sequence they appear. For some options is makes sense to have source files loaded first like for the \-p and \-d options. For other options like \-s and \-m it is logical to specify these before the source files to be loaded. If a \-e switch is used the programtext is evaluated and then newlisp exits otherwise evaluation continues interactively (unless an exit occurs during lisp\-file interpretation).
+.SH OPTIONS
+.TP
+\-h
+Display a short help text.
+.TP
+\-c
+Suppress the commandline prompt.
+.TP
+\-C
+Force prompt when running newLISP in pipe I/O mode for Emacs.
+.TP
+\-http
+only accept HTTP commands
+.TP
+\-s stacksize
+Stack size to use when starting newLISP. When no stack size is specified the stack defaults to 1024.
+.TP
+\-m max\-mem\-megabyte
+Limits memory to max\-mem\-megabyte megabytes for LISP cell memory.
+.TP
+lisp\-files
+Load and evaluate the specified lisp source files in sequence. Source files can be specified using URLs. If an (exit) is executed by one of the source files then newlisp exits and all processing ceases.
+.TP
+\-e programtext
+Programtext is an expression enclosed in quotation marks which is evaluated and the result printed to standard out device (STDOUT). In most UNIX system shells apostrophes can also be used to delimit the expression. newLISP exits after evaluation of programtext is complete.
+.TP
+\-w directory
+Directory is the start up directory for newLISP. Any file reference in a program will refer to this directory by default as the current directory. This can be used to define a web root directory when in server mode.
+.TP
+\-l \-L path\-file
+Log network connections and newLISP I/O to the file in path\-file. \-l will only log network connections or commandline input or net\-eval requests. \-L will additionally log HTTP requests and newLISP output from commandline and net\-eval input.
+.TP
+\-p port\-number
+Listen for commands on a TCP/IP socket connection. In this case standard I/O is redirected to the port specified in the \-p option. Any specified lisp\-files will be loaded the first time a connection is made, that is, before text is accepted from the port connection.
+.TP
+\-d port\-number
+Run in demon mode. As for the \-p option, but newLISP does not exit after a closed connection and stays in memory listening for a new connection.
+
+.SH EXAMPLES
+.TP
+Start interactive session
+.B newlisp
+.PP
+.TP
+Excute a program
+.B newlisp myprog.lsp
+.PP
+.TP
+Excute a remote program
+.B newlisp http://newlisp.org/example.lsp
+.PP
+.TP
+Add 3 and 4, 7 prints on standard output
+.B newlisp
+\-e "(+ 3 4)"
+.PP
+.TP
+newLISP is started as a server (the & indicates to LINUX to run the process in the background) and can be connected to with telnet by issuing telnet localhost 1234
+.B newlisp
+\-p 1234 &
+.PP
+.TP
+newLISP is started as a server for another newlisp process connecting with the net\-eval function or HTTP requests
+.B newlisp
+\-c \-d 4711 &
+.PP
+.TP
+newLISP is started as a server handling HTTP requests only. Connections are logged to the file /usr/home/www/log.txt
+.B newlisp
+\-l /usr/home/www/log.txt \-http \-d 8080 &
+.PP
+.TP
+newLISP is started as a server handling HTTP requests and defining the startup/web root directory
+.B newlisp
+\-http \-d 8080 \-w /usr/home/www/httpdocs &
+.TP
+When accepting HTTP commands a file httpd.conf can be loaded, which will preprocess the path\-name in the HTTP request
+.B newlisp
+httpd.conf \-http \-d 8080 \-w /usr/home/www/httpdocs &
+.PP
+If the file httpd.conf contains:
+
+(define (httpd\-conf path\-name)
+ (if (ends\-with path\-name ".exe") "errorpage.html" path\-name))
+
+then all files ending in .exe will translate the request in to a request for an error page, else the original request string is returned.
+.PP
+.SH EXIT STATUS
+newLISP returns a zero exit status for normal termination unless an exit command specifies a code to be returned. Non zero is returned in case of abnormal exit.
+.SH AUTHOR
+Lutz Mueller
+
+http://newlisp.org/ \- the newLISP home page
+
diff --git a/doc/newlisp_index.html b/doc/newlisp_index.html
new file mode 100644
index 0000000..b86e6c6
--- /dev/null
+++ b/doc/newlisp_index.html
@@ -0,0 +1,510 @@
+
+
+
+
+
+
+
+ newLISP Manual and Reference Index
+
+
+
+
+
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled
+GNU Free Documentation License.
+ newLISP focuses on the core components of LISP:
+ lists, symbols, and lambda expressions.
+ To these, newLISP adds arrays,
+ implicit indexing on lists and arrays,
+ and dynamic and lexical scoping.
+ Lexical scoping is implemented using separate namespaces called contexts.
+
+
+ The result is an easier-to-learn LISP
+ that is even smaller than most Scheme implementations,
+ but which still has about 350 built-in functions.
+ Approximately 200k in size,
+ newLISP is built for high portability
+ using only the most common UNIX system C-libraries.
+ It loads quickly and has a small memory footprint.
+ newLISP is as fast or faster than other popular scripting languages
+ and uses very few resources.
+
+
+ newLISP is dynamically scoped inside lexically separated contexts (namespaces).
+ Contexts can be used to create isolated protected expansion packages
+ and to write prototype-based object-oriented programs.
+
+
+ Both built-in and user-defined functions, along with variables,
+ share the same namespace and are manipulated by the same functions.
+ Lambda expressions and user-defined functions can be handled
+ like any other list expression.
+
+
+ Contexts in newLISP facilitate the development
+ of larger applications comprising independently developed modules
+ with their own separate namespaces.
+ They can be copied,
+ dynamically assigned to variables,
+ and passed by reference to functions as arguments.
+ In this way, contexts can serve as dynamically created objects
+ packaging symbols and methods.
+ Lexical separation of namespaces
+ also enables the definition of statically scoped functions.
+
+
+ newLISP's efficient red-black tree implementation
+ can handle millions of symbols without degrading performance.
+ Contexts can hold symbol-value pairs,
+ allowing them to be used as hash-tables.
+ Functions are also available
+ to iteratively access symbols inside contexts.
+
+
+ newLISP allocates and reclaims memory automatically,
+ without using traditional asynchronous garbage collection
+ (except under error conditions).
+ All objects — except for contexts, built-in primitives, and symbols —
+ are passed by value and are referenced only once.
+ When objects are no longer referenced,
+ their memory is automatically deallocated.
+ This results in predictable processing times,
+ without the pauses found in traditional garbage collection.
+ newLISP's unique automatic memory management
+ makes it the fastest interactive LISP available.
+
+
+ Many of newLISP's built-in functions are polymorphic
+ and accept a variety of data types and optional parameters.
+ This greatly reduces the number of functions
+ and syntactic forms it is necessary to learn and implement.
+ High-level functions are available for distributed computing,
+ financial math, statistics, and AI.
+
+
+ newLISP has functions to modify, insert, or delete elements inside
+ complex nested lists or multidimensional array structures.
+
+
+ Since strings can contain null characters in newLISP,
+ they can be used to process binary data.
+
+
+ newLISP can also be extended with a shared library interface
+ to import functions that access data in foreign binary data structures.
+ The distribution contains a module for importing popular database APIs.
+
+
+ newLISP's HTTP, TCP/IP, and UDP socket interfaces
+ make it easy to write distributed networked applications.
+ Its built-in XML interface,
+ along with its text-processing features
+ — Perl Compatible Regular Expressions (PCRE) and text-parsing functions —
+ make newLISP a useful tool for CGI processing.
+ The source distribution includes examples of HTML forms processing.
+ newLISP can be run a as a CGI capable web server using its built-in http mode option.
+
+
+ The source distribution can be compiled for Linux, BSDs, Mac OS X/Darwin, Solaris, and Win32.
+ On 64-bit Linux, SUN Solaris and True64Unix newLISP can be compiled as a 64-bit LP64 application
+ for full 64-bit memory addressing.
+
+
+
+ newLISP-GS
+
+
+ newLISP-GS is a graphical user interface front-end
+ written in newLISP and a Java based library server
+ using the standard Java runtime environment
+ installed on all Windows and Mac OS X platforms.
+ Applications built with newLISP-GS can have the host operating system's
+ native look and feel.
+ Interfaces to GTK, Tcl/Tk and OpenGL graphics libraries
+ are also available.
+
+
+ newLISP and Java are available for most operating systems.
+ This makes newLISP-GS is a platform-independent solution
+ for writing GUI applications.
+
+
+ For more information on newLISP-GS,
+ see newLISP-GS.
+
The new set-assoc or pop-assoc should
+be used instead of replace-assoc, to replace or remove an association
+in an association list. The new set-assoc and pop-assoc handle multiple key
+expressions for nested association lists. The old replace-assoc will be removed in
+a future version.
+
+
+
+
+( § )
+
+
+
+
3. Command-line options startup and directories
+
+
When starting newLISP from the command line several switches and options and source files
+can be specified. The options and source files are executed. For options such as -p and -d,
+it makes sense to load source files first; other options, like -m and -s,
+should be specified before the source files. The -e switch is used to evaluate
+the program text and then exit; otherwise, evaluation continues interactively
+(unless an exit occurs while the files are loading).
+
+
+
+
+
Specifying files as URLs
+
+
newLISP will load and execute files specified on the command line. Files are specified with either their
+pathname on the local filesystem or with a http:// or file:// URL:
+ The above examples show starting newLISP with different stack sizes using
+ the -s option, as well as loading one or more newLISP source files
+ and loading files specified by an URL. When no stack size is specified,
+ the stack defaults to 2048.
+
+
+
+
+ Maximum memory usage
+
+
+newlisp -m 128
+
+
+ This example limits LISP cell memory to 128 megabytes. In 32-bit newLISP, each LISP cell consumes 16 bytes, so the argument 128 would represent a maximum of 8,388,608 LISP cells. This information is returned by sys-info as the list's second element. Although LISP cell memory is not the only memory consumed by newLISP, it is a good estimate of overall memory usage.
+
+
+
+
+
+Specifiying the working directory
+
+
+
The -w option specifies the initial working directory for newLISP after startup:
+
+
+
+newlisp -w /usr/home/newlisp
+
+
+
All file requests without a directory path will now be directed to the path specified with the -w option.
+
+
+
+
+
+ Suppressing the prompt and HTTP processing
+
+
+ The command-line prompt
+ and initial copyright banner
+ can be suppressed:
+
+
+newlisp -c
+
+
+ Listen and connection messages
+ are suppressed if logging is not enabled.
+ The -c option is useful
+ when controlling newLISP
+ from other programs;
+ it is mandatory when setting it up
+ as a net-eval server.
+
+
+ The -c option also enables newLISP server nodes to answer
+ HTTP GET, PUT, POST and DELETE requests, as well as
+ perform CGI processing. Using the -c option,
+ together with the -w and -d options,
+ newLISP can serve as a standalone httpd webserver:
+
+
+newlisp -c -d 8080 -w /usr/home/www
+
+
+
+When running newLISP as a inetd or xinetd enabled
+server on UNIX machines, use:
+
+
+
+newlisp -c -w /usr/home/www
+
+
+
+ In -c mode, newLISP processes command-line requests as well as
+ HTTP and net-eval requests. Running
+ newLISP in this mode is only recommended on a machine behind
+ a firewall. This mode should not be run on machines open and accessible
+ through the Internet.
+ To suppress the processing of net-eval and command-line–like requests,
+ use the safer -http option.
+
+
+
+
+
+
+ HTTP-only server mode
+
+
+ newLISP can be limited to HTTP processing using the -http option.
+ With this mode, a secure httpd web server daemon can be configured:
+
+
+newlisp -http -d 8080 -w /usr/home/www
+
+
+When running newLISP as an inetd or xinetd-enabled
+server on UNIX machines, use:
+
+
+newlisp -http -w /usr/home/www
+
+
+
To further enhance security and HTTP processing, load a program during startup when using this mode:
+
+
+newlisp http-conf.lsp -http -w /usr/home/www
+
+
+
Defining a function named httpd-conf
+in a source file called httpd-conf.lsp
+can be used to customize HTTP request processing.
+The newLISP distribution contains an example
+httpd-conf.lsp file.
+This file shows how to configure redirects
+and filter unauthorized requests.
+
+
In the HTTP modes enabled by either -c or -http, the following file types are
+recognized, and a correctly formatted Content-Type: header is sent back:
+
+
+
+
+
file extension
media type
+
.jpg
image/jpg
+
.pgn
image/png
+
.gif
image/gif
+
.pdf
application/pdf
+
.mp3
image/mpeg
+
.mov
image/quicktime
+
.mpg
image/mpeg
+
any other
text/html
+
+
+
+
+
Forcing prompts in pipe I/O mode
+
+
+ A capital C forces prompts when running newLISP in pipe I/O mode
+ inside the Emacs editor:
+
+
+
+newlisp -C
+
+
+
+ To suppress return values from evaluations,
+ use silent.
+
+
+
+
+
+ newLISP as a TCP/IP server
+
+
+newlisp some.lsp -p 9090
+
+
+
+This example shows how newLISP can listen for commands on a TCP/IP socket connection.
+In this case, standard I/O is redirected to the port specified with the -p
+option. some.lsp is an optional file loaded during startup, before listening
+for a connection begins.
+
+
+
+The -p option is also used to control newLISP from another application,
+such as a newLISP GUI front-end or a program written in another language.
+
+
+
+A telnet application can be used to test running newLISP as a server. First enter:
+
+
+
+newlisp -p 4711 &
+
+
+
+The & indicates to a UNIX shell to run the process in the background.
+Now connect with a telnet application:
+
+
+
+telnet localhost 4711
+
+
+
+If connected, the newLISP sign-on banner and prompt appear. Instead of 4711,
+any other port number could be used.
+
+
+
+When the client application closes the connection, newLISP will exit, too.
+
+
+
+
+
+ TCP/IP daemon mode
+
+
+
When the connection to the client is closed in -p mode, newLISP exits.
+To avoid this, use the -d option instead of the -p option:
+
+
+
+newlisp -d 4711 &
+
+
+
+This works like the -p option, but newLISP does not exit after a
+connection closes. Instead, it stays in memory, listening for a new connection
+and preserving its state. An exit issued from a client
+application closes the network connection, and the newLISP daemon remains resident,
+waiting for a new connection. Any port number could be used in place of 4711.
+
+
+
+When running in -p or -d mode, the opening and closing tags
+[cmd] and [/cmd] must be used to enclose multiline statements.
+They must each appear on separate lines. This makes it possible to transfer larger
+portions of code from controlling applications.
+
+
+
+The following variant of the -d mode is frequently used in a distributed
+computing environment, together with net-eval on the client side:
+
+
+
+newlisp -c -d 4711 &
+
+
+
+The -c spec suppresses prompts, making this mode suitable
+for receiving requests from the net-eval function.
+
+
+
+ newLISP server nodes running on UNIX like operating systems,
+ will also answer HTTP GET, PUT and DELETE requests.
+ This can be used to retrieve and store files
+ with get-url, put-url,
+ delet-url,
+ read-file, write-file
+ and append-file,
+ or to load and save programs using load
+ and save from and to remote server nodes.
+ See the chapters for the -c and -http options
+ for more details.
+
+
+
+
+
+
+
Local domain UNIX socket server
+
+
Instead of a port a local domain UNIX socket path can be specified in
+the -d or -p server modes.
+
+
+newlisp -c -d /tmp/mysocket &
+
+
+
This mode will work together with local domain socket modes of
+net-connect, net-listen,
+and net-eval. Local domain sockets opened with
+with net-connect and net-listen can be served using
+net-accept, net-receive,
+and net-send. Local domain socket connections
+can be monitored using net-peek and
+net-select.
+
+
Local domain socket connections are much faster than normal Tcp/Ip network
+connections and preferred for communications between processes on
+the same local file system in distributed applications. This mode is not
+available on Win32.
+
+
+
+
+
inetd daemon mode
+
+The inetd server running on virtually all Linux/UNIX OSes can function
+as a proxy for newLISP. The server accepts TCP/IP or UDP connections and passes
+on requests via standard I/O to newLISP. inetd starts a newLISP process
+for each client connection. When a client disconnects, the connection is closed
+and the newLISP process exits.
+
+
+
+inetd and newLISP together can handle multiple connections efficiently
+because of newLISP's small memory footprint, fast executable, and short program load
+times. When working with net-eval, this mode is preferred
+for efficiently handling multiple requests in a distributed computing environment.
+
+
+
+Two files must be configured: services and inetd.conf.
+Both are ASCII-editable and can usually be found at /etc/services and
+/etc/inetd.conf.
+
+
+
+Put one of the following lines into inetd.conf:
+
+
+
+net-eval stream tcp nowait root /usr/bin/newlisp -c
+
+# as an alternative, a program can also be preloaded
+
+net-eval stream tcp nowait root /usr/bin/newlisp -c myprog.lsp
+
+
+
+Instead of root, another user and optional group can be specified.
+For details, see the UNIX man page for inetd.
+
+
+
+The following line is put into the services file:
+
+
+
+net-eval 4711/tcp # newLISP net-eval requests
+
+
+
+On Mac OS X and some UNIX systems, xinetd can be used instead of
+inetd. Save the following to a file named net-eval in the
+/etc/xinetd.d/ directory:
+
+
+
+service net-eval
+{
+ socket_type = stream
+ wait = no
+ user = root
+ server = /usr/bin/newlisp
+ port = 4711
+ server_args = -c
+ only_from = localhost
+}
+
+
+For security reasons, root should be changed to a different user,
+when traffic is accepted from other places than localhost.
+The only_from spec can be left out to permit remote access.
+
+
+
+See the man pages for xinetd and xinetd.conf
+for other configuration options.
+
+
+
+After configuring the daemon, inetd or
+xinetd must be restarted to
+allow the new or changed configuration files to be read:
+
+
+
+kill -HUP <pid>
+
+
+Replace <pid> with the process ID of the
+running xinetd process.
+
+
+
+A number or network protocol other than 4711 or TCP can be specified.
+
+
+
+newLISP handles everything as if the input were being entered
+on a newLISP command line without a prompt. To test the
+inetd setup, the telnet program can be used:
+
+
+
+telnet localhost 4711
+
+
+
+newLISP expressions can now be entered, and inetd will
+automatically handle the startup and communications of a newLISP
+process. Multiline expressions can be entered by bracketing them
+with [cmd] and [/cmd] tags, each on separate lines.
+
+
+
+
+ newLISP server nodes running on UNIX like operating systems,
+ will also answer simple HTTP GET and PUT requests.
+ This can be used to retrieve and store files
+ with get-url, put-url,
+ read-file, write-file
+ and append-file,
+ or to load and save programs using load
+ and save from and to remote server nodes.
+ On Win32 newLISP server nodes do not
+ answer HTTP requests.
+
+
+
+
+
+ Direct execution mode
+
+ Small pieces of newLISP code can be executed directly from the command line:
+
+newlisp -e "(+ 3 4)" → 7
+
+ The expression enclosed in quotation marks is evaluated, and the result is printed to standard out (STDOUT). In most UNIX system shells, single quotes can also be used as command-line delimiters. Note that there is a space between -e and the quoted command string.
+
+
+
+
+
Logging I/O
+
+
+In any mode newLISP can write a log when started with the -l or -L option.
+Depending on the mode newLISP is running, different output is written to the logfile. Both options always must
+specify the path of a log-file. The path may be a relative path and can be either attached or detached to the
+-l or -L option.
+
+ All logging output is written to the file specified after the -l or -L option.
+
+
+
+
+ Command line help summary
+
+
The -h command-line switch prints a copyright notice and summary of options:
+
+
+newlisp -h
+
+ On Linux and other UNIX systems, a newlispman page can be found:
+
+
+man newlisp
+
+ This will display a man page in the Linux/UNIX shell.
+
+
+
+
+
The initialization file init.lsp
+
On Linux, BSDs, Mac OS X and other UNIXs the initialization file is installed and expected in /usr/share/newlisp/init.lsp. newLISP on Win32 compiled with MinGW looks for init.lsp in the same directory where newlisp.exe is installed. Along with any files specified on the command line, init.lsp is loaded before the banner and prompt are shown. When newLISP is executed or launched by a program or process other than a shell, the banner and prompt are not shown, and newLISP communicates by standard I/O. init.lsp, however, is still loaded and evaluated if present.
+
+
+
While newLISP does not require init.lsp to run, it is convenient for defining functions and systemwide variables.
+
+The last part of init.lsp contains OS-specific code, which loads a second .init.lsp (starting with a dot). On Linux/UNIX, this file is expected in the directory specified by the HOME environment variable. On Win32, this file is expected in the directory specified by the USERPROFILE or DOCUMENT_ROOT environment variable.
+
+
+
+
+
+
Directories on Linux, BSD, Mac OS X and other UNIX
+
+The directory /usr/share/newlisp/modules contains modules with useful functions
+for a variety of tasks, such as database management with MySQL, procedures for statistics,
+POP3 mail, etc. The directory /usr/share/newlisp/guiserver contains sample programs
+for writing GUI aplications with newLISP-GS.
+The directory /usr/share/doc/newlisp/ contains documentation in HTML format.
+
+
+
+
+ Directories on Win32
+
+
+On Win32 systems, all files are installed in the default directory $PROGRAMFILES\newlisp.
+$PROGRAMFILES is a Win32 environment variable that resolves to
+C:\Program files\newlisp\ in English language installations. The subdirectories
+$PROGRAMFILES\newlisp\modules and $PROGRAMFILES\newlisp\guiserver
+contain modules for interfacing to external libraries and sample programs written for
+newLISP-GS.
+
+
+
+
Environment variable NEWLISPDIR
+
During startup newLISP sets the environment variable NEWLISPDIR, if it is not set already. On Linux, BSDs, Mac OS X and other UNIXs the variable is set to /usr/share/newlisp. On Win32 the variable is set to %PROGRAMFILES%/newlisp.
+
+
The environment variable NEWLISPDIR is useful when loading files installed with
+newLISP:
+ 4. Shared library module for Linux/BSD versions
+
+
+ newLISP can be compiled as a UNIX shared library called newlisp.dylib on Mac OS X and as newlisp.so on Linux and BSDs. A newLISP shared library can be used like any other UNIX shared library.
+
+
+ To use newlisp.so or newlisp.dylib, import the function newlispEvalStr. Like eval-string, this function takes a string containing a newLISP expression and stores the result in a string address. The result can be converted using get-string. The returned string is formatted like output from a command-line session. It contains terminating line-feed characters, but without the prompt strings.
+
+
+ The first example shows how newlisp.so is imported from newLISP itself.
+
+ This program will accept quoted newLISP expressions and print the evaluated results.
+
+
+ When calling newlisp.so's function newlispEvalStr, output normally directed to the console (e.g., return values or print statements) is returned in the form of an integer string pointer. The output can be accessed by passing this pointer to the get-string function. To silence the output from return values, use the silent function.
+
+
+
+( § )
+
+
+
+
+ 5. DLL module for Win32 versions
+
+
+ On the Win32 platforms, newLISP can be compiled as a DLL (Dynamic Link Library). In this way, newLISP functions can be made available to other programs (e.g., MS Excel, Visual Basic, Borland Delphi, or even newLISP itself).
+
+
+ When the DLL is loaded, it looks for the file init.lsp in the current directory of the calling process.
+
+
+ To access the functionality of the DLL, use newlispEvalStr, which takes a string containing a valid newLISP expression and returns a string of the result:
+
+ The above example shows the loading of a DLL using newLISP. The get-string function is necessary to access the string being returned. Other applications running on Win32 allow the returned data type to be declared when importing the function.
+
+
+ When using newlisp.so, output normally directed to the console — like print statements or return values — will be returned in a string pointed to by the call to newlispEvalStr. To silence the output from return values, use the silent directive.
+
+
+
+( § )
+
+
+
+
+ 6. Evaluating newLISP expressions
+
+
+ The following is a short introduction to LISP statement evaluation and the role of integer and floating point arithmetic in newLISP.
+
+
+ Top-level expressions are evaluated when using the load function or when entering expressions in console mode on the command line. As shown in the following snippet from an interactive session, multiline expressions can be entered by enclosing them between [cmd] and [/cmd] tags:
+
+
+> [cmd]
+(define (foo x y)
+(+ x y))
+[/cmd]
+(lambda (x y) (+ x y))
+> (foo 3 4)
+7
+> _
+
+ Each [cmd] and [/cmd] tag is entered on a separate line. This mode is useful for pasting multiline code into the interactive console.
+
+
+
+
+ Integer data, floating point data, and operators
+
+
+ newLISP functions and operators accept integer and floating point numbers, converting them into the needed format. For example, a bit-manipulating operator converts a floating point number into an integer by omitting the fractional part. In the same fashion, a trigonometric function will internally convert an integer into a floating point number before performing its calculation.
+
+
+ The symbol operators (+-*/%$~|^<<>>) return values of type integer. Functions and operators named with a word instead of a symbol (e.g., add rather than +) return floating point numbers. Integer operators truncate floating point numbers to integers, discarding the fractional parts.
+
+
+ newLISP has two types of basic arithmetic operators: integer (+-*/) and floating point (addsubmuldiv). The arithmetic functions convert their arguments into types compatible with the function's own type: integer function arguments into integers, floating point function arguments into floating points. To make newLISP behave more like other scripting languages, the integer operators +, -, *, and / can be redefined to perform the floating point operators add, sub, mul, and div:
+
+
+(constant '+ add)
+(constant '- sub)
+(constant '* mul)
+(constant '/ div)
+
+;; or all 4 operators at once
+(constant '+ add '- sub '* mul '/ div)
+
+ Now the common arithmetic operators +, -, *, and / accept both integer and floating point numbers and return floating point results.
+
+
+ Note that the looping variables in dotimes and for, as well as the result of sequence, use floating point numbers for their values.
+
+
+ Care must be taken when importing from libraries that use functions expecting integers. After redefining +, -, *, and /, a double floating point number may be unintentionally passed to an imported function instead of an integer. In this case, floating point numbers can be converted into integers by using the function int. Likewise, integers can be transformed into floating point numbers using the float function:
+
+
+(import "mylib.dll" "foo") ; importing int foo(int x) from C
+(foo (int x)) ; passed argument as integer
+(import "mylib.dll" "bar") ; importing C int bar(double y)
+(bar (float y)) ; force double float
+
+ Some of the modules shipping with newLISP are written assuming the default implementations of +, -, *, and /. This gives imported library functions maximum speed when performing address calculations.
+
+
+ The newLISP preference is to leave +, -, *, and / defined as integer operators and use add, sub, mul, and div when explicitly required.
+Since version 8.9.7 integer operations in newLISP are 64 bit operations, while 64 bit double floating
+point numbers only offer 52 bits of resolution in the integer part of the number.
+
+
+
+
+
+
+
+
+
+ Evaluation rules and data types
+
+
+ Evaluate expressions by entering and editing them on the command line. More complicated programs can be entered using editors like Emacs and VI, which have modes to show matching parentheses while typing. Load a saved file back into a console session by using the load function.
+
+
+ A line comment begins with a ; (semicolon) or a # (number sign) and extends to the end of the line. newLISP ignores this line during evaluation. The # is useful when using newLISP as a scripting language in Linux/UNIX environments, where the # is commonly used as a line comment in scripts and shells.
+
+
+ When evaluation occurs from the command line, the result is printed to the console window.
+
+
+ The following examples can be entered on the command line by typing the code to the left of the → symbol. The result that appears on the next line should match the code to the right of the → symbol.
+
+
+ nil and true are boolean data types that evaluate to themselves:
+
+
+nil → nil
+true → true
+
+ Integers and floating point numbers evaluate to themselves:
+
+ Integers are 64-bit numbers (including the sign bit, 32-bit before version 8.9.7).
+ Valid integers are numbers between -9,223,372,036,854,775,808 and
+ +9,223,372,036,854,775,807.
+ Larger numbers converted from floating point numbers are truncated
+ to one of the two limits. Integers internal to newLISP, which
+ are limited to 32-bit numbers overflow to either +2,147,483,647 or
+ -2,147,483,648. Floating point numbers are IEEE 754 64-bit doubles.
+ Unsigned numbers up to 18,446,744,073,709,551,615 can be displayed
+ using special formatting characters for format.
+
+
+
+ Strings may contain null characters and can have different delimiters. They evaluate to themselves.
+
+
+"hello" →"hello"
+"\032\032\065\032" →" A "
+"\x20\x20\x41\x20" →" A "
+"\t\r\n" →"\t\r\n"
+"\x09\x0d\x0a" →"\t\r\n"
+
+;; null characters are legal in strings:
+"\000\001\002" → "\000\001\002"
+{this "is" a string} → "this \"is\" a string"
+
+;; use [text] tags for text longer than 2048 bytes:
+[text]this is a string, too[/text]
+→ "this is a string, too"
+
+
+ Strings delimited by " (double quotes) will also process the following characters escaped with a \ (backslash):
+
+
+
+
+
escaped character
description
+
\"
for a double quote inside a quoted string
+
\n
for a line-feed character (ASCII 10)
+
\r
for a return character (ASCII 13)
+
\t
for a TAB character (ASCII 9)
+
\nnn
for a three-digit ASCII number (nnn format between 000 and 255)
+
\xnn
for a two-hex-digit ASCII number (xnn format between x00 and xff)
+
+
+
+
+ Quoted strings cannot exceed 2,048 characters. Longer strings should use the [text] and [/text] tag delimiters. newLISP automatically uses these tags for string output longer than 2,048 characters.
+
+
+ The { (left curly bracket), } (right curly bracket), and [text], [/text] delimiters do not perform escape character processing.
+
+
+ Lambda and lambda-macro expressions evaluate to themselves:
+
+
+(lambda (x) (* x x)) → (lambda (x) (* x x))
+(lambda-macro (a b) (set (eval a) b)) → (lambda (x) (* x x))
+(fn (x) (* x x)) → (lambda (x) (* x x)) ; an alternative syntax
+
+ Symbols evaluate to their contents:
+
+
+(set 'something 123) → 123
+something → 123
+
+ Contexts evaluate to themselves:
+
+
+(context 'CTX) → CTX
+CTX → CTX
+
+ Built-in functions also evaluate to themselves:
+
+ In the above example, the number between the < > (angle brackets) is the hexadecimal memory address (machine-dependent) of the add function. It is displayed when printing a built-in primitive.
+
+
+ Quoted expressions lose one ' (single quote) when evaluated:
+
+
+'something → something
+''''any → '''any
+'(a b c d) → (a b c d)
+
+ A single quote is often used to protect an expression from evaluation (e.g., when referring to the symbol itself instead of its contents or to a list representing data instead of a function).
+
+
+
In newLISP, a list's first element is evaluated
+before the rest of the expression (as in Scheme). The result of the
+evaluation is applied to the remaining elements in the list and must
+be one of the following: a lambda expression, lambda-macro
+expression, or primitive (built-in) function.
+
+
+
+(+ 1 2 3 4) → 10
+(define (double x) (+ x x)) → (lambda (x) (+ x x))
+
+ or
+
+
+(set 'double (lambda (x) (+ x x)))
+(double 20) → 40
+((lambda (x) (* x x)) 5) → 25
+
+ For a user-defined lambda expression, newLISP evaluates the arguments from left to right and binds the results to the parameters (also from left to right), before using the results in the body of the expression.
+
+
+ Like Scheme, newLISP evaluates the functor (function object) part of an expression before applying the result to its arguments. For example:
+
+
+((if (> X 10) * +) X Y)
+
+
+
Depending on the value of X, this expression applies the *
+(product) or + (sum) function to X and Y.
+
+
+
Because their arguments are not evaluated, lambda-macro
+expressions are useful for extending the syntax of the language. Most
+built-in functions evaluate their arguments from left to right (as needed)
+when executed. Some exceptions to this rule are indicated in the reference
+section of this manual. LISP functions that do not evaluate all or some of
+their arguments are called special forms.
+
Shell commands: If an ! (exclamation mark)
+is entered as the first character on the command line followed by a shell
+command, the command will be executed. For example, !ls on Unix or
+!dir on Win32 will display a listing of the present working directory.
+No spaces are permitted between the ! and the shell command. Symbols
+beginning with an ! are still allowed inside expressions or on the
+command line when preceded by a space. Note: This mode only works when running
+in the shell and does not work when controlling newLISP from another
+application.
+
+
+
To exit the newLISP shell on Linux/UNIX, press Ctrl-D; on Win32,
+type (exit) or Ctrl-C, then the x key.
+
+
+
Use the exec function to access shell commands from
+other applications or to pass results back to newLISP.
+
+
+
+( § )
+
+
+
+
+ 7. Lambda expressions in newLISP
+
+
+ Lambda expressions in newLISP evaluate to themselves and can be treated
+ just like regular lists:
+
+(set 'double (lambda (x) (+ x x))
+(set 'double (fn (x) (+ x x)) ; alternative syntax
+
+(last double) → (+ x x) ; treat lambda as a list
+
+
+ Note: No ' is necessary before the lambda expression since lambda expressions evaluate to themselves in newLISP.
+
+
+ The second line uses the keyword fn, an alternative syntax first suggested by Paul Graham for his Arc language project.
+
+
+ A lambda expression is a lambda list, a subtype of list, and its arguments can associate from left to right or right to left. When using append, for example, the arguments associate from left to right:
+
+
+(append (lambda (x)) '((+ x x))) → (lambda (x) (+ x x))
+
+ cons, on the other hand, associates the arguments from right to left:
+
+
+(cons '(x) (lambda (+ x x))) → (lambda (x) (+ x x))
+
+ Note that the lambda keyword is not a symbol in a list, but a
+ designator of a special type of list: the lambda list.
+
+
+(length (lambda (x) (+ x x))) → 2
+(first (lambda (x) (+ x x))) → (x)
+
+ Lambda expressions can be mapped or applied onto arguments to work as user-defined, anonymous functions:
+
+ All arguments are optional when applying lambda expressions and default to nil when not supplied by the user. This makes it possible to write functions with multiple parameter signatures.
+
+
+
+( § )
+
+
+
+
+ 8. nil, true, cons, and ()
+
+
+ In newLISP, nil and true represent both the symbols and the boolean values true and false. Depending on their context, nil and true are treated differently. The following examples use nil, but they can be applied to true by simply reversing the logic.
+
+
+ Evaluation of nil yields a boolean false and is treated as such inside control flow expressions, such as if, unless, while, until, and not. Likewise, evaluating true yields true.
+
+ In newLISP, nil and the empty list () are not the same as in some other LISPs. Only in conditional expressions are they treated as a boolean false, as in and, or, if, while, unless, until, and cond.
+
+
+ The expression (list? '()) is true, but (list? nil) is not. This is because in newLISP, nil results in a boolean false when evaluated.
+
+
+ Evaluation of (cons x '()) yields (x), but (cons x nil) yields (x nil) because nil is treated as a boolean value when evaluated instead of as an empty list. The cons of two atoms in newLISP does not yield a dotted pair, but rather a two-element list. The predicate atom? is true for nil, but false for the empty list. The empty list in newLISP is only an empty list and not equal to nil.
+
+
+ A list in newLISP is a LISP cell of type list. It acts like a container for the linked list of elements making up the list cell's contents. There is no dotted pair in newLISP because the cdr (tail) part of a LISP cell always points to another LISP cell and never to a basic data type, such as a number or a symbol. Only the car (head) part may contain a basic data type. Early LISP implementations used car and cdr for the names head and tail.
+
+
+
+( § )
+
+
+
+
+ 9. Arrays
+
+
+ newLISP's arrays enable fast element access within large lists. New arrays can be constructed and initialized with the contents of an existing list using the function array. Lists can be converted into arrays, and vice versa. Some of the same functions used for modifying and accessing lists can be applied to arrays, as well. Arrays can hold any type of data or combination thereof.
+
+
+ In particular, the following functions can be used for creating, accessing, and modifying arrays:
+
+ newLISP represents multidimensional arrays with an array of arrays (i.e., the elements of the array are themselves arrays).
+
+
+ When used interactively, newLISP prints and displays arrays as lists, with no way of distinguishing between them.
+
+
+ Use the source or save functions to serialize arrays (or the variables containing them). The array statement is included as part of the definition when serializing arrays.
+
+
+ Like lists, negative indices can be used to enumerate the elements of an array, starting from the last element.
+
+
+ An out-of-bounds index will cause an error message on an array. In contrast, lists pick the last or first element when an out-of-bounds occurs.
+
+
+ Arrays can be non-rectangular, but they are made rectangular during serialization when using source or save. The array function always constructs arrays in rectangular form.
+
+
+ The matrix functions det, transpose, multiply, and invert can be used on matrices built with nested
+lists or arrays built with array.
+
+
+ For more details, see array, array?, and array-list in the reference section of this manual.
+
+
+
+( § )
+
+
+
+
+10. Dictionaries (hash tables)
+
+
+
newLISP has no built-in hash table data type. Instead, it uses symbols for associative memory access. Symbols in newLISP are implemented using an efficient red-black tree algorithm. This algorithm balances the binary symbol tree for faster symbol access. In newLISP, symbol trees are represented as namespaces called contexts, which are themselves part of the MAIN namespace.
+
+
+
For a more detailed introduction to namespaces, see the chapter on
+Contexts.
+
+
+
The context function can be used to make associations. It can also be used to create and switch contexts.
+
+
+
+;; create a symbol and store data into it
+(context 'MyHash "John Doe" 123) → 123
+(context 'MyHash "@#$%^" "hello world") → "hello world"
+
+;; retrieve contents from the symbol
+(context 'MyHash "John Doe") → 123
+(context 'MyHash "@#$%^") → "hello world"
+
+
+
The first two statements create the symbols "John Doe" and "@#$^", storing the values 123 and "hello world" into them. The hash context named MyHash is created in the first statement, while the second merely adds the new association to the existing one.
+
+
+
+Note that hash symbols can contain spaces or other special characters
+not typically allowed in variable names.
+
+
+
Internally, context is just a shorter
+and faster form of:
+
+
+
+;; create a symbol and store the data in it
+(set (sym "John Doe" 'MyHash) 123) → 123
+
+;; retrieve contents from the symbol
+(eval (sym "John Doe" MyHash)) → 123
+
+
+
The context default function can be used for a
+very short definition of a hash function:
+
+
+
+(define (myhash:myhash key value)
+ (if value
+ (context myhash key value)
+ (context myhash key)))
+
+;; create a dictionary key value pair
+(myhash "hello" 123) → 123
+
+;; retrieve the key value
+(myhash "hello") → 123
+
+
+
+
+( § )
+
+
+
+
11. Indexing elements of strings, lists, and arrays
+
+
Some functions take array, list, or string elements (characters) specified by one or more int-index (integer index). The positive indices run 0, 1, …, N-2, N-1, where N is the number of elements in the list. If int-index is negative, the sequence is -N, -N+1, …, -2, -1. Adding N to the negative index of an element yields the positive index. Unless a function does otherwise, an index greater than N-1 returns the last element in a list; it returns the first element for indices less than -N. An error message is produced for any indexing occurring outside an array's boundaries.
+
+
+
+
Implicit indexing for nth
+
+
Implicit indexing can be used instead of nth to retrieve the elements of a list or array or the characters of a string:
+
+
+(set 'lst '(a b c (d e) (f g)))
+
+(lst 0) → a ; same as (nth (lst 0))
+(lst 3) → (d e)
+(lst 3 1) → e ; same as (nth (lst 3 1))
+(lst -1) → (f g)
+
+(set 'myarray (array 3 2 (sequence 1 6)))
+
+(myarray 1) → (3 4)
+(myarray 1 0) → 3
+(myarray 0 -1) → 2
+
+("newLISP" 3) → "L"
+
+
+
Indices may also be supplied from a list. In this way, implicit indexing works together with functions that take or produce index vectors, such as push, pop, ref
+and ref-all.
+
+
+(lst '(3 1)) → e
+(set 'vec (ref 'e lst)) → (3 1)
+(lst vec) → e
+
+
+
Note that implicit indexing is not breaking Lisp
+syntax rules but is merely an expansion of existing rules to
+other data types in the functor position of an s-expression.
+In original Lisp the first element in an s-expression list
+is applied as a function to the rest elements as arguments. In newLISP a list
+in the functor position of an s-expression assumes self-indexing functionality
+using the index arguments following it.
+
+
Implicit indexing is faster than the explicit forms, but the explicit forms
+may be more readable depending on context.
+
+
Note that in the UTF-8–enabled version of newLISP, implicit indexing of strings using the nth function works on character rather than byte boundaries.
+
+
+
+
+
+
Implicit indexing and the default functor
+
+
The default functor is a functor inside a context with the same name as the context itself. See The context default function chapter. A default functor can be used together with implicit indexing to serve as a mechanism for referencing lists:
+
+
+(set 'MyList:MyList '(a b c d e f g))
+
+(MyList 0) → a
+(MyList 3) → d
+(MyList -1) → g
+
+(3 2 MyList) → (d e)
+(-3 MyList) → (e f g)
+
+(set 'aList MyList)
+
+(aList 3) → d
+
+
+
In this example, aList references MyList:MyList, not a copy of it. For more information about contexts, see Programming with contexts.
+
+
The default functor can also be used with nht-set as shown in the following
+example:
+
+
+(set 'MyList:MyList '(a b c d e f g))
+
+(nth-set (MyList 3) 999) → d
+(MyList 3) → 999
+
+
+
+
+
Implicit indexing for rest and slice
+
+
Implicit forms of rest and slice
+can be created by prepending a list with one or two numbers for offset and length.
+If the length is negative it counts from the end of the list or string:
+
+
+(set 'lst '(a b c d e f g))
+; or as array
+(set 'lst (array 7 '(a b c d e f g)))
+
+(1 lst) → (b c d e f g)
+(2 lst) → (c d e f g)
+(2 3 lst) → (c d e)
+(-3 2 lst) → (e f)
+(2 -2 lst) → (d e)
+
+(set 'str "abcdefg")
+
+(1 str) → "bcdefg"
+(2 str) → "cdefg"
+(2 3 str) → "cde"
+(-3 2 str) → "ef"
+(2 -2 str) → "de"
+
+
+
Implicit indexing for rest works on
+character rather than byte boundaries when using the UTF-8–enabled version
+of newLISP, whereas implicit indexing for slice will always
+work on byte boundaries and can be used for binary content.
+
+
+
+
+
+
Implicit indexing for nth-set and set-nth
+
+
+
+
+(set 'aList '(a b c (d e (f g) h i) j k))
+
+(nth-set (aList 0) 1) → a
+
+(nth-set (aList 3 2) '(1 2 3 4)) → (f g)
+
+(set 'i 3 'j 2 'k 2)
+
+(nth-set (aList i j k) 99) → 3
+
+aList
+→ (1 b c (d e (1 2 99 4) h i) j k)
+
+(set-nth (aList -3 -3 2) 999)
+→ (1 b c (d e (1 2 999 4) h i) j k)
+
+
+
+
As with nth, indices can be supplied in a vector list to work together with
+functions handling index vectors such as push, pop, ref
+and ref-all.
+
+
+
+
+(set 'aList '(a b c (d e (f g) h i) j k))
+
+(set 'vec (ref 'f aList)) → (3 2 0)
+
+(set-nth (aList vec) 999)
+
+(set-nth (aList vec) 999) → (a b c (d e (999 g) h i) j k)
+
+(nth-set (aList vec) 'Z) → 999 ; old value
+
+aList → (a b c (d e (Z g) h i) j k)
+
+
+
+
+
+
+( § )
+
+
+
+
+
+ 12. Destructive versus nondestructive functions
+
+
+ Most of the primitives in newLISP are nondestructive (no side effects) and leave existing objects untouched, although they may create new ones. There are a few destructive functions, however, that do change the contents of a list, string, or variable:
+
Note that the last two functions, write-buffer and write-line, are only destructive in one of their syntactic forms: when taking a string buffer instead of a file handle.
+
+
+
+
+
Make a destructive function non-destructive
+
+
Some destructive functions can be made non-destruvtive by wrapping the target object into a begin
+block. A block returns a copy of the last evaluation in the block and the destructive function will work on the
+copy instead of the original.
+
+
+(set 'aList '(a b c d e f))
+
+(replace 'c (begin aList)) → (a b d e f)
+
+aList → (a b c d e f)
+
+(set 'str "newLISP") → "newLISP"
+
+(rotate (begin str)) → "PnewLIS"
+
+str → "newLISP"
+
+
+
+
+
+( § )
+
+
+
+
+ 13. Dynamic and lexical scoping
+
+
+ newLISP uses dynamic scoping inside contexts. A context is a lexically closed namespace. In this way, parts of a newLISP program can live in different namespaces taking advantage of lexical scoping.
+
+
+ When the parameter symbols of a lambda expression are bound to its arguments, the old bindings are pushed on a stack. newLISP automatically restores the original variable bindings when leaving the lambda function.
+
+
+ The following example illustrates the dynamic scoping mechanism. The text in bold is the output from newLISP:
+
The variable x is first set to 1, but when (g 0) is called x is
+bound to 0 and x is reported by (f) as 0 during execution of (g 0). After execution of (g 0) the call to (f) will report x as 1 again.
+
+
This is different from the lexical scoping mechanisms found in languages like C or Java, where the binding of local parameters occurs inside the function only. In lexically scoped languages like C, (f) would always print the global bindings of the symbol x with 1.
+
+
+ Be aware that passing quoted symbols to a user-defined function causes a name clash if the same variable name is used as a function parameter:
+
+
+(define (inc-symbol x y) (inc x y))
+(set 'y 200)
+(inc-symbol 'y 123) → 246
+y → 200 ; y is still 200
+
+ Since 'y shares the same name as the function's second parameter, inc-symbol returns 246 (123 + 123), leaving 'y unaffected. Dynamic scoping's variable capture can be a disadvantage when passing symbol references to user-defined functions.
+
+
+ The problem is avoided entirely by grouping related user-defined functions into a context. A symbol name clash cannot occur when accessing symbols and calling functions from outside of the defining context.
+
+
+ Contexts should be used to group related functions when creating interfaces or function libraries. This surrounds the functions with a lexical "fence," thus avoiding variable name clashes with the calling functions.
+
+ 14. Early return from functions, loops, and blocks
+
+
+ What follows are methods of interrupting the control flow inside both loops and the begin expression.
+
+
+
The looping functions dolist and
+dotimes can take optional conditional expressions to leave the loop
+early. catch and throw are a more
+general form to break out of a loop body and are also applicable to other
+forms or statement blocks.
+
+
+
+
+
+ Using catch and throw
+
+
+ Because newLISP is a functional language, it uses no break or return statements to exit functions or iterations. Instead, a block or function can be exited at any point using the functions catch and throw:
+
+
+(define (foo x)
+ (…)
+ (if condition (throw 123))
+ (…)
+ 456)
+
+;; if condition is true
+
+(catch (foo p)) → 123
+
+;; if condition is not true
+
+(catch (foo p)) → 456
+
+ Breaking out of loops works in a similar way:
+
+
+(catch
+ (dotimes (i N)
+ (if (= (foo i) 100) (throw i))))
+→ value of i when foo(i) equals 100
+
+ The example shows how an iteration can be exited before executing N times.
+
+
+ Multiple points of return can be coded using throw:
+
+ If condition-A is true, x will be returned from the catch expression; if condition-B is true, the value returned is y. Otherwise, the result from foo5 will be used as the return value.
+
+
+ As an alternative to catch, the throw-error function can be used
+ to catch errors caused by faulty code
+ or user-initiated exceptions.
+
+
+
+
+ Using and and or
+
+
+ Using the logical functions and and or, blocks of statements can be built that are exited depending on the boolean result of the enclosed functions:
+
+ The and expression will return as soon as one of the block's functions returns nil or an () (empty list). If none of the preceding functions causes an exit from the block, the result of the last function is returned.
+
+ The result of the or expression will be the first function that returns a value which is notnil or ().
+
+
+
+( § )
+
+
+
+
15. Contexts
+
+
In newLISP, symbols can be separated into namespaces called contexts. Each context has a private symbol table lexically separate from all other contexts. Symbols known in one context are unknown in others, so the same name may be used in different contexts without conflict.
+
+
Contexts are used to build modules of isolated variable and function definitions. They can also be copied and dynamically assigned to variables or passed as arguments. Because contexts in newLISP have lexically separated namespaces, they allow programming with lexical scoping and software object styles of programming.
+
+
Contexts are identified by symbols that are part of the root or MAIN context. While context symbols are uppercased in this chapter, lowercase symbols may also be used.
+
+
In addition to context names, MAIN contains the symbols for built-in functions and special symbols such as true and nil. The MAIN context is created automatically each time newLISP is run. To see all the symbols in MAIN, enter the following expression after starting newLISP:
+
+
+(symbols)
+
+
+
+
+
+
Symbol creation in contexts
+
+
The following rules should simplify the process of understanding contexts by
+identifying which ones the created symbols are being assigned to.
+
+
+
+
newLISP first parses and translates each top level expression. The symbols
+are created during the parsing and translation phase. After the expression
+is translated it gets evaluated.
+
+
+
+
A symbol is created when newLISP first sees it, when calling the
+load, sym,
+or eval-string functions. When newLISP reads
+a source file, symbols are created before evaluation occurs.
+
+
+
+
When an unknown symbol is encountered during code translation,
+a search for its definition begins inside the current context.
+Failing that, the search continues inside MAIN for a
+built-in function, context, or global symbol. If no definition
+is found, the symbol is created locally inside the current context.
+
+
+
+
Once a symbol is created and assigned to a specific context,
+it will belong to that context permanently.
+
+
+
+
A user-defined function is evaluated in the context of the symbol it is called with.
+
+
+
+
+
+
Scoping rules for contexts
+
+Special symbols like nil and true, as well as context and built-in function symbols, are global (visible to all contexts). Any symbol in the MAIN context can be made global by using the global function.
+
+
The following simulates a command-line session in newLISP:
+
+
+> (context 'FOO)
+FOO
+FOO> _
+
+ If the FOO context already exists, newLISP switches to it. Otherwise, the context is created before the switch occurs. All symbols now read from the command line are created and known only within the context FOO. Note that the symbol used for the context name must be quoted ('FOO in this example) the first time a context is created. Subsequent uses of context do not require the quote. After the switch, the command-line prompt changes to FOO> :
+
+ When quoting a fully qualified symbol (context:symbol), the quote precedes the context name:
+
+
+> (set 'FOO-B:x 555)
+555
+> _
+
+ A context is implicitly created when referring to one that does not yet exist. Unlike the context function, the context is not switched. The following statements are all executed inside the MAIN context:
+
+ The same symbol (x in this case) used in a context can also be used in MAIN. Now we have three versions of x, all in a different context:
+
+
+> (set 'x "I belong to MAIN")
+"I belong to MAIN"
+> FOO:x
+123
+> FOO-B:x
+555
+> x
+"I belong to MAIN"
+> _
+
+ Symbols owned by a context (or MAIN) are not accessible unless prefixed by the context name:
+
+
+FOO> MAIN:x
+"I belong to MAIN"
+FOO> FOO-B:x
+555
+FOO> x
+123
+> _
+
+ When loading source files on the command line with load, or when executing the functions eval-string or sym, the context function tells newLISP where to put all of the symbols and definitions:
+
+
+;;; file MY_PROG.LSP
+;;
+;; everything from here on goes into GRAPH
+(context 'GRAPH)
+
+(define (draw-triangle x y z)
+ (…))
+(define (draw-circle)
+ (…))
+
+;; show the runtime context, which is GRAPH
+ (define (foo)
+ (context))
+
+;; switch back to MAIN
+(context 'MAIN)
+
+;; end of file
+
+ The draw-triangle and draw-circle functions — along with their x, y, and z parameters — are now part of the GRAPH context. These symbols are known only to GRAPH. To call these functions from another context, prefix them with
+ GRAPH:
+
+ The last statement shows how the runtime context has changed to GRAPH (foo's context).
+
+
+ A symbol's name and context are used when comparing symbols from different contexts. The name function can be used to extract the name part from a fully qualified symbol.
+
+
+;; same symbol name, but different context name
+(= 'A:val 'B:val) → nil
+(= (name 'A:val) (name 'B:val)) → true
+
+ Note: The symbols are quoted with a ' (single quote) because we are interested in the symbol itself, not in the contents of the symbol.
+
+
+
+
+ Changing scoping
+
+
+ By default, only built-in functions and symbols like nil and
+ true are visible inside contexts other than MAIN. To make a symbol visible to every context, use the global function:
+
+ Without the global statement, the second aVar would have returned nil instead of 123. If FOO had a previously defined symbol (aVar in this example) that symbol's value — and not the global's — would be returned instead. Note that only symbols from the MAIN context can be made global.
+
+
+ Once it is made visible to contexts through the global function, a symbol cannot be hidden from them again.
+
+
+
+
+ Symbol protection
+
+
+ By using the constant function, symbols can be both set and protected from change at the same time:
+
+
+> (constant 'aVar 123) → 123
+> (set 'aVar 999)
+symbol is protected in function set : aVar
+>_
+
+ A symbol needing to be both a constant and a global can be defined simultaneously:
+
+
+(constant (global 'aVar) 123)
+
+ In the current context, symbols protected by constant can be overwritten by using the constant function again. This protects the symbols from being overwritten by code in other contexts.
+
+
+
+
+ Overwriting global symbols and built-ins
+
+
+ Global and built-in function symbols can be overwritten inside a
+ context by prefixing them with their own context symbol:
+
+> (load "demo")
+symbol is protected in function set : FOO
+> _
+
+ Loading the file causes an error message for FOO, but not for ABC. When the first context FOO is loaded, the context ABC does not exist yet, so a local variable FOO:ABC gets created. When ABC loads, FOO already exists as a global protected symbol and will be correctly flagged as protected.
+
+
+ FOO could still be used as a local variable in the ABC context by explicitly prefixing it, as in ABC:FOO.
+
+
+ The following pattern can be applied to avoid unexpected behavior when loading contexts being used as modules to build larger applications:
+
+
+;; begin of file - MyModule.lsp
+(load "This.lsp")
+(load "That.lsp")
+(load "Other.lsp")
+
+(context 'MyModule)
+
+ …
+
+(define (func x y z) (…))
+
+ …
+
+(context 'MAIN)
+
+(MyModule:func 1 2 3)
+
+(exit)
+
+;; end of file
+
+
+Always load the modules required by a context before
+the module's context statement. Always finish by switching
+back to the MAIN context, where the module's functions and
+values can be safely accessed.
+
+
+
+
+( § )
+
+
+
+
16. Programming with contexts
+
+
Contexts are used in newLISP in different ways. Most frequently they
+are used for partioning code into modules, but they also can be
+used for simple object-oriented programming when using the : (colon)
+operator to handle polymorphism in function application.
+
+
+
Contexts as programming modules
+
+
Contexts in newLISP are mainly used for partitioning source into
+modules. Because each module lives in a different namespace, modules
+are lexically separated and the names of symbols cannot clash with
+identical names in other modules.
+
+
The modules, which are
+part of the newLISP distribution, are a good example how to put related
+functions into a module file, and how to document modules using
+the newLISPdoc utility.
+
+
For best programming practice a file should only contain one module and
+the filename should be similar if not identical to the context name used:
The example shows a good practice of predefining variables, which are global
+inside the namespace and defining as constants variables, which will not change.
+
+
If a file contains more then one context, then the end of the context
+should be marked with a switch back to MAIN:
Module files are loaded using the load function.
+If a programming project contains numerous modules which are referring
+to each other, they should be pre-declared to avoid problems due to context forward
+references before loading of that context.
When pre-declaring and loading modules as shown in the example, the sequence
+of declaration or loading can be neglected. All forward references to variables
+and definitions in modules not loaded yet will be translated correctly.
+
+
Modules not starting with a context switch are loaded always into MAIN
+except when the load statement specifies a target context
+as the last parameter. The load function can take URLs
+to load modules from remote locations, via HTTP.
+
+
+
+
+
The context default functor
+
+ A default functor or default function
+ is a symbol or user-defined function or macro
+ with the same name as its namespace.
+ When the context is used
+ as the name of a function or in the functor position of an s-expression,
+ newLISP executes the default function or refers to the contents of the
+ default functor.
+
+
+;; the default function
+
+(define (foo:foo a b c) (+ a b c))
+
+(foo 1 2 3) → 6
+
+;; the default functor
+
+(define mylist:mylist '(a b c d e f g))
+
+(mylist 3) → d
+
+(nth-set (mylist 3) 'D) → d ; returns old contents
+
+mylist:mylist → (a b c D e f g)
+
+
+
This allows the default function defined inside a context
+to be called whenever the context is applied as a function.
+A default function could update the lexically isolated static variables
+contained inside its context:
The first time the gen function is called,
+its accumulator is set to the value of the argument.
+Each successive call increments gen's accumulator
+by the argument's value.
+
+
If a default function is called
+from a context other than MAIN,
+the context must already exist
+or be declared with a forward declaration,
+which creates the context and the function symbol:
+
+
+;; forward declaration of a default function
+(define fubar:fubar)
+
+(context 'foo)
+(define (foo:foo a b c)
+ …
+ (fubar a b) ; forward reference
+ (…)) ; to default function
+
+(context MAIN)
+
+;; definition of previously declared default function
+
+(context 'fubar)
+(define (fubar:fubar x y)
+ (…))
+
+(context MAIN)
+
+
+
Default functions work like global functions,
+but they are lexically separate from the context in which they are called.
+The arguments in a default function macro are safe from variable capture.
+
+
Like a lambda or lambda-macro function, default functions can be used
+with map or apply.
+
+
+
+
+
+
+
Passing data by reference
+
+In newLISP, all parameters are passed by value.
+This poses a potential problem when passing large lists or strings
+to user-defined functions or macros.
+Symbols and context objects can also be passed by reference.
+This allows memory-intensive objects to be passed
+without the overhead of copying the entire list or string.
+
+
+
Any data can be passed by reference by passing the symbol holding it:
+
+
+(define (change-list aList) (push 999 (eval aList)))
+
+(set 'data '(1 2 3 4 5))
+
+; note the quote ' in front of data
+(change-list 'data) → (999 1 2 3 4 5)
+
+data → (999 1 2 3 4 5)
+
+
+
Although this method is simple to understand and use, it poses the potential
+problem of variable capture when passing the same symbol as used in
+the function as a parameter:
+
+
+;; pass data by symbol reference
+
+> (set 'aList '(a b c d))
+(a b c d)
+> (change-list 'aList)
+
+list or string expected : (eval aList)
+called from user defined function change-list
+>
+
+
+
Because of the danger of variable capture, passing an object by its symbol
+should only be used in small scripts or programs where each function and its
+parameters are well-known. A safer method would be to package the object in
+a context (namespace) and pass the context ID:
+This example shows how objects can be passed by reference
+to a user-defined function using context variables,
+without the overhead of passing them by value.
+String buffers or data objects enclosed in a context
+can also be passed using this technique.
+
+
+
+As shown in the following variation, using default
+functor can further simplify the syntax:
+
+The change-db function does not need to know
+the name of the variable inside the context.
+All functions which use a syntax (functor (L idx) ...) like:
+like
+assoc-set,
+nth,
+nth-set,
+pop-assoc,
+push, and pop and functions
+which use a syntax (functor (L key) ...) like:
+ref,
+ref-all,
+ref-set,
+set-assoc,
+set-nth,
+set-ref,
+and set-ref-all
+know how to extract the default functor from the context L.
+This technique works for arrays and strings, as well.
+
In this example,
+the list in foo:foo is passed by context reference.
+default is used to acces the
+default functor symbol,
+the contents of which is access by eval.
+
+
+
+
+
Serializing contexts
+
+
Serialization makes a software object persistent
+by converting it into a character stream,
+which is then saved to a file or string in memory.
+In newLISP, anything referenced by a symbol can be serialized to a file
+by using the save function.
+Like other symbols, contexts are saved just by using their names:
+
+
+
+(save "mycontext.lsp" 'MyCtx) ; save MyCtx to mycontext.lsp
+
+(load "mycontext.lsp") ; loads MyCtx into memory
+
+(save "mycontexts.lsp" 'Ctx1 'Ctx2 'Ctx3) ; save multiple contexts at once
+
+
+
+For details, see the functions save (mentioned above)
+and source (for serializing to a newLISP string).
+
+
+
+( § )
+
+
+
+
+
17. Object-Oriented Programming in newLISP
+
+
Any object-oriented programming (OOP) system built in newLISP is based on the following
+three principles:
+
+
+
Class attributes and methods are stored in the namespace of the object class.
+
+
The namespace default functor is used to hold the object constructor method.
+
+
An object is constructed using a list, the first element of which is the
+ context symbol describing the class of the object.
+
+
Polymorphism is implemented using the : (colon) operator, which selects the appropriate
+ class from the object.
+
+
+
The following paragraphs are a short introduction to FOOP: Functional Object-Oriented Programming
+as designed by Michael Michaels. This description covers only very basic elements.
+For more details see the Michael Michaels's FOOP training videos on
+newlisp.org or neglook.com.
+
+
+
+
+
+
+
Classes and constructors
+
+
Class attributes and methods are stored in the namespace of the object class.
+No object instance data is stored in this namespace/context. Data variables in
+the class namespace only desecribe the class of objects as a whole but don't contain
+any object specific information. A generic FOOP object constructor can be used
+as a template for specific object constructors when creating new object classes
+with new:
+
+
+; generic FOOP object constructor
+(define (Class:Class)
+ (cons (context) (args)))
+
+(new Class 'Rectangle)
+(new Class 'Circle)
+
+
+
Creating the namespace classes using new, reserves the class name as a context
+in newLISP and facilitates forward references. At the same time a simple
+constructor is defined for the new class for instantiating new objects. As a convention it is
+recommended to start class names in upper-case to signal that the name stands for a namespace.
+
+
In some cases it may be useful to overwrite the simple constructor, which was created during class creation
+with new:
+
+
+; overwrite simple constructor
+(define (Circle:Circle x y radius)
+ (list Circle x y radius))
+
+
+
A constructor can also specify defaults:
+
+
+; constructor with defaults
+(define (Circle:Circle (x 10) (y 10) (radius 3))
+ (list Circle x y radius))
+
+
+
In many cases the constructor as created when using new is sufficient and overwriting
+it is not necessary.
+
+
+
+
Objects and associations
+
+
FOOP represents objects as lists. The first element of the list indicates the object's kind or class, while the remaining elements contain the data. The following statements define two objects using any of the contructors defined previously:
The street number has been changes from 123 to 456.
+
+
+
+
The colon : operator and polymorphism
+
+
In newLISP, the colon character : is primarily used to
+connect the context symbol with the symbol it is qualifying.
+Secondly, the colon function is used in OOP to resolve a function's
+application polymorphically.
+
+
The following code defines two functions called area,
+each belonging to a different namespace. Both functions could
+have been defined in different modules, but in this case they are
+defined in the same file and without bracketing
+context statements. Here, only
+the symbols rectangle:area and circle:area belong
+to different namespaces. The local parameters p, c, dx, and dy are all part of MAIN,
+but this is of no concern.
+
+
+;; class methods for rectangles
+
+(define (Rectangle:area p)
+ (mul (p 3) (p 4)))
+
+(define (Rectangle:move p dx dy)
+ (list Rectangle (add (p 1) dx) (add (p 2) dy) (p 3) (p 4)))
+
+;; class methods for circles
+
+(define (Circle:area c)
+ (mul (pow (c 3) 2) (acos 0) 2))
+
+(define (Circle:move p dx dy)
+ (list Circle (add (p 1) dx) (add (p 2) dy) (p 3)))
+
+
+
By prefixing the area or move symbol with the : (colon), we can call these functions for each class of object. Although there is no space between the colon and the symbol following it, newLISP parses them as distinct entities. The colon works as a function that processes parameters:
In this example, the correct qualified symbol (rectangle:area or circle:area) is constructed and applied to the object data based on the symbol following the colon and the context name (the first element of the object list).
+
+
Note that moving the shapes is done in a functional manner.
+Rather than changing the x and y coordinates directly in myrect and mycircle, newLISP constructs and then reassigns the moved shapes.
+
+
+
+
+
18. XML, S-XML, and XML-RPC
+
+newLISP's built-in support for XML-encoded data or documents
+comprises three functions:
+xml-parse,
+xml-type-tags, and xml-error.
+
+
+
+Use the xml-parse function
+to parse XML-encoded strings.
+When xml-parse encounters an error,
+nil is returned.
+To diagnose syntax errors caused by incorrectly formatted XML,
+use the function xml-error.
+The xml-type-tags function can be used
+to control or suppress the appearance of XML type tags.
+These tags classify XML into one of four categories:
+text, raw string data, comments, and element data.
+
+
+XML source:
+
+<?xml version="1.0"?>
+<DATABASE name="example.xml">
+<!--This is a database of fruits-->
+ <FRUIT>
+ <NAME>apple</NAME>
+ <COLOR>red</COLOR>
+ <PRICE>0.80</PRICE>
+ </FRUIT>
+</DATABASE>
+
+ S-XML is XML
+ reformatted as LISP S-expressions.
+ The @ (at symbol) denotes
+ an XML attribute specification.
+
+
+ See xml-parse in
+ the reference section of the manual
+ for details on parsing and option numbers,
+ as well as for a longer example.
+
+
+ XML-RPC
+
+
+ The remote procedure calling protocol XML-RPC uses
+ HTTP post requests as a transport and
+ XML for the encoding of method names, parameters, and parameter types.
+ XML-RPC client libraries and servers have been implemented
+ for most popular compiled and scripting languages.
+
+
+ For more information about XML,
+ visit www.xmlrpc.com.
+
+
+ XML-RPC clients and servers are easy to write
+ using newLISP's built-in network and XML support.
+ A stateless XML-RPC server implemented as a CGI service,
+ can be found in the file examples/xmlrpc.cgi. This
+ script can be used together with a web server, like Apache.
+ This XML-RPC service scripts implement
+ the following methods:
+
+
+
+
+
method
description
+
+
system.listMethods
+
Returns a list of all method names
+
+
+
system.methodHelp
+
Returns help for a specific method
+
+
+
system.methodSignature
+
Returns a list of return/calling signatures for a specific method
+
+
+
newLISP.evalString
+
Evaluates a Base64 newLISP expression string
+
+
+
+
+
+ The first three methods
+ are discovery methods
+ implemented by most XML-RPC servers.
+ The last one is specific
+ to the newLISP XML-RPC server script and
+ implements remote evaluation of
+ a Base64-encoded string of newLISP source code.
+ newLISP's base64-enc
+ and base64-dec functions
+ can be used to encode and decode
+ Base64-encoded information.
+
+
+ In the modules directory
+ of the source distribution,
+ the file xmlrpc-client.lsp implements
+ a specific client interface for
+ all of the above methods.
+
+ In a similar fashion,
+ standard system.xxx calls can be issued.
+
+
+ All functions return either a result if successful,
+ or nil if a request fails.
+ In case of failure,
+ XMLRPC:error can be evaluated
+ to return an error message.
+
+
+ For more information,
+ please consult the header
+ of the file modules/xmlrpc-client.lsp.
+
+
+
+( § )
+
+
+
+
+ 19. Customization, localization, and UTF-8
+
+
+ All built-in primitives
+ in newLISP can be easily renamed:
+
+
+(constant 'plus +)
+
+ Now, plus is functionally equivalent to +
+ and runs at the same speed.
+ As with many scripting languages,
+ this allows for double precision floating point arithmetic
+ to be used throughout newLISP.
+
+
+ The constant function,
+ rather than the set function,
+ must be used to rename built-in primitive symbols.
+ By default, all built-in function symbols
+ are protected against accidental overwriting.
+
+ All operations using +, -, *, and /
+ are now performed as floating point operations.
+
+
+ Using the same mechanism,
+ the names of built-in functions
+ can be translated into languages
+ other than English:
+
+
+(constant 'wurzel sqrt) ; German for 'square-root'
+(constant 'imprime print) ; Spanish for 'print'
+ …
+
+
+
+ Switching the locale
+
+
+ newLISP can switch locales
+ based on the platform and operating system.
+ On startup, newLISP attempts to
+ set the ISO C standard default POSIX locale,
+ available for most platforms and locales.
+ Use the set-locale function
+ to switch to the default locale:
+
+
+(set-locale "")
+
+ This switches to the default locale
+ used on your platform/operating system
+ and ensures character handling
+ (e.g., upper-case)
+ work correctly.
+
+
+ Many Unix systems have
+ a variety of locales available.
+ To find out which ones are available on
+ a particular Linux/UNIX/BSD system,
+ execute the following command
+ in a system shell:
+
+
+locale -a
+
+ This command prints a list of
+ all the locales available on your system.
+ Any of these may be
+ used as arguments to set-locale:
+
+
+(set-locale "es_US")
+
+ This would switch to a U.S. Spanish locale.
+ Accents or other characters
+ used in a U.S. Spanish environment
+ would be correctly converted.
+
+
+ See the manual description for more details
+ on the usage of set-locale.
+
+
+
+
+ Decimal point and decimal comma
+
+
+ Many countries use a comma instead of a period
+ as a decimal separator in numbers.
+ newLISP correctly parses numbers
+ depending on the locale set:
+
+
+;; switch to German locale on a Linux system
+(set-locale "de_DE")
+
+;; newLISP source and output use a decimal comma
+(div 1,2 3) → 0,4
+
+ The default POSIX C locale,
+ which is set when newLISP starts up,
+ uses a period as a decimal separator.
+
+
+ The following countries
+ use a period as a decimal separator:
+
+
Australia, Botswana, Canada (English-speaking), China, Costa Rica, Dominican Republic, El Salvador, Guatemala, Honduras, Hong Kong, India, Ireland, Israel, Japan, Korea (both North and South), Malaysia, Mexico, Nicaragua, New Zealand, Panama, Philippines, Puerto Rico, Saudi Arabia, Singapore, Thailand, United Kingdom, and United States
+
+
+ The following countries use
+ a comma as a decimal separator:
+
+
Albania, Andorra, Argentina, Austria, Belarus, Belgium, Bolivia, Brazil, Bulgaria, Canada (French-speaking), Croatia, Cuba, Chile, Colombia, Czech Republic, Denmark, Ecuador, Estonia, Faroes, Finland, France, Germany, Greece, Greenland, Hungary, Indonesia, Iceland, Italy, Latvia, Lithuania, Luxembourg, Macedonia, Moldova, Netherlands, Norway, Paraguay, Peru, Poland, Portugal, Romania, Russia, Serbia, Slovakia, Slovenia, Spain, South Africa, Sweden, Switzerland, Ukraine, Uruguay, Venezuela, and Zimbabwe
+
+
+
+
+ Unicode and UTF-8 encoding
+
+
+ Note that for many European languages,
+ the set-locale mechanism
+ is sufficient to display
+ non-ASCII character sets,
+ as long as each character is presented
+ as one byte internally.
+ UTF-8 encoding is only necessary for
+ multibyte character sets as described in
+ this chapter.
+
+
+ newLISP can be compiled
+ as a UTF-8–enabled application.
+ UTF-8 is a multibyte encoding
+ of the international Unicode character set.
+ A UTF-8–enabled newLISP
+ running on an operating system with UTF-8 enabled
+ can handle any character of the installed locale.
+
+
+ The following steps
+ make UTF-8 work with newLISP
+ on a specific operating system and platform:
+
+
+ (1) Use one of the makefiles
+ ending in utf8
+ to compile newLISP as
+ a UTF-8 application.
+ If no UTF-8 makefile
+ is available for your platform,
+ the normal makefile
+ for your operating system
+ contains instructions
+ on how to change it
+ for UTF-8.
+
+
+ The Mac OS X binary installer contains
+ a UTF-8–enabled version by default.
+
+
+ (2) Enable the UTF-8 locale
+ on your operating system.
+ Check and set a UTF-8 locale
+ on Unix and Unix-like OSes
+ by using the locale command
+ or the set-locale function within newLISP.
+ On Linux, the locale can be changed by setting
+ the appropriate environment variable.
+ The following example uses bash
+ to set the U.S. locale:
+
+
+export LC_CTYPE=en_US.UTF-8
+
+ (3) The UTF-8–enabled newLISP
+ automatically switches to the locale found
+ on the operating system.
+ Make sure the command shell
+ is UTF-8–enabled.
+ When using the Tcl/Tk front-end on Linux/UNIX,
+ Tcl/Tk will automatically switch to UTF-8 display
+ as long as the UNIX environment variable
+ is set correctly.
+ The U.S. version of WinXP's notepad.exe
+ can display Unicode UTF-8–encoded characters,
+ but the command shell and the Tcl/Tk front-end cannot.
+ On Linux and other UNIXes,
+ the Xterm shell can be used
+ when started as follows:
+
+
+LC_CTYPE=en_US.UTF-8 xterm
+
+ The following procedure can now be used
+ to check for UTF-8 support.
+ After starting newLISP, type:
+
+ While the uppercase omega (Ω) looks
+ like a big O on two tiny legs,
+ the lowercase omega (ω) has
+ a shape similar to a small w
+ in the Latin alphabet.
+
+
+ Note: Only the output of println
+ will be displayed as a character;
+ println's return value
+ will appear on the console
+ as a multibyte ASCII character.
+
+
+ When UTF-8–enabled newLISP
+ is used on a non-UTF-8–enabled display,
+ both the output and the return value
+ will be two characters.
+ These are the two bytes necessary
+ to encode the omega character.
+
+
+ When UTF-8–enabled newLISP is used,
+ the following string functions work
+ on character rather than byte boundaries:
+
+ All other string functions work on bytes.
+ When positions are returned,
+ as in find or regex,
+ they are byte positions rather than character positions.
+ The slice function
+ takes not character offset, but byte offsets.
+ The reverse function reverses
+ a byte vector, not a character vector.
+ The last two functions can still be used to manipulate
+ binary non-textual data in the UTF-8–enabled version of newLISP.
+
+
+ To enable UTF-8 in Perl Compatible Regular Expressions (PCRE)
+ — used by directory, find, parse, regex, and
+ replace —
+ set the option number accordingly (2048).
+ See the regex documentation for details.
+
+
+ Use explode to obtain an array
+ of UTF-8 characters and to manipulate characters rather than bytes
+ when a UTF-8–enabled function is unavailable:
+
+ The above string functions
+ (often used to manipulate non-textual binary data)
+ now work on character,
+ rather than byte, boundaries,
+ so care must be exercised
+ when using the UTF-8–enabled version.
+ The size of the first 127 ASCII characters —
+ along with the characters in popular code pages such as ISO 8859 —
+ is one byte long.
+ When working exclusively within these code pages,
+ UTF-8–enabled newLISP is not required.
+ The set-locale function alone
+ is sufficient for localized behavior.
+
+
+ Two new functions are available
+ for converting between four-byte Unicode (UCS-4)
+ and multibyte UTF-8 code.
+ The UTF-8 function converts UCS-4
+ to UTF-8, and the unicode function converts UTF-8
+ or ASCII strings into USC-4 Unicode.
+
+
+ These functions are rarely used in practice,
+ as most Unicode text files
+ are already UTF-8–encoded
+ (rather than UCS-4,
+ which uses four-byte integer characters).
+ Unicode can be displayed directly
+ when using the "%ls"format specifier.
+
+ Some of the example programs contain functions
+ that use a comma to separate the parameters into two groups.
+ This is not a special syntax of newLISP,
+ but rather a visual trick.
+ The comma is a symbol just like any other symbol.
+ The parameters after the comma are not required
+ when calling the function;
+ they simply declare local variables in a convenient way.
+ This is possible in newLISP because parameter variables in lambda expressions
+ are local and arguments are optional:
+
+
+(define (my-func a b c , x y z)
+ (set 'x …)
+ (…))
+
+ When calling this function,
+ only a, b, and c are used as parameters.
+ The others (x, y, and z)
+ are initialized to nil
+ and are local to the function.
+ After execution, the function's contents are forgotten
+ and the environment's symbols are restored
+ to their previous values.
+
+
+ For other ways of declaring and initializing local variables,
+ see let, letex,
+ letn and local.
+
+
+
+( § )
+
+
+
+
+ 21. Linking newLISP source and executable
+
+
+ Source code and the newLISP executable
+ can be linked together to build
+ a self-contained application
+ by using link.lsp. This program is located in the newlisp/util directory of the distributions.
+ As an example,
+ the following code is linked to the newLISP executable
+ to form a simple, self-contained application:
+
+
+;; uppercase.lsp - Link example
+(println (upper-case (main-args 1)))
+(exit)
+
+ This program, which resides in the file uppercase.lsp, takes the first word on the command line and converts it to uppercase.
+
+
+ To build this program as a self-contained executable,
+ follow these four steps:
+
+
+ (1) Put the following files into the same directory:
+ (a) a copy of the newLISP executable; (b) newlisp
+ (or newlisp.exe on Win32); (c) link.lsp; and (d) the program to link with (uppercase.lsp in this example).
+
+
+ (2) In a shell,
+ go to the directory referred to in step 1
+ and load link.lsp:
+
+
+newlisp link.lsp
+
+ (3) In the newLISP shell, type one of the following:
+
+ Note: On Linux/BSD, the new file must be marked
+ executable for the operating system to recognize it:
+
+
+chmod 755 uppercase
+
+ This gives the file executable permission
+ (this step is unnecessary on Win32).
+
+
+
+
+
+
+
+
+( ∂ )
+
+
+
+
newLISP Function Reference
+
+
+
+
+
1. Syntax of symbol variables and numbers
+
+ Source code in newLISP is parsed according the rules outlined here.
+ When in doubt, verify the behavior of newLISP's internal parser
+ by calling parse without optional arguments.
+
+
+
+
Symbols for variable names
+
+ The following rules apply to the naming of symbols
+ used as variables or functions:
+
+
+
+
+
Variable symbols may not start with any of the following characters:
+# ; " ' ( ) { } . , 0 1 2 3 4 5 6 7 8 9
+
+
Variable symbols starting with a + or - cannot have a number as the second character.
+
+
Any character is allowed inside a variable name, except for:
+ " ' ( ) : , and the space character. These mark the end of a variable symbol.
+
+
A symbol name starting with [ (left square bracket) and ending with ] (right square bracket) may contain any character except the right square bracket.
+
+
+
+
+
+
+ All of the following symbols are legal variable names in newLISP:
+
+
+example:
+
+
+myvar
+A-name
+X34-zz
+[* 7 5 ()};]
+*111*
+
+
+
+
+ Sometimes it is useful to create hash-like lookup dictionaries
+ with keys containing characters that are illegal in newLISP variables.
+ The functions sym and context
+ can be used to create symbols containing these characters:
+
+ The last example creates the symbol 1
+ containing the value 123.
+ Also note that creating such a symbol does not alter newLISP's normal operations,
+ since 1 is still parsed as the number one.
+
+
+
+
+
Numbers
+
+
+ newLISP recognizes the following number formats:
+
+
+
+ Integers are one or more digits long,
+ optionally preceded by a + or - sign.
+ Any other character marks the end of the integer
+ or may be part of the sequence
+ if parsed as a float (see float syntax below).
+
+
+example:
+
+
+123
++4567
+-999
+
+
+
+
+ Hexadecimals start with a 0x (or 0X)
+ followed by any combination of the hexadecimal digits:
+ 0123456789abcdefABCDEF.
+ Any other character ends the hexadecimal number.
+
+
+example:
+
+
+0xFF → 255
+0x10ab → 4267
+0X10CC → 4300
+
+
+
+
+ Octals start with an optional + (plus) or - (minus) sign and a 0 (zero),
+ followed by any combination of the octal digits: 01234567.
+ Any other character ends the octal number.
+
+
+example:
+
+
+012 → 10
+010 → 8
+077 → 63
+-077 → -63
+
+
+
+
+
+ Floating point numbers can start
+ with an optional + (plus) or - (minus) sign,
+ but they cannot be followed by a 0 (zero) if they are.
+ This would make them octal numbers instead of floating points.
+ A single . (decimal point) can appear anywhere within
+ a floating point number, including at the beginning.
+
+ As described above, scientific notation
+ starts with a floating point number
+ called the significand (or mantissa),
+ followed by the letter e or E
+ and an integer exponent.
+
+ Arguments are represented by symbols
+ formed by the argument's type and name,
+ separated by a - (hyphen).
+ Here, str-format (a string) and exp-data-1 (an expression)
+ are named "format" and "data-1", respectively.
+
+
+
bool
+
+
+ true, nil,
+ or an expression evaluating to
+ one of these two.
+
+
+
+
+true, nil, (<= X 10)
+
+
+
+
int
+
+
+ An integer or an expression evaluating to an integer.
+ Generally, if a floating point number is used
+ when an int is expected,
+ the value is truncated to an integer.
+
+
+
+
+123, 5, (* X 5)
+
+
+
+
num
+
+ An integer, a floating point number,
+ or an expression evaluating to one of these two.
+ If an integer is passed,
+ it is converted to a floating point number.
+
+
+
+1.234, (div 10 3), (sin 1)
+
+
+
+
matrix
+
+ A list in which each row element is itself a list
+ or an array in which each row element is itself an array.
+ All element lists or arrays (rows) are of the same length.
+ When using det,
+ multiply,
+ or invert,
+ all numbers must be floats or integers.
+
+
+
+ The dimensions of a matrix are defined
+ by indicating the number of rows
+ and the number of column elements per row.
+ Functions working on matrices
+ ignore superfluous columns in a row.
+ For missing row elements,
+ 0.0 is assumed by the functions
+ det, multiply,
+ and invert,
+ while transpose assumes nil.
+ Special rules apply for transpose
+ when a whole row is not a list or an array,
+ but some other data type.
+
+ A string or an expression that evaluates to a string.
+
+
+
+"Hello", (append first-name " Miller")
+
+
+
+
+ Special characters can be included in quoted strings
+ by placing a \ (backslash) before the character
+ or digits to escape them:
+
+
+
+
+
escaped character
description
+
+
\n
+
the line feed character (ASCII 10)
+
+
+
+
\r
+
the carriage return character (ASCII 13)
+
+
+
+
\t
+
the tab character (ASCII 9)
+
+
+
+
\nnn
+
a decimal ASCII code where nnn is between 000 and 255
+
+
+
+
\xnn
+
a hexadecimal code where nn is between 00 and FF
+
+
+
+
+
+
+
+
+"\065\066\067" → "ABC"
+"\x41\x42\x43" → "ABC"
+
+
+
+
+ Instead of a " (double quote),
+ a { (left curly bracket)
+ and } (right curly bracket)
+ can be used to delimit strings.
+ This is useful when quotation marks need to occur inside strings.
+ Quoting with the curly brackets
+ suppresses the backslash escape effect for special characters.
+ Balanced nested curly brackets may be used within a string.
+ This aids in writing regular expressions or short sections of HTML.
+
+
+
+
+(print "<A HREF=\"http://mysite.com\">" ) ; the cryptic way
+
+(print {<A HREF="http://mysite.com">} ) ; the readable way
+
+;; also possible because the inner brackets are balanced
+(regex {abc{1,2}} line)
+
+(print [text]
+ this could be
+ a very long (> 2048 characters) text,
+ i.e. HTML.
+[/text])
+
+
+
+
+ The tags [text] and [/text]
+ can be used to delimit long strings
+ and suppress escape character translation.
+ This is useful for delimiting long HTML passages
+ in CGI files written in newLISP
+ or for situations where character translation
+ should be completely suppressed.
+ Always use the [text] tags
+ for strings longer than 2048 characters.
+
+
+
sym
+
+
+ A symbol or expression evaluating to a symbol.
+
+
+
+
+'xyz, (first '(+ - /)), '*, '- , 'someSymbol,
+
+
+
+
context
+
+
+ An expression evaluating to a context (namespace)
+ or a variable symbol holding a context.
+
+
+
+
+MyContext, aCtx, TheCTX
+
+
+
+
+ Most of the context symbols in this manual
+ start with an uppercase letter
+ to distinguish them from other symbols.
+
+
+
sym-context
+
+ A symbol, an existing context,
+ or an expression evaluating to a symbol
+ from which a context will be created.
+ If a context does not already exist,
+ many functions implicitly create them
+ (e.g., bayes-train, context, eval-string,
+load, sym, and xml-parse).
+ The context must be specified
+ when these functions are used
+ on an existing context.
+ Even if a context already exists,
+ some functions may continue to take symbols
+ (e.g., context).
+ For other functions,
+ such as context?,
+ the distinction is critical.
+
+
+
func
+
+
+ A symbol or an expression evaluating to
+ an operator symbol or lambda expression.
+
shows memory address and contents of newLISP cells
+
+
+
+
+
+
+
+
+
+( ∂ )
+
+
+
+
Functions in alphabetical order
+
+
+
!
+syntax: (! str-command)
+
+
+ Executes the command in str-command
+ by shelling out to the operating system
+ and executing.
+ This function returns a different value
+ depending on the host operating system.
+
+
+example:
+
+
+(! "vi")
+(! "ls -ltr")
+
+
+
+
+ Use the exec function
+ to execute a shell command
+ and capture the standard output
+ or to feed standard input.
+ The process function
+ may be used to launch a non-blocking child process
+ and redirect std I/O and std error to pipes.
+
+
+
+ Note that ! (exclamation mark) can be also be used as
+ a command-line shell operator
+ by omitting the parenthesis and space after the !:
+
+
+example:
+
+
+> !ls -ltr ; executed in the newLISP shell window
+
+
+
+
+ Used in this way,
+ the ! operator
+ is not a newLISP function at all,
+ but rather a special feature of
+ the newLISP command shell.
+ The ! must be entered
+ as the first character
+ on the command line.
+
+
+
+
+
+
$
+syntax: ($ int-idx)
+
+
+ The functions that use regular expressions
+ (directory,
+find, parse, regex, search, and replace)
+ all bind their results to
+ the predefined system variables
+ $0, $1, $2–$15
+ after or during the function's execution.
+ Both nth-set and set-nth
+ store the replaced expression in $0.
+ System variables can be treated
+ the same as any other symbol.
+ As an alternative,
+ the contents of these variables may also be accessed
+ by using ($ 0), ($ 1), ($ 2), etc.
+ This method allows indexed access
+ (i.e., ($ i), where i is an integer).
+
+
+example:
+
+
+(set 'str "http://newlisp.org:80")
+(find "http://(.*):(.*)" str 0) → 0
+
+$0 → "http://newlisp.org:80"
+$1 → "newlisp.org"
+$2 → "80"
+
+($ 0) → "http://newlisp.org:80"
+($ 1) → "newlisp.org"
+($ 2) → "80"
+
+(set 'L '(a b c d e f g))
+(set-nth (L 2) 'x) → (a b x d e f g)
+
+$0 → c
+($ 0) → c
+
+
+
+
+ For using captures within substitutions,
+ the $ system variables
+ can be accessed from within the functions
+ nth-set, set-nth, and replace:
+
+ Subtracts int-2 from int-1,
+ then the next int-i
+ from the previous result.
+ If only one argument is given,
+ its sign is reversed.
+
+
+syntax: (* int-1 [int-2 ... ])
+
+
+ The product is calculated for
+ int-1 to int-i.
+
+
+syntax: (/ int-1 [int-2 ... ])
+
+
+ Each result is divided successively
+ until the end of the list is reached.
+ Division by zero causes an error.
+
+
+syntax: (% int-1 [int-2 ... ])
+
+
+ Each result is divided successively
+ by the next int,
+ then the rest (modulo operation) is returned.
+ Division by zero causes an error.
+ For floating point numbers,
+ use the mod function.
+
+ Floating point values in arguments to
+ +, -, *, /, and %
+ are truncated to their floor value.
+
+
+
+ Floating point values larger or smaller than
+ the maximum (9,223,372,036,854,775,807)
+ or minimum (-9,223,372,036,854,775,808) integer values
+ are truncated to those values.
+
+
+
+ Calculations resulting in values
+ larger than 9,223,372,036,854,775,807
+ or smaller than -9,223,372,036,854,775,808
+ wrap around from positive to negative
+ or negative to positive.
+
+
+
+ For floating point values that evaluate to NaN (Not a Number),
+ both +INF and -INF are treated as 0 (zero).
+
+ Expressions are evaluated and the results are compared successively.
+ As long as the comparisons conform to the comparison operators,
+ evaluation and comparison will continue
+ until all arguments are tested
+ and the result is true.
+ As soon as one comparison fails,
+ nil is returned.
+
+
+
If only one argument is supplied,
+all comparison operators assume 0 (zero)
+as a second argument.
+
+
+
+ All types of expressions can be compared:
+ atoms, numbers, symbols, and strings.
+ List expressions can also be compared
+ (list elements are compared recursively).
+
+
+
+ When comparing lists,
+ elements at the beginning of the list
+ are considered more significant than the elements following
+ (similar to characters in a string).
+ When comparing lists of different lengths but equal elements,
+ the longer list is considered greater (see examples).
+
+
+
+ In mixed-type expressions,
+ the types are compared from lowest to highest.
+ Floats and integers are compared by first
+ converting them to the needed type,
+ then comparing them as numbers.
+
+ The number int-1 is arithmetically shifted
+ to the left or right by the number of bits given as int-2,
+ then shifted by int-3 and so on.
+ For example, 64-bit integers may be shifted up to 63 positions.
+ When shifting right,
+ the most significant bit is duplicated
+ (arithmetic shift):
+
+
+
+
+(>> 0x800000000000000 1) → 0xC00000000000000 ; not 0x040000000000000!
+
When used as an operator, the colon : constructs a context symbol from the context name in the object list and the symbol following the colon. The object list in list-object can be followed by other parameters.
+
+
The : operator implements polymorphism of object methods, which are part of different object classes represented by contexts (namespaces). In newLISP, an object is represented by a list, the first element of which is the symbol (name) of its class context.
+The class context implements the functions applicable to the object. No space is required between the colon and the symbol following it.
+
+example:
+
+
+(define (Rectangle:area p)
+ (mul (p 3) (p 4)))
+
+(define (Circle:area c)
+ (mul (pow (c 3) 2) (acos 0) 2))
+
+(define (Rectangle:move p dx dy)
+ (list rectangle (add (p 1) dx) (add (p 2) dy) (p 3) (p 4)))
+
+(define (Circle:move p dx dy)
+ (list circle (add (p 1) dx) (add (p 2) dy) (p 3)))
+
+(set 'myrect '(Rectangle 5 5 10 20)) ; x y width height
+(set 'mycircle '(Circle 1 2 10)) ; x y radius
+
+;; explicit naming of the context methods
+
+(Rectangle:area myrect)
+(Circle:area mycircle)
+
+(set 'myrect (Rectangle:move myrect 2 3))
+(set 'mycircle ((Circle:move mycircle 4 5))
+
+;; using the : (colon) operator to polymorphically
+;; resolve to a specific context
+
+(:area myrect) → 200
+(:area mycircle) → 314.1592654
+
+;; change object attributes using a function and re-assigning
+;; to the objects name
+
+(set 'myrect (:move myrect 2 3)) → (Rectangle 7 8 10 20)
+(set 'mycircle (:move mycircle 4 5)) → (Circle 5 7 10)
+
+
+
+
Using the colon : operator does not prohibit naming the method context explicitly when it is known.
+
+
In the first usage, the : is part of the syntax for qualifying a symbol with its context. The second usage of the : as an operator implements polymorphism by resolving the context at runtime.
+
+
Note that in the above example, the :move methods are implemented in a functional way, reassigning shapes with changed x and y coordinates to myrect and mycircle.
+
+
+
+
+
+
abs
+
+syntax: (abs num)
+
+
+ Returns the absolute value of the number in num.
+
+
+example:
+
+
+(abs -3.5) → 3.5
+
+
+
+
+
+
acos
+syntax: (acos num)
+
+
+ The arccosine function is calculated
+ from the number in num-radians.
+
+
+example:
+
+
+(acos 1) → 0
+(cos (acos 1)) → 1
+
+
+
+
+
+
acosh
+syntax: (acosh num-radians)
+
+
Calculates the inverse hyperbolic cosine of num-radians,
+the value whose hyperbolic cosine is num-radians.
+If num-radians is less than 1,
+acosh returns NaN.
+ All of the numbers in num-1, num-2, and on
+ are summed.
+ add accepts float or integer operands,
+ but it always returns a floating point number.
+ Any floating point calculation with NaN
+ also returns NaN.
+
+ Returns the memory address of the integer in int,
+ the double floating point number in float,
+ or the string in str.
+ This function is used for passing parameters to library functions
+ that have been imported using the import function.
+
+
+example:
+
+
+(set 's "\001\002\003\004")
+
+(get-char (+ (address s) 3)) → 4
+
+(set 'x 12345)
+
+; on a big-endian CPU, i.e. PPC or SPARC
+(get-int (+ (address x) 4)) → 12345
+
+; on a little-endian CPU, i.e. Intel i386
+(get-int (address x)) → 12345
+
+; on both architectures (integers are 64 bit in newLISP)
+(set 'x 1234567890)
+(get-long (address x)) → 1234567890
+
+
+
+
+
+ When a string is passed,
+ the address of the string is automatically used.
+ As the example shows,
+ address can be used to do pointer arithmetic
+ on the string's address.
+
+
+
address should only be used on persistent addresses from
+data objects referred to by a variable symbol, not from volatile intermediate
+expression objects.
+ One of the expressions exp-1 ... n is selected at random,
+ and the evaluation result is returned.
+
+
+example:
+
+
+(amb 'a 'b 'c 'd 'e) → one of: a, b, c, d, or e at random
+
+(dotimes (x 10) (print (amb 3 5 7))) → 35777535755
+
+
+
+
+ Internally, newLISP uses the same function as rand to pick a random number.
+ To generate random floating point numbers,
+ use random,
+ randomize, or normal.
+ To initialize the pseudo random number generating process
+ at a specific starting point,
+ use the seed function.
+
+
+
+
+
+
and
+syntax: (and exp-1 exp-2 [exp-3... ])
+
+
+ The expressions exp-1, exp-2, etc. are evaluated in order,
+ returning the result of the last expression.
+ If any of the expressions yield nil or the empty list (),
+ evaluation is terminated and nil or the empty list () is returned.
+
+
+example:
+
+
+(set 'x 10) → 10
+(and (< x 100) (> x 2)) → true
+(and (< x 100) (> x 2) "passed") → "passed"
+(and '()) → ()
+(and true) → true
+(and) → nil
+
+ In the third form,
+ append works on strings.
+ The strings in str-n are concatenated into
+ a new string and returned.
+
+
+example:
+
+
+(set 'more " how are you") → " how are you"
+
+(append "Hello " "world," more) → "Hello world, how are you"
+
+
+
+
+ append is also suitable
+ for processing binary strings
+ containing zeroes.
+
+
+
+ Linkage characters or strings can be specified
+ using the join function.
+ Use the string function
+ to convert arguments to strings and append in one step.
+
+
+
+ Use the functions push or
+ write-buffer
+ (with its special syntax)
+ to append to an existing string in place.
+
+
+
+
+
append-file
+syntax: (append-file str-filenamestr-buffer)
+
+
+ Works similarly to write-file,
+ but the content in str-buffer is appended
+ if the file in str-filename exists.
+ If the file does not exist, it is created
+ (in this case, append-file works identically to write-file).
+ This function returns the number of bytes written.
+
append-file can take a http:// or file:// URL
+in str-file-name. In this case append-file works exactly like
+put-url with "Pragma: append\r\n"
+in the header option and can take the same additional parameters. The
+"Pragma: append\r\n" option is supplied automatically.
+
The file message.txt is appended at a remote
+location http://asite.com with the contents of
+str-buffer. If the file does not yet exist, it
+will be created. In this mode, append-file can also be used
+to transfer files to remote newLISP server nodes.
+
+ The int-reduce parameter can optionally contain
+ the number of arguments taken by the function in func.
+ In this case,
+ func will be repeatedly applied using the previous result
+ as the first argument and taking the other arguments required
+ successively from list
+ (in left-associative order).
+ For example, if op takes two arguments, then:
+
+
+
+
+(apply op '(1 2 3 4 5) 2)
+
+;; is equivalent to
+
+(op (op (op (op 1 2) 3) 4) 5)
+
+;; find the greatest common divisor
+;; of two or more integers
+;; note that newLISP already has a gcd function
+
+(define (gcd_ a b)
+(let (r (% b a))
+ (if (= r 0) a (gcd_ r a))))
+
+(define-macro (my-gcd)
+ (apply gcd_ (args) 2))
+
+(my-gcd 12 18 6) → 6
+(my-gcd 12 18 6 4) → 2
+
+
+
+
+ The last example shows how apply's reduce functionality
+ can be used to convert a two-argument function
+ into one that takes multiple arguments.
+
+
+
+ apply should only be used on functions and operators
+ that evaluate all of their arguments,
+ not on special forms
+ like setq or case,
+ which evaluate only some of their arguments.
+ Doing so will cause the function to fail.
+
+ Accesses a list of all unbound arguments
+ passed to the currently evaluating
+ define, define-macro
+ lambda, or lambda-macro expression.
+ Only the arguments of the current function or macro
+ that remain after local variable binding has occurred
+ are available.
+ The args function is useful for defining functions or macros
+ with a variable number of parameters.
+
+
+
+ args can be used to define hygienic macros
+ that avoid the danger of variable capture.
+ See define-macro.
+
+ The function foo
+ prints out the arguments in reverse order.
+ The bar function
+ shows args being used
+ with multiple indices
+ to access nested lists.
+
+
+
+ Remember that (args) only contains the arguments
+ not already bound to local variables
+ of the current function or macro:
+
+ In the first example,
+ an empty list is returned because
+ the arguments are bound to the
+ two local symbols, a and b.
+ The second example demonstrates that,
+ after the first two arguments are bound
+ (as in the first example), three arguments remain
+ and are then returned by args.
+
+
+
+ (args) can be used as an argument
+ to a built-in or user-defined function call,
+ but it should not be used as an argument to another macro,
+ in which case (args) would not be evaluated
+ and would therefore have the wrong
+ contents in the new macro environment.
+
+ Creates an array with int-n1 elements,
+ optionally initializing it with the contents of list-init.
+ Up to sixteen dimensions may be specified for multidimensional arrays.
+
+
+
+ Internally,
+ newLISP builds multidimensional arrays
+ by using arrays as the elements of an array.
+ newLISP arrays should be used
+ whenever random indexing into a large list
+ becomes too slow.
+ Only a subset of the list functions
+ may be used on arrays.
+ For a more detailed discussion,
+ see the chapter on arrays.
+
+ Arrays can be initialized with objects of any type.
+ If fewer initializers than elements are provided,
+ the list is repeated until all elements of the array are initialized.
+
+ When serializing arrays using the function
+ source or save,
+ the code includes the array statement
+ necessary to create them.
+ This way,
+ variables containing arrays are correctly serialized
+ when saving with save or creating source strings
+ using source.
+
+
+
+In the first syntax the value of exp-key is used
+to search list-alist for a member-list
+whose first element matches the key value.
+If found, the member-list is returned;
+otherwise, the result will be nil.
+
The list in list-aList can be a context which will be interpreted
+as its default functor. This way very big lists can be passed by reference
+for speedier access and less memory usage:
+For making replacements in association lists, use the
+set-assoc function.
+The lookup function is used to perform association lookup
+and element extraction in one step and on single level association lists.
+
This function works like set-assoc but returns the replaced
+association instead of the entire changed association list.
+
+
+
+
+
+
atan
+5,900,000
+ (atan num-radians)
+
+
+ The arctangent of num-radians
+ is calculated and returned.
+
+
+example:
+
+
+(atan 1) → 0.7853981634
+(tan (atan 1)) → 1
+
+
+
+
+
+
+
atan2
+syntax: (atan2 num-Y-radiansnum-X-radians)
+
+
+ The atan2 function computes
+ the principal value of
+ the arctangent of Y / X in radians.
+ It uses the signs of both arguments
+ to determine the quadrant of
+ the return value.
+ atan2 is useful for converting
+ Cartesian coordinates
+ into polar coordinates.
+
Calculates the inverse hyperbolic tangent of num-radians, the value whose hyperbolic tangent is num-radians. If the absolute value of num-radians is greater than 1, atanh returns NaN; if it is equal to 1, atanh returns infinity.
+ Returns true if the value of exp is an atom,
+ otherwise nil.
+ An expression is an atom, if it evaluates to nil,
+ true, an integer, a float, a string, a symbol or a primitive.
+ Lists, lambda or lambda-macro expressions,
+ and quoted expressions are not atoms.
+
+ newLISP's BASE64 handling is derived from
+ routines found in the UNIX curl utility.
+
+
+
+
+
+
+
base64-enc
+syntax: (base64-enc str)
+
+
+ The string in str is encoded into BASE64 format.
+ This format encodes groups of 3 * 8 = 24 input bits
+ into 4 * 8 = 32 output bits,
+ where each 8-bit output group
+ represents 6 bits from the input string.
+ The 6 bits are encoded into 64 possibilities
+ from the letters A–Z and a–z;
+ the numbers 0–9;
+ and the characters + (plus sign) and / (slash).
+ The = (equals sign) is used as a filler
+ in unused 3- to 4-byte translations.
+ This function is helpful for converting binary content
+ into printable characters.
+
+
+
+ The encoded string is returned.
+
+
+
+ BASE64 encoding is used with many Internet protocols
+ to encode binary data for inclusion in text-based messages
+ (e.g., XML-RPC).
+
+ Note that base64-enc does not insert
+ carriage-return/line-feed pairs in longer BASE64 sequences
+ but instead returns a pure BASE64-encoded string.
+
+ Takes a list of tokens (list-L)
+ and a trained dictionary (context-D)
+ and returns a list of the combined probabilities
+ of the tokens in one category
+ (A or Mc)
+ versus a category (B)
+ against all other categories (Mi).
+ All tokens in list-L
+ should occur in context-D.
+ When using the default R.A. Fisher Chi² mode,
+ nonexistent tokens will skew results
+ toward equal probability in all categories.
+
+
+
+ Non-existing tokens will not have any influence
+ on the result when using the true Chain Bayesian mode
+ with bool-chain set to true.
+ The optional last flag, bool-probs,
+ indicates whether frequencies or probability values
+ are used in the data set.
+ The bayes-train function
+ is typically used to generate
+ a data set's frequencies.
+
+
+
+ Tokens can be strings or symbols.
+ If strings are used,
+ they are prepended with an underscore
+ before being looked up in context-D.
+ If bayes-train was used
+ to generate context-D's frequencies,
+ the underscore was automatically prepended
+ during the learning process.
+
+
+
+ Depending on the flag specified in bool-probs,
+ bayes-query employs either the
+ R. A. Fisher Chi² method of compounding probabilities
+ or the Chain Bayesian method.
+ By default, when no flag or nil is specified in bool-probs,
+ the Chi² method of compounding probabilities is used.
+ When specifying true in bool-probs,
+ the Chain Bayesian method is used.
+
+
+
+ If the R.A. Fisher Chi² method is used,
+ the total number of tokens
+ in the different training set's categories
+ should be equal or similar.
+ Uneven frequencies in categories
+ will skew the results.
+
+
+
+ For two categories A and B,
+ bayes-query uses the following formula:
+
+ The probabilities (p(Mi) or p(A), along with p(B))
+ represent the Bayesian prior probabilities.
+ p(Mx|tkn) and p(A|tkn) are the
+ posterior Bayesian probabilities of a category or model.
+
+
+
+ Priors are handled differently,
+ depending on whether the R.A. Fisher Chi²
+ or the Chain Bayesian method is used.
+ While in Chain Bayesian mode,
+ posteriors from one token calculation get the priors in the next calculation.
+ In the default R.A. Fisher method,
+ priors are not passed on via chaining,
+ but probabilities are compounded using the Chi² method.
+
+
+
+ In Chain Bayes mode,
+ tokens with zero frequency in one category
+ will effectively put the probability of that category to 0 (zero).
+ This also causes all posterior priors to be set to 0
+ and the category to be completely suppressed in the result.
+ Queries resulting in zero probabilities for all categories
+ yield NaN values.
+
+
+
+ The default R.A. Fisher Chi² method
+ is less sensitive about zero frequencies
+ and still maintains a low probability for that token.
+ This may be an important feature in natural language processing
+ when using Bayesian statistics.
+ Imagine that five different language corpus categories have been trained,
+ but some words occurring in one category are not present in another.
+ When the pure Chain Bayesian method is used,
+ a sentence could never be classified into its correct category
+ because the zero-count of just one word token could effectively exclude it
+ from the category to which it belongs.
+
+
+
+ On the other hand,
+ the Chain Bayesian method offers exact results
+ for specific proportions in the data.
+ When using Chain Bayesian mode for natural language data,
+ all zero frequencies should be removed from the trained dictionary first.
+
+
+
+ The return value of bayes-query
+ is a list of probability values,
+ one for each category.
+ Following are two examples:
+ the first for the default R.A. Fisher mode,
+ the second for a data set processed with the Chain Bayesian method.
+
+
+
+
R.A. Fisher Chi² method
+
+
+ In the following example,
+ the two data sets are books from Project Gutenberg.
+ We assume that different authors
+ use certain words with different frequencies
+ and want to determine if a sentence is more likely to occur in one
+ or the other author's writing.
+ A similar method is frequently used to differentiate between spam
+ and legitimate email.
+
+
+
+
+;; from Project Gutenberg: http://www.gutenberg.org/catalog/
+;; The Adventures of Sherlock Holmes - Sir Arthur Conan Doyle
+
+(bayes-train (parse (lower-case (read-file "Doyle.txt"))
+ "[^a-z]+" 0) '() 'DoyleDowson)
+
+;; A Comedy of Masks - Ernest Dowson and Arthur Moore
+
+(bayes-train '() (parse (lower-case (read-file "Dowson.txt"))
+ "[^a-z]+" 0) 'DoyleDowson)
+
+(save "DoyleDowson.lsp" 'DoyleDowson)
+
+
+
+
+ The two training sets are loaded, split into tokens,
+ and processed by the bayes-train function.
+ In the end, the DoyleDowson dictionary is saved to a file,
+ which will be used later with the bayes-query function.
+
+
+
+ The following code illustrates how bayes-query is used
+ to classify a sentence as Doyle or Dowson:
+
+
+
+
+(load "DoyleDowson.lsp")
+(bayes-query (parse "he was putting the last touches to a picture")
+ 'DoyleDowson)
+→ (0.03801673331 0.9619832667)
+
+(bayes-query (parse "immense faculties and extraordinary powers of observation")
+ 'DoyleDowson)
+→ (0.9851075608 0.01489243923)
+
+
+
+
+ The queries correctly identify the first sentence as a Dowson sentence,
+ and the second one as a Doyle sentence.
+
+
+
+
+
Chain Bayesian method
+
+
+ The second example is frequently found
+ in introductory literature on Bayesian statistics.
+ It shows the Chain Bayesian method of
+ using bayes-query on the data of a previously processed data set:
+
+ A disease occurs in 10 percent of the population.
+ A blood test developed to detect this disease
+ produces a false positive rate of 20 percent in the healthy population
+ and a false negative rate of 20 percent in the sick.
+ What is the probability of a person carrying
+ the disease after testing positive?
+
+example:
+
+
+(bayes-query '(test-positive) Data true)
+→ (0.3076923077 0.6923076923)
+
+(bayes-query '(test-positive test-positive) Data true)
+→ (0.64 0.36)
+
+(bayes-query '(test-positive test-positive test-positive) Data true)
+→ (0.8767123288 0.1232876712)
+
+
+
+
+ Note that the Bayesian formulas used
+ assume statistical independence of events
+ for the bayes-query to work correctly.
+
+
+
+ The example shows that a person must test positive several times
+ before they can be confidently classified as sick.
+
+
+
+ Calculating the same example using the R.A. Fisher Chi² method
+ will give less-distinguished results.
+
+
+
+
Specifying probabilities instead of counts
+
+
+ Often, data is already available as probability values
+ and would require additional work to reverse them into frequencies.
+ In the last example, the data were originally defined as percentages.
+ The additional optional bool-probs flag
+ allows probabilities to be entered directly
+ and should be used together with the Chain Bayesian mode
+ for maximum performance:
+
+ Takes one or more lists of tokens (M1, M2—)
+ from a joint set of tokens.
+ In newLISP, tokens can be symbols or strings
+ (other data types are ignored).
+ Tokens are placed in a common dictionary
+ in sym-context-D,
+ and the frequency is counted for each token
+ in each category Mi.
+ If the context does not yet exist,
+ it must be quoted.
+
+
+
+ The M categories represent data models
+ for which sequences of tokens can be classified
+ (see bayes-query).
+ Each token in D is a content-addressable symbol
+ containing a list of the frequencies
+ for this token within each category.
+ String tokens are prepended with an _ (underscore)
+ before being converted into symbols.
+ A symbol named total is created
+ containing the total of each category.
+ The total symbol cannot be part
+ of the symbols passed as an Mi category.
+
+
+
+ The function returns a list of token frequencies
+ found in the different categories or models.
+
+
+example:
+
+
+(bayes-train '(A A B C C) '(A B B C C C) 'L) → (5 6)
+
+L:A → (2 1)
+L:B → (1 2)
+L:C → (2 3)
+L:total → (5 6)
+
+(bayes-train '("one" "two" "two" "three")
+ '("three" "one" "three")
+ '("one" "two" "three") 'S)
+→ (4 3 3)
+
+S:_one → (1 1 1)
+S:_two → (2 0 1)
+S:_three → (1 2 1)
+S:total → (4 3 3)
+
+
+
+
+ The first example shows training with two lists of symbols.
+ The second example illustrates how an _ is prepended
+ when training with strings.
+
+
+
+ Note that these examples are just for demonstration purposes.
+ In reality, training sets may contain thousands or millions of words,
+ especially when training natural language models.
+ But small data sets may be used when then the frequency of symbols
+ just describe already-known proportions.
+ In this case, it may be better to describe the model data set explicitly,
+ without the bayes-train function:
+
+ The last data are from a popular example used
+ to describe the bayes-query function
+ in introductory papers and books about bayesian networks.
+
+
+
+ Training can be done in different stages
+ by using bayes-train on an existing trained context
+ with the same number of categories.
+ The new symbols will be added,
+ then counts and totals will be correctly updated.
+
+
+
+ Training in multiple batches may be necessary
+ on big text corpora or documents
+ that must be tokenized first.
+ These corpora can be tokenized in small portions,
+ then fed into bayes-train in multiple stages.
+ Categories can also be singularly trained
+ by specifying an empty list for the absent corpus:
+
+ bayes-train will correctly update word counts and totals.
+
+
+
+ Using bayes-train inside a context other than MAIN
+ requires the training contexts to have been created previously within
+ the MAIN context via the context function.
+
+
+
+ bayes-train is not only useful with the bayes-query function,
+ but also as a function for counting in general.
+ For instance, the resulting frequencies
+ could be analyzed using prob-chi2
+ against a null hypothesis of proportional distribution
+ of items across categories.
+
+
+
+
+
+
begin
+syntax: (begin body)
+
+
+ The begin function is used to group a block of expressions.
+ The expressions in body are evaluated in sequence, and
+ the value of the last expression in body is returned.
+
+
+example:
+
+
+(begin
+ (print "This is a block of 2 expressions\n")
+ (print "================================"))
+
+
+
+
+ Some built-in functions like cond, define,
+ dolist, dotimes, and while
+ already allow multiple expressions in their bodies,
+ but begin is often used in an if expression.
+
+
+
+ The silent function works like begin,
+ but suppresses console output on return.
+
+
+
+
+
+
beta
+syntax: (beta cum-anum-b)
+
+
+ The Beta function, beta,
+ is derived from the log Gamma
+ gammaln function as follows:
+
+ The Incomplete Beta function, betai,
+ equals the cumulative probability of the Beta distribution, betai,
+ at x in num-x.
+ The cumulative binomial distribution is defined as the probability of an event, pev,
+ with probability p to occur k or more times in N trials:
+
+
+
+ pev = Betai(p, k, N - k + 1)
+
+example:
+
+
+(betai 0.5 3 8) → 0.9453125
+
+;; probability of F ratio for df1/df2
+;;
+(define (f-prob f df1 df2)
+ (let (prob (mul 2 (betai (div df2 (add df2 (mul df1 f)))
+ (mul 0.5 df2)
+ (mul 0.5 df1))))
+ (div (if (> prob 1) (sub 2 prob) prob) 2)))
+
+
+
+
+ The first example calculates the probability for an event,
+ with a probability of 0.5 to occur 3 or more times in 10 trials (8 = 10 - 3 + 1).
+ The incomplete Beta distribution can be used to derive a variety of other functions
+ in mathematics and statistics.
+ The second example calculates the one-tailed probability of a variance, F ratio.
+ In similar fashion, students t could be calculated using betai.
+ See also the binomial function.
+
The return value of bind is the value of the last association.
+
+
bind is often used to bind association lists returned
+by unify.
+
+
+(bind (unify '(p X Y a) '(p Y X X))) → a
+
+X → a
+Y → a
+
+
+
The return value of bind is the value of the last association.
+
+
+
+
+
+
binomial
+syntax: (binomial int-nint-kfloat-p)
+
+
+ The binomial distribution function is defined as
+ the probability for an event to occur int-k times in int-n trials
+ if that event has a probability of float-p
+ and all trials are independent of one another:
+
+ where x! is the factorial of x
+ and pow(x, y) is x raised to the power of y.
+
+
+
+
+example:
+
+
+(binomial 10 3 0.5) → 0.1171875
+
+
+
+
+ The example calculates the probability for an event
+ with a probability of 0.5 to occur 3 times in 10 trials.
+ For a cumulated distribution,
+ see the betai function.
+
+
+
+
+
+
callback
+syntax: (callback int-indexsym-function)
+
+
Up to eight callback functions
+can be registered with imported libraries.
+The callback function returns a procedure address
+that invokes a user-defined function in sym-function.
+The following example shows the usage of callback functions
+when importing the
+OpenGL graphics library:
The address returned by callback
+is registered with the Glut library.
+The above code is a snippet from the file opengl-demo.lsp,
+in the examples/ directory of the source distribution of newLISP.
+ The result of evaluating exp-switch
+ is compared to each of the unevaluated expressions
+ exp-1, exp-2, —.
+ If a match is found,
+ the corresponding expressions in body are evaluated.
+ The result of the last match is returned
+ as the result for the entire case expression.
+ In the first syntax,
+ catch will return the result of the evaluation of exp
+ or the evaluated argument of a throw
+ executed during the evaluation of exp:
+
+ This form is useful for breaking out of iteration loops
+ and for forcing an early return
+ from a function or expression block:
+
+
+
+
+(define (foo x)
+ …
+ (if condition (throw 123))
+ …
+ 456)
+
+;; if condition is true
+
+(catch (foo p)) → 123
+
+;; if condition is not true
+
+(catch (foo p)) → 456
+
+
+
+
+
+ In the second syntax,
+ catch evaluates the expression exp,
+ stores the result in symbol,
+ and returns true.
+ If an error occurs during evaluation,
+ catch returns nil
+ and stores the error message in symbol.
+ This form can be useful when errors are expected
+ as a normal potential outcome of a function
+ and are dealt with during program execution.
+
+ As well as being used for early returns from functions and
+ for breaking out of iteration loops (as in the first syntax),
+ the second syntax of catch can also be used to catch errors.
+ The throw-error function may be used
+ to throw user-defined errors.
+
+
+
+
+
+
+
ceil
+syntax: (ceil number )
+
+
+ Returns the next highest integer above number
+ as a floating point.
+
+ Given a string argument,
+ extracts the character at int-index from str,
+ returning the ASCII value of that character.
+ If int-index is omitted,
+ 0 (zero) is assumed.
+
+ If the first argument evaluates to a string,
+ chop returns a copy of str
+ with the last int-char characters omitted.
+ If the int-char argument is absent,
+ one character is omitted.
+ chop does not alter str.
+
+
+
+ If the first argument evaluates to a list,
+ a copy of list is returned
+ with int-elements omitted
+ (same as for strings).
+
+
+example:
+
+
+(set 'str "newLISP") → "newLISP"
+
+(chop str) → "newLIS"
+(chop str 2) → "newLI"
+
+str → "newLISP"
+
+(set 'lst '(a b (c d) e))
+
+(chop lst) → (a b (c d))
+(chop lst 2) → (a b)
+
+lst → (a b (c d) e)
+
+
+
+
+
+
+
clean
+syntax: (clean exp-predicatelist)
+
+
+ The predicate exp-predicate is applied
+ to each element of list.
+ In the returned list,
+ all elements for which exp-predicate is true
+ are eliminated.
+
+
+
+ clean works like filter
+ with a negated predicate.
+
+
+example:
+
+
+(clean symbol? '(1 2 d 4 f g 5 h)) → (1 2 4 5)
+
+(filter symbol? '(1 2 d 4 f g 5 h)) → (d f g h)
+
+(define (big? x) (> x 5)) → (lambda (x) (> x 5))
+
+(clean big? '(1 10 3 6 4 5 11)) → (1 3 4 5)
+
+(clean <= '(3 4 -6 0 2 -3 0)) → (3 4 2)
+
+(clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
+→ ((b 5) (c 8))
+
+
+
+
+ The predicate may be a built-in predicate
+ or a user-defined function or lambda expression.
+
+
+
+ For cleaning numbers from one list
+ using numbers from another,
+ use difference
+ or intersect
+ (with the list option).
+
+
+
+ See also the related function index,
+ which returns the indices of the remaining elements,
+ and filter,
+ which returns all elements for which a predicate returns true.
+
+
+
+
+
+
close
+syntax: (close int-file)
+
+
+ Closes the file specified by the file handle in int-file.
+ The handle would have been obtained
+ from a previous open operation.
+ If successful, close returns true; otherwise nil is returned.
+
+ Note that using close on device
+ automatically resets it to 0 (zero, the screen device).
+
+
+
+
+
+
command-line
+syntax: (command-line [bool])
+
+
+ Enables or disables the console's
+ interactive command-line mode.
+ The command line is switched off
+ if bool evaluates to nil,
+ and on for anything else.
+ The command line is also switched on
+ if reset or an error condition occurs.
+
+
+example:
+
+
+(command-line nil)
+
+
+
+
+ On Linux/UNIX,
+ this will also disable the Ctrl-C handler.
+
+ Like if, cond conditionally evaluates the expressions
+ within its body.
+ The exp-conditions are evaluated in turn,
+ until some exp-condition-i is found
+ that evaluates to anything other than nil
+ or an empty list ().
+ The result of evaluating body-i
+ is then returned as the result of the entire cond-expression.
+ If all conditions evaluate to nil
+ or an empty list,
+ cond returns the value of the last cond-expression.
+
+ When a body-n is missing,
+ the value of the last cond-expression evaluated
+ is returned.
+ If no condition evaluates to true,
+ the value of the last conditional expression is returned
+ (i.e., nil or an empty list).
+
+
+
+
+(cond ((+ 3 4))) → 7
+
+
+
+
+ When used with multiple arguments,
+ the function if
+ behaves like cond,
+ except it does not need extra parentheses
+ to enclose the condition-body pair
+ of expressions.
+
+
+
+
+
+
cons
+syntax: (cons exp-1exp-2)
+
+
+ If exp-2 evaluates to a list,
+ then a list is returned with the result of evaluating exp-1
+ inserted as the first element.
+ If exp-2 evaluates to anything other than a list,
+ the results of evaluating exp-1 and exp-2
+ are returned in a list.
+ Note that there is no dotted pair in newLISP:
+ consing two atoms constructs a list, not a dotted pair.
+
+
+example:
+
+
+(cons 'a 'b) → (a b)
+(cons 'a '(b c)) → (a b c)
+(cons (+ 3 4) (* 5 5)) → (7 25)
+(cons '(1 2) '(3 4)) → ((1 2) 3 4)
+(cons nil 1) → (nil 1)
+(cons 1 nil) → (1 nil)
+(cons 1) → (1)
+(cons) → ()
+
+
+
+
+ Unlike other LISPs that return (s)
+ as the result of the expression (cons 's nil),
+ newLISP's cons returns (s nil).
+ In newLISP, nil is a boolean value
+ and is not equivalent to an empty list,
+ and a LISP cell holds only one value.
+
+
+
+ cons behaves like the inverse operation of first
+and rest
+ (or first and last if the list is a pair):
+
+
+
+
+(cons (first '(a b c)) (rest '(a b c))) → (a b c)
+
+(cons (first '(x y)) (last '(x y))) → (x y)
+
+ Identical to set in functionality,
+ constant further protects the symbols from subsequent modification.
+ A symbol set with constant can only be modified
+ using the constant function again.
+ When an attempt is made to modify the contents of a symbol protected with constant,
+ newLISP generates an error message.
+ Only symbols from the current context can be used with constant.
+ This prevents the overwriting of symbols
+ that have been protected in their home context.
+
+
+
+ Symbols initialized with set, define, or define-macro
+can still be protected by using the constant function:
+
+
+
+
+(constant 'aVar 123) → 123
+(set 'aVar 999)
+error: symbol is protected in function set: aVar
+
+(define (double x) (+ x x))
+
+(constant 'double)
+
+;; equivalent to
+
+(constant 'double (fn (x) (+ x x)))
+
+
+
+
+ The first example defines a constant, aVar,
+ which can only be changed by using another constant statement.
+ The second example protects double from being changed
+ (except by constant).
+ Because a function definition in newLISP
+ is equivalent to an assignment of a lambda function,
+ both steps can be collapsed into one,
+ as shown in the last statement line.
+ This could be an important technique
+ for avoiding protection errors
+ when a file is loaded multiple times.
+
+
+
+ The last value to be assigned can be omitted.
+ constant returns the contents of
+ the last symbol set and protected.
+
+
+
+ Built-in functions can be assigned to symbols
+ or to the names of other built-in functions,
+ effectively redefining them as different functions.
+ There is no performance loss when renaming functions.
+
+ squareroot will behave like sqrt.
+ The + (plus sign) is redefined
+ to use the mixed type floating point mode of add.
+ The hexadecimal number displayed in the result
+ is the binary address of the built-in function
+ and varies on different platforms and OSes.
+
+ In the first syntax, context is used
+ to switch to a different context namespace.
+ Subsequent loads of newLISP source
+ or functions like eval-string
+ will put newly created symbols and
+ function definitions in the new context.
+
+
+
+ If the context still needs to be created,
+ the symbol for the new context should be specified.
+ When no argument is passed to context, then
+ the symbol for the current context is returned.
+
+
+ Because contexts evaluate to themselves,
+ a quote is not necessary
+ to switch to a different context
+ if that context already exists.
+
+
+example:
+
+
+(context 'GRAPH) ; create / switch context GRAPH
+
+(define (foo-draw x y z) ; function resides in GRAPH
+ (…))
+
+(set 'var 12345)
+(symbols) → (foo-draw var) ; GRAPH has now two symbols
+
+(context MAIN) ; switch back to MAIN (quote not required)
+
+(print GRAPH:var) → 12345 ; contents of symbol in GRAPH
+
+(GRAPH:foo-draw 10 20 30) ; execute function in GRAPH
+(set 'GRAPH:var 6789) ; assign to a symbol in GRAPH
+
+
+
+
+ If a context symbol is referred to before the context exists,
+ the context will be created implicitly.
+
+
+
+
+(set 'person:age 0) ; no need to create context first
+(set 'person:address "") ; useful for quickly defining data structures
+
+
+
+
+ Contexts can be copied:
+
+
+
+
+(new person 'JohnDoe) → JohnDoe
+
+(set 'JohnDoe:age 99)
+
+
+
+
+ Contexts can be referred to by a variable:
+
+
+
+
+(set 'human JohnDoe)
+
+human:age → 99
+
+(set 'human:address "1 Main Street")
+
+JohnDoe:address → "1 Main Street"
+
+
+
+
+
An evaluated context (no quote) can be given as an argument:
+
+ If an identifier with the same symbol already exists,
+ it is redefined to be a context.
+
+
+
+ Symbols within the current context
+ are referred to simply by their names,
+ as are built-in functions and special symbols
+ like nil and true.
+ Symbols outside the current context
+ are referenced by prefixing the symbol name
+ with the context name and a : (colon).
+ To quote a symbol in a different context,
+ prefix the context name with a ' (single quote).
+
+
+
+ Within a given context, symbols may be created
+ with the same name as built-in functions
+ or context symbols in MAIN.
+ This overwrites the symbols in MAIN
+ when they are prefixed with a context:
+
+ In the second syntax,
+ context is used to create dictionaries
+ for hash-like associative memory access:
+
+
+
+
+;; create a symbol and store data in it
+(context 'MyHash "John Doe" 123) → 123
+(context 'MyHash "@#$%^" "hello world") → "hello world"
+(context 'myHash 'xyz 999) → 999
+
+;; retrieve contents from symbol
+(context 'MyHash "john Doe") → 123
+(context 'MyHash "@#$%^") → "hello world"
+(context 'MyHash 'xyz) → 999
+MyHash:xyz → 999
+
+
+
+
+ The first three statements create a symbol
+ and store a value of any data type inside.
+ The first statement also creates
+ the hash context named MyHash.
+When a symbol is specified for the name, the name is taken
+from the symbol and creates a symbol with the same name
+in the context MyHash.
+
+
+
+ Hash symbols can contain spaces
+ or any other special characters
+ not typically allowed in newLISP symbols
+ being used as variable names.
+ This second syntax of context
+ only creates the new symbol
+ and returns the value contained in it.
+ It does not switch to the new namespace.
+
+
+
The following function definition can be used as a comfortable shorter
+method to handle dictionaries:
+
+ Use context to change and create namespaces
+ and to create hash symbols in contexts.
+
+
+
+
+
+
copy-file
+syntax: (copy-file str-from-namestr-to-name)
+
+
+ Copies a file from a path-file-name given in str-from-name
+ to a path-file-name given in str-to-name.
+ Returns true or nil,
+ depending on if the copy was successful or not.
+
Calculates the hyperbolic cosine of num-radians.
+The hyperbolic sine is defined mathematically as:
+(exp (x) + exp (-x)) / 2.
+An overflow to inf may occur
+if num-radians is too large.
+ Counts elements of list-1 in list-2
+ and returns a list of those counts.
+
+
+example:
+
+
+(count '(1 2 3) '(3 2 1 4 2 3 1 1 2 2)) → (3 4 2)
+(count '(z a) '(z d z b a z y a)) → (3 2)
+
+(set 'lst (explode (read-file "myFile.txt")))
+(set 'letter-counts (count (unique lst) lst))
+
+
+
+ The second example counts all occurrences
+ of different letters in myFile.txt.
+
+
+
+ The first list in count,
+ which specifies the items to be counted in the second list,
+ should be unique.
+ For items that are not unique,
+ only the first instance will carry a count;
+ all other instances will display 0 (zero).
+
+ Copies int-bytes of memory
+ from int-from-address
+ to int-to-address.
+ This function can be used for
+ direct memory writing/reading
+ or for hacking newLISP internals
+ (e.g., type bits in LISP cells,
+ or building functions with binary executable code on the fly).
+
+
+
+ Note that this function should only be used
+ when familiar with newLISP internals.
+ cpymem can crash the system
+ or make it unstable if used incorrectly.
+
+ The first example would remove
+ the protection bit in symbol sym.
+ The second example copies a string directly
+ into a string variable.
+
+
+
+ The following example creates a new function from scratch,
+ runs a piece of binary code, and adds up two numbers.
+ This assembly language snippet shows the x86 code
+ to add up two numbers and return the result:
+
+ The binary representation is attached
+ to a new function created in newLISP:
+
+
+
+
+;; set code
+(set 'bindata (pack "ccccccccccc"
+ 0x55 0x8B 0xEC 0x8B 0x45 0x08 0x03 0x45 0x0C 0x5D 0xC3))
+
+;; get function template
+(set 'foo print)
+
+;; change type to library import and OS calling conventions
+;(cpymem (pack "ld" 265) (first (dump foo)) 4) ; Win32 stdcall
+(cpymem (pack "ld" 264) (first (dump foo)) 4) ; Linux cdecl
+
+;; set code pointer
+(cpymem (pack "ld" (address bindata)) (+ (first (dump foo)) 12) 4)
+
+;; execute
+(foo 3 4) → 7
+
+
+
+
+ Use the dump function
+ to retrieve binary addresses
+ and the contents from newLISP cells.
+
+
+
+
+
+
crc32
+syntax: (crc32 str-data)
+
+
+ Calculates a running 32-bit CRC (Circular Redundancy Check) sum
+ from the buffer in str-data,
+ starting with a CRC of 0xffffffff for the first byte.
+ crc32 uses an algorithm published
+ by www.w3.org.
+
+ crc32 is often used to verify data integrity
+ in unsafe data transmissions.
+
+
+
+
+
+
crit-chi2
+
+syntax: (crit-chi2 num-probabilitynum-df)
+
+
+ Calculates the critical minimum Chi²
+ for a given confidence probability num-probability
+ and the degrees of freedom num-df
+ for testing the significance of a statistical null hypothesis.
+
+ Calculates the critical normal distributed Z value
+ of a given cumulated probability (num-probability)
+ for testing of statistical significance and confidence intervals.
+
+ Retrieves the contents of the last
+ read-line operation.
+ current-line's contents are also implicitly used
+ when write-line
+ is called without a string parameter.
+
+
+
+ The following source shows the typical code pattern
+ for creating a UNIX command-line filter:
+
+ This displays all comment lines starting with ;;
+ from a file given as a command-line argument
+ when invoking the script filter.
+
+
+
+
+
+
+
curry
+syntax: (curry funcexpr)
+
+
Transforms func from a function f(x, y) that takes two arguments into a function fx(y) that takes a single argument. curry works like a
+macro in that it does not evaluate its arguments. Instead, they are
+evaluated during the application of func.
+
+
+example:
+
+
+(set 'f (curry + 10)) → (lambda (_x) (+ 10 _x))
+
+(f 7) → 17
+
+(filter (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
+→ ((a 10) (a 3) (a 9))
+
+(clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
+→ ((b 5) (c 8))
+
+(map (curry list 'x) (sequence 1 5))
+→ ((x 1) (x 2) (x 3) (x 4) (x 5))
+
+
+
+
curry can be used on all functions taking two arguments.
+ The first syntax returns the local time zone's
+ current date and time as a string representation.
+
+
+
+ In the second syntax, date translates the number of seconds
+ in int-secs into its date/time string representation
+ for the local time zone.
+ The number in int-secs is usually retrieved from the system
+ using date-value.
+ Optionally, a time-zone offset (in minutes) can be specified
+ in int-offset, which is added
+ or subtracted before conversion of int-sec to a string.
+
+
+
+example:
+
+
+(date) → "Fri Oct 29 09:56:58 2004"
+
+(date (date-value)) → "Sat May 20 11:37:15 2006"
+(date (date-value) 300) → "Sat May 20 16:37:19 2006" ; 5 hours offset
+(date 0) → "Wed Dec 31 16:00:00 1969"
+
+
+
+
+ Note that on some Win32-compiled versions,
+ values resulting in dates earlier than
+ January 1, 1970, 00:00:00
+ return nil.
+ But the MinGW compiled version will also work
+ with values that result in dates up to 24 hours
+ prior to 1/1/1970, returning a date-time string for 12/31/1969.
+
+
+
+ The way the date and time are presented in a string
+ depends on the underlying operating system.
+
+
+
+ The second example would show 1-1-1970 0:0
+ when in the Greenwich time zone,
+ but it displays a time lag of 8 hours when
+ in Pacific Standard Time (PST).
+ date assumes the int-secs given are in
+ Coordinated Universal Time (UCT; formerly Greenwich Mean Time (GMT))
+ and converts it according to the local time-zone.
+
+
+
+ The third syntax makes the date string fully customizable
+ by using a format specified in str-format.
+ This allows the day and month names to be translated into
+ results appropriate for the current locale:
+
+
+example:
+
+
+(set-locale "german") → "de_DE"
+
+(date (date-value) 0 "%A %-d. %B %Y")
+→ "Montag 7. März 2005"
+; on Linux - suppresses the leading 0
+
+(set-locale "C") ; default POSIX
+
+(date (date-value) 0 "%A %B %d %Y")
+→ "Monday March 07 2005"
+
+(date (date-value) 0 "%a %#d %b %Y")
+→ "Mon 7 Mar 2005"
+; suppressing leading 0 on Win32 using #
+
+(set-locale "german")
+
+(date (date-value) 0 "%x")
+→ "07.03.2005" ; day month year
+
+(set-locale "C")
+
+(date (date-value) 0 "%x")
+
+→ "03/07/05" ; month day year
+
+
+
+
+ The following table summarizes all format specifiers available
+ on both Win32 and Linux/UNIX platforms.
+ More format options are available on Linux/UNIX.
+ For details, consult the documentation for the C function
+ strftime() in the individual platform's C library.
+
+
+
+
+
format
description
+
%a
abbreviated weekday name according to the current locale
+
+
%A
full weekday name according to the current locale
+
%b
abbreviated month name according to the current locale
+
%B
full month name according to the current locale
+
%c
preferred date and time representation for the current locale
+
%d
day of the month as a decimal number (range 01–31)
+
%H
hour as a decimal number using a 24-hour clock (range 00–23)
+
+
%I
hour as a decimal number using a 12-hour clock (range 01–12)
+
%j
day of the year as a decimal number (range 001–366)
+
%m
month as a decimal number (range 01–12)
+
%M
minute as a decimal number
+
%p
either 'am' or 'pm' according to the given time value or
+the corresponding strings for the current locale
+
%S
second as a decimal number 0–61 (60 and 61 to account
+for occasional leap seconds)
+
+
%U
week number of the current year as a decimal number,
+starting with the first Sunday as the first day of the first week
+
%w
day of the week as a decimal, Sunday being 0
+
%W
week number of the current year as a decimal number,
+starting with the first Monday as the first day of the first week
+
%x
preferred date representation for the current locale
+without the time
+
%X
preferred time representation for the current locale
+without the date
+
%y
year as a decimal number without a century (range 00–99)
+
+
%Y
year as a decimal number including the century
+
%z
time zone or name or abbreviation (same as %Z on Win32,
+different on Linux/UNIX)
+
%Z
time zone or name or abbreviation (same as %z on Win32,
+different on Linux/UNIX)
+
%%
a literal '%' character
+
+
+
+ Leading zeroes in the display of decimal numbers can be suppressed
+ using - (minus) on Linux/UNIX and # (number sign) on Win32.
+
+ In the first syntax, date-value returns the time
+ in seconds since 1970-1-1 00:00:00 for a given date and time.
+ The parameters for the hour, minutes, and seconds are optional.
+ The time is assumed to be Coordinated Universal Time (UCT),
+ not adjusted for the current time zone.
+
+
+
+ In the second syntax, date-value returns the time value
+ in seconds for the current time.
+
+ Calls trace and begins evaluating
+ the user-defined function in func.
+ debug is a shortcut for executing (trace true),
+ then entering the function to be debugged.
+
+
+example:
+
+
+;; instead of doing
+(trace true)
+(my-func a b c)
+(trace nil)
+
+;; use debug as a shortcut
+(debug (my-func a b c))
+
+ The number in sym is decremented by one
+ (or the optional number num) and returned.
+ dec performs mixed integer and floating point
+ arithmetic according to the rules outlined below.
+
+
+
+ If sym contains a float and num is absent,
+ the input argument is truncated to an integer.
+
+
+
+ Integer calculations (without num) resulting in numbers
+ greater than 9,223,372,036,854,775,807 wrap around to negative numbers.
+ Results smaller than -9,223,372,036,854,775,808 wrap around to positive numbers.
+
+
+
+ If num is supplied, dec
+ always returns the result as a floating point number
+ (even for integer arguments).
+
+ Defines the new function sym-name,
+ with optional parameters sym-param-1—.
+ define is equivalent to assigning
+ a lambda expression to sym-name.
+ When calling a defined function,
+ all arguments are evaluated and assigned
+ to the variables in sym-param-1—,
+ then the body-1— expressions are evaluated.
+ When a function is defined, the lambda expression
+ bound to sym-name is returned.
+
+
+
+ All parameters defined are optional.
+ When a user-defined function is called without arguments,
+ those parameters assume the value nil.
+If those parameters have a default value
+ specified in exp-default,
+ they assume that value.
+
+
+
+ The return value of define
+ is the assigned lambda expression.
+ When calling a user-defined function,
+ the return value is the last expression evaluated
+ in the function body.
+
+
+example:
+
+
+(define (area x y) (* x y)) → (lambda (x y) (* x y))
+(area 2 3) → 6
+
+
+
+
+ As an alternative, area could be defined
+ as a function without using define.
+
+
+
+
+(set 'area (lambda (x y) (* x y))
+
+
+
+
+ lambda or fn expressions may be used by themselves
+ as anonymous functions without being defined as a symbol:
+
+
+
+
+((lambda ( x y) (* x y)) 2 3) → 6
+((fn ( x y) (* x y)) 2 3) → 6
+
+ Expressions in exp-default
+ are evaluated in the function's
+ current environment.
+
+
+
+
+(define-macro (foo (a 10) (b (div a 2)))
+ (list a b))
+
+(foo) → (10 5)
+(foo 30) → (30 15)
+(foo 3 4) → (3 4)
+
+
+
+
+ The second version of define
+ works like the set function.
+
+
+example:
+
+
+(define x 123) → 123
+;; is equivalent to
+(set 'x 123) → 123
+
+(define area (lambda ( x y) (* x y)))
+;; is equivalent to
+(set 'area (lambda ( x y) (* x y)))
+;; is equivalent to
+(define (area x y) (* x y))
+
+
+
+
+ Trying to redefine a protected symbol will cause an error message.
+
+ Defines the new macro sym-name,
+ with optional arguments sym-param-1—.
+ define-macro is equivalent to assigning
+ a lambda-macro expression to a symbol.
+ When a macro-defined function is called,
+ arguments are assigned to the variables
+ in sym-param-1—,
+ without evaluating the arguments first.
+ Then the body expressions are evaluated.
+ When evaluating the define-macro function,
+ the lambda-macro expression is returned.
+
+
+
+example:
+
+
+;; use underscores on symbols
+(define-macro (my-setq _x _y) (set _x (eval _y)))
+→ (lambda-macro (_x _y) (set _x (eval _y)))
+
+(my-setq x 123) → 123
+
+
+
+
+ Macros in newLISP are similar to define functions,
+ but they do not evaluate their arguments.
+ New functions can be created to behave like built-in functions
+ that delay the evaluation of certain arguments.
+ Since macros can access the arguments inside a parameter list,
+ they can be used to create flow-control functions
+ like those already built into newLISP.
+
+
+ All parameters defined are optional.
+ When a macro is called without arguments,
+ those parameters assume the value nil.
+ If those parameters have a default value
+ specified in exp-default,
+ they assume that default value.
+
+ Expressions in exp-default are evaluated
+ in the function's current environment.
+
+
+
+
+(define-macro (foo (a 10) (b (div a 2)))
+ (list a b))
+
+(foo) → (10 5)
+(foo 30) → (30 15)
+(foo 3 4) → (3 4)
+
+
+
+
+ Note that in macros, the danger exists of passing a parameter
+ with the same variable name as used in the macro definition.
+ In this case, the macro internal variable would end up
+ receiving nil instead of the intended value:
+
+
+
+
+;; not a good definition!
+
+(define-macro (my-setq x y) (set x (eval y)))
+
+;; symbol name clash for x
+
+(my-setq x 123) → 123
+x → nil
+
+
+
+
+ There are several methods that can be used
+ to avoid this problem, known as variable capture,
+ and to write hygienic macros:
+
+
+
+
+ Prefix all macro variable names with an underscore character.
+ Using this or a similar convention,
+ the danger of symbol name clashes can be avoided.
+
+
+ Put the macro into its own lexically closed namespace context.
+ If the function has the same name as the context,
+ it can be called by using the context name alone.
+ A function with this characteristic is called a
+ default function.
+
+
+
+ Use args to access
+ arguments passed by the function.
+
+
+
+example:
+
+
+;; a macro as a lexically isolated function
+;; avoiding variable capture in passed parameters
+
+(context 'my-setq)
+
+(define-macro (my-setq:my-setq x y) (set x (eval y)))
+
+(context MAIN)
+
+(my-setq x 123) → 123 ; no symbol clash
+
+
+
+
+ The macro in the example is lexically isolated,
+ and no variable capture can occur.
+ Instead of the macro being called using (my-setq:my-setq …),
+ it can be called with just (my-setq …)
+ because it is a default function.
+
+
+
+ A third possibility is to refer to passed parameters
+ using args:
+
+
+example:
+
+
+;; avoid variable capture in macros using the args function
+
+(define-macro (my-setq) (set (args 0) (eval (args 1))))
+
+
+
+
+ The last example shows how letex can be combined with
+ define-macro to expand macro variables into an expression to be evaluated:
+
+example:
+
+
+(define-macro (dolist-while)
+ (letex (var (args 0 0)
+ lst (args 0 1)
+ cnd (args 0 2)
+ body (cons 'begin (1 (args))))
+ (let (res)
+ (catch (dolist (var lst)
+ (if (set 'res cnd) body (throw res)))))))
+
+> (dolist-while (x '(a b c d e f) (!= x 'd)) (println x))
+a
+b
+c
+nil
+>
+
+
+
+
+ dolist-while loops through a list
+ while the condition is true.
+ Note that a similar feature is already built into
+ dolist as a break condition
+ optional parameter.
+
+
+
+ Also, the expand function performs variable
+ expansion explicitly, without evaluating the expanded expression.
+
+
+
+
+
+
def-new
+syntax: (def-new sym-source [sym-target])
+
+
+ This function works similarly to new,
+ but it only creates a copy of one symbol
+ and its contents from the symbol in sym-source.
+ When sym-target is not given,
+ a symbol with the same name is created
+ in the current context.
+ All symbols referenced inside sym-source
+ will be translated into symbol references into the current context,
+ which must not be MAIN.
+
+ If an argument is present in sym-target,
+ the copy will be made into a symbol and context
+ as referenced by the symbol in sym-target.
+ In addition to allowing renaming of the function while copying,
+ this also enables the copy to be placed in a different context.
+ All symbol references will be translated into symbol references
+ of the target context.
+
+ The function def-new can be used to configure contexts
+ or context objects in a more granular fashion than is possible
+ with new, which copies a whole context.
+
+
+
+
+
+
default
+syntax: (default context)
+
+
Returns the default functor of a context. The default functor is the
+symbol which carries the same name as the context it belongs to:
+
+example:
+
+
+(set 'foo:foo '(a b c d e f))
+
+(set 'ctx foo)
+
+(default foo) → foo:foo
+(default ctx) → foo:foo
+
+(sort (eval (default ctx)) >)
+
+foo:foo → (f e d c b a)
+
+ Deletes a symbol, symbol, or a context in sym-context
+ with all contained symbols from newLISP's symbol table.
+ References to the symbol will be changed to nil.
+ When the expression in bool evaluates
+ to true or anything other than nil,
+ symbols are only deleted when they are not referenced.
+
+
+
+ Protected symbols of built-in functions and special symbols
+ like nil and true cannot be deleted.
+
+
+
+ delete returns true if the symbol was deleted,
+ else it returns nil.
+
+
+example:
+
+
+(set 'lst '(a b aVar c d))
+
+(delete 'aVar) ; aVar deleted, references marked nil
+
+lst → (a b nil c d)
+
+(set 'lst '(a b aVar c d))
+
+(delete 'aVar true)
+→ nil ; protect aVar if referenced
+
+lst → (a b aVar c d)
+
+(set 'foo:x 123)
+(set 'foo:y "hello")
+
+;; in contexts, the quote may be omitted
+(delete foo) → foo:x, foo:y deleted
+
+
+
+
In the last example only the symbols inside context foo
+will be deleted but not the context symbol foo itself. It
+will be converted to a normal unprotected symbol and contain nil.
+
+
+
+ Note that deleting a symbol that is part of a function
+ which is currently executing can crash the system
+ or have other unforeseen effects.
+
+
+
+
+
+
+
+
delete-file
+syntax: (delete-file str-file-name)
+
+
+ Deletes a file given in str-file-name.
+ Returns true or nil depending
+ on the outcome of the delete operation.
+
+The first example deletes the file junk in the current directory.
+The second example shows how to use a URL to specify the file.
+In this form, additional parameters can be given.
+See delete-url for details.
+
+
+
+
+
+
destroy
+syntax: (destroy int-pid)
+
+
Destroys a process with process id in int-pid and returns true
+on success or nil on failure. The process id is obtained from a previous
+call to fork on Mac OS X and other UNIX or process.
+on all platforms.
+
+ int is an I/O device number, which is 0 (zero)
+ for the default STD I/O console window.
+ int may also be a file handle
+ previously obtained using open.
+ When no argument is supplied,
+ the current I/O device number is returned.
+ The I/O channel specified by device
+ is used internally by the functions
+ print and read-line.
+ When the current I/O device is 0 (zero), print
+ sends output to the console window and read-line
+ accepts input from the keyboard.
+ If the current I/O device has been set by opening a file,
+ then print and read-line work on that file.
+
+ Note that using close on device
+ automatically resets device to 0 (zero).
+
+
+
+
+
+
delete-url
+syntax: (delete-file str-url)
+
+
This function deletes the file
+on a remote HTTP server
+specified in str-url.
+The HTTP DELETE protocol
+must be enabled on the target web server,
+or an error message string may be returned.
+The target file must also have
+access permissions set accordingly.
+Additional parameters such as timeout and custom headers
+are available exactly as in the
+get-url function.
+
+
This feature is also available when the delete-file
+function is used and a URL is specified for the filename.
The second example configures a timeout option of five seconds.
+Other options such as special HTTP protocol headers
+can be specified, as well.
+See the get-url function for details.
+ In the first syntax, difference returns
+ the set difference between list-A and list-B.
+ The resulting list only has elements occurring in list-A,
+ but not in list-B.
+ All elements in the resulting list are unique,
+ but list-A and list-B need not be unique.
+ Elements in the lists can be any type of LISP expression.
+
+ In the second syntax, difference works in list mode.
+ bool specifies true
+ or an expression not evaluating to nil.
+ In the resulting list, all elements of list-B
+ are eliminated in list-A,
+ but duplicates of other elements in list-A are left.
+
+ A list of directory entry names is returned
+ for the directory path given in str-path.
+ On failure, nil is returned.
+ When str-path is omitted,
+ the list of entries in the current directory is returned.
+
+
+example:
+
+
+(directory "/bin")
+
+(directory "c:/")
+
+
+
+
+ The first example returns the directory of /bin,
+ the second line returns a list of directory entries
+ in the root directory of drive C:.
+ Note that on Win32 systems,
+ a forward slash (/) can be included in path names.
+ When used, a backslash (\) must be
+ preceded by a second backslash.
+
+
+
+ In the second syntax, directory can take
+ a regular expression pattern in str-pattern.
+ Only filenames matching the pattern will be returned
+ in the list of directory entries.
+ In int-options, special regular expression options
+ can be specified; see regex for details.
+
+
+example:
+
+
+(directory "." "\\.c") → ("foo.c" "bar.c")
+;; or using braces as string pattern delimiters
+(directory "." {\.c}) → ("foo.c" "bar.c")
+
+; show only hidden files (starting with dot)
+(directory "." "^[.]") → ("." ".." ".profile" ".rnd" ".ssh")
+
+
+
+ The regular expression forces directory
+ to return only file names containing the string ".c".
+
+ Successively divides num-1
+ by the number in num-2—.
+ div can perform mixed-type arithmetic,
+ but it always returns floating point numbers.
+ Any floating point calculation
+ with NaN also returns NaN.
+
+ When num-1 is the only argument,
+ div calculates the inverse of num-1.
+
+
+
+
+
+
doargs
+syntax: (doargs (sym [exp-break]) body)
+
+
Iterates through all members of the argument list
+inside a user-defined function or macro. This function or macro can be defined using define,
+define-macro, lambda, or
+lambda-macro.
+The variable in sym
+is set sequentially to all members in the argument list
+until the list is exhausted
+or an optional break expression
+(defined in exp-break)
+evaluates to true or a logical true value.
+The doargs expression always returns
+the result of the last evaluation.
The optional break expression causes doargs
+to interrupt processing of the arguments:
+
+
+
+(define-macro (foo)
+ (doargs (i (= i 'x))
+ (println i)))
+
+> (foo a b c x e f g)
+a
+b
+c
+true
+
+
+
+
Use the args function
+to access the entire argument list at once.
+
+
+
+
+
dolist
+syntax: (dolist (sym list [exp-break]) body)
+
+
+ The expressions in body are evaluated
+ for each element in list.
+ The variable in sym is set to each of the elements
+ before evaluation of the body expressions.
+ The variable used as loop index is local
+ and behaves according to the rules of dynamic scoping.
+
+
+
+ Optionally, a condition for early loop exit
+ may be defined in exp-break.
+ If the break expression evaluates to any non-nil value,
+ the dolist loop returns with the value of exp-break.
+ The break condition is tested before evaluating body.
+
+example:
+
+
+(set 'x 123)
+(dolist (x '(a b c d e f g)) ; prints: abcdefg
+ (print x)) → g ; return value
+
+(dolist (x '(a b c d e f g) (= x 'e)) ; prints: abcd
+ (print x))
+
+;; x is local in dolist
+;; x has still its old value outside the loop
+
+x → 123 ; x has still its old value
+
+
+
+
+ This example prints abcdefg in the console window.
+ After the execution of dolist,
+ the value for x remains unchanged
+ because the x in dolist has local scope.
+ The return value of dolist is the result
+ of the last evaluated expression.
+
+
+
+ The internal system variable $idx
+ keeps track of the current offset
+ into the list passed to dolist,
+ and it can be accessed during its execution:
+
+
+
+
+(dolist (x '(a b d e f g))
+ (println $idx ":" x)) → g
+
+0:a
+1:b
+2:d
+3:e
+4:f
+5:g
+
+
+
+
+ The console output is shown in boldface.
+ $idx is protected and cannot be changed by the user.
+
+ The expressions in body are evaluated
+ for each character in string.
+ The variable in sym is set to each ASCII or UTF-8 integer value of the characters
+ before evaluation of the body expressions.
+ The variable used as loop index is local
+ and behaves according to the rules of dynamic scoping.
+
+
+
+ Optionally, a condition for early loop exit
+ may be defined in exp-break.
+ If the break expression evaluates to any non-nil value,
+ the dolist loop returns with the value of exp-break.
+ The break condition is tested before evaluating body.
+
+ This example prints prints the value of each character
+ in the console window. In UTF-8 enabled versions of newLISP
+ individual characters may be longer than one byte and the
+ number in the loop variable may exceed 255.
+ The return value of dostring is the result
+ of the last evaluated expression.
+
+
+
+ The internal system variable $idx
+ keeps track of the current offset
+ into the list passed to dostring,
+ and it can be accessed during its execution.
+
+ The expressions in body are evaluated int times.
+ The variable in sym is set from 0 (zero) to (int - 1)
+ each time before evaluating the body expression(s).
+ The variable used as the loop index is local to the dotimes
+ expression and behaves according the rules of dynamic scoping.
+ The loop index is of integer type.
+ dotimes returns the result of
+ the last expression evaluated in body.
+
+
+
+ Optionally, a condition for early loop exit
+ may be defined in exp-break.
+ If the break expression evaluates to any non-nil value,
+ the dotimes loop returns with the value of exp-break.
+ The break condition is tested before evaluating body.
+
+ The expressions in body are evaluated
+ for all symbols in sym-context.
+ The symbols are accessed in a sorted order.
+ Before each evaluation of the body expression(s),
+ the variable in sym is set
+ to the next symbol from sym-context.
+ The variable used as the loop index is local
+ to the dotree expression
+ and behaves according the rules of dynamic scoping.
+
+
+example:
+
+
+;; faster and less memory overhead
+(dotree (s 'SomeCTX) (print s " "))
+
+;; the quote can be omitted
+(dotree (s SomeCTX) (print s " "))
+
+;; slower and more memory usage
+(dolist (s (symbols 'SomeCTX)) (print s " "))
+
+
+
+
+ This example prints the names of all symbols inside SomeCTX to the console window.
+
+
+
+
+
+
+
do-until
+syntax: (do-until exp-condition body)
+
+
+ The expressions in body are evaluated
+ before exp-condition is evaluated.
+ If the evaluation of exp-condition is not nil,
+ then the do-until expression is finished;
+ otherwise, the expressions in body get evaluated again.
+ Note that do-until evaluates the conditional expression
+ after evaluating the body expressions,
+ whereas until checks the condition
+ before evaluating the body.
+ The return value of the do-until expression
+ is the last evaluation of the body expression.
+
+ The expressions in body are evaluated
+ before exp-condition is evaluated.
+ If the evaluation of exp-condition is nil,
+ then the do-while expression is finished;
+ otherwise the expressions in body get evaluated again.
+ Note that do-while evaluates the conditional expression
+ after evaluating the body expressions,
+ whereas while checks the condition
+ before evaluating the body.
+ The return value of the do-while expression
+ is the last evaluation of the body expression.
+
+ Shows the binary contents of a newLISP cell.
+ Without an argument, this function outputs
+ a listing of all LISP cells to the console.
+ When exp is given,
+ it is evaluated and the contents
+ of a LISP cell are returned in a list.
+
+ The list contains the following memory addresses and information:
+
+
+
+ (0) memory address of the LISP cell
+ (1) cell->type: mayor/minor type, see newlisp.h for details
+ (2) cell->next: linked list ptr
+ (3) cell->aux:
+ string length+1 or
+ low (little endian) or high (big endian) word of 64-bit integer or
+ low word of IEEE 754 double float
+ (4) cell->contents:
+ string/symbol address or
+ high (little endian) or low (big endian) word of 64-bit integer or
+ high word of IEEE 754 double float
+
+
+
+ This function is valuable for changing type bits in cells
+ or hacking other parts of newLISP internals.
+ See the function cpymem
+ for a comprehensive example.
+
+ If the expression in exp evaluates to a string,
+ it will be replicated int-n times within a string and returned.
+ When specifying an expression evaluating
+ to anything other than nil in bool,
+ the string will not be concatenated
+ but replicated in a list like any other data type.
+
+
+
+ If exp contains any data type other than string,
+ the returned list will contain int-n evaluations of exp.
+
+
+
Without the repetition parameter dup assumes 2.
+
+example:
+
+
+(dup "A" 6) → "AAAAAA"
+(dup "A" 6 true) → ("A" "A" "A" "A" "A" "A")
+(dup "A" 0) → ""
+(dup "AB" 5) → "ABABABABAB"
+(dup 9 7) → (9 9 9 9 9 9 9)
+(dup 9 0) → ()
+(dup 'x 8) → (x x x x x x x x)
+(dup '(1 2) 3) → ((1 2) (1 2) (1 2))
+(dup "\000" 4) → "\000\000\000\000"
+
+(dup "*") → "**"
+
+
+
+
+ The last example shows handling of binary information,
+ creating a string filled with four binary zeroes.
+
+ The first example checks a list,
+ while the second two examples check a string.
+
+
+
+
+
+
encrypt
+syntax: (encrypt str-sourcestr-pad)
+
+
+ Performs a one-time–pad encryption of str-source
+ using the encryption pad in str-pad.
+ The longer str-pad is
+ and the more random the bytes are,
+ the safer the encryption.
+ If the pad is as long as the source text,
+ is fully random, and is used only once,
+ then one-time–pad encryption
+ is virtually impossible to break,
+ since the encryption seems to contain only random data.
+ To retrieve the original,
+ the same function and pad
+ are applied again to the encrypted text:
+
+
+example:
+
+
+(set 'secret
+ (encrypt "A secret message" "my secret key"))
+→ ",YS\022\006\017\023\017TM\014\022\n\012\030E"
+
+(encrypt secret "my secret key") → "A secret message"
+
+ In the first syntax, ends-with tests
+ the string in str-data to see if it
+ ends with the string specified in str-key.
+ It returns true or nil
+ depending on the outcome.
+
+ When nil or any expression evaluating to nil
+ as a third parameter in bool is specified,
+ the comparison is case-insensitive.
+
+
+
+
If a regular expression option number is
+specified str-key contains a regular expression pattern. See
+regex for valid numbers for option.
+
+ In the second syntax,
+ the name of an environment variable
+ is given in var-str.
+ env returns the value
+ of the variable or nil
+ if the variable does not exist
+ in the environment.
+
+
+example:
+
+
+(env "PATH") → "/bin:/usr/bin:/usr/local/bin"
+
+
+
+
+The third syntax (variable name in var-str
+and value pair in value-str) sets or creates
+an environment variable. If value-str is the
+empty string "", then the variable is completely
+removed from the environment except when running on Solaris,
+wjere the variable stays with an empty string.
+
+ sym contains a user-defined function for handling errors.
+ Whenever an error occurs,
+ the system performs a reset
+ and executes the user-defined error handler.
+ The error handler can use the built-in function
+ error-number
+ to retrieve the number of the error.
+
+ newLISP passes all arguments by value.
+ Using a quoted symbol,
+ expressions can be passed
+ by reference through the symbol.
+ eval can be used
+ to access the original contents of the symbol:
+
+ Before being evaluated,
+ the result of str is compiled
+ into newLISP's internal format, and
+ the result of the evaluation is returned.
+ If the string contains more than one expression,
+ the result of the last evaluation is returned.
+
+
+
+ A second optional argument, expr,
+ can be passed that is evaluated
+ and returned in case of an error.
+ This permits programmatic control to be maintained
+ if the evaluation of str produces errors.
+ An optional third argument can be used to specify
+ the context in which the string should be parsed and evaluated.
+ When sym-context is specified,
+ the failure expression in expr
+ must be specified, as well.
+
+ The second example shows
+ a simple LISP interpreter eval loop.
+
+
+
+ Use the catch function
+ to catch errors resulting from the evaluation
+ of expressions, as opposed to strings.
+
+
+
+ The last example shows how to specify a target context for evaluation.
+ The symbols a and b now refer to the
+ values in context foo instead of MAIN.
+
+ In the first form,
+ exec launches a process described in str-process
+ and returns all standard output as an array of strings
+ (one for each line in stdout).
+ exec returns nil
+ if the process could not be launched.
+
+ The example starts a process and performs the shell command ls,
+ capturing the output in an array of strings.
+
+
+
+ In the second form,
+ exec creates a process pipe,
+ starts the process in str-process,
+ and receives from str-stdin
+ standard input for this process.
+ The return value is true
+ if the process was successfully launched;
+ otherwise it is nil.
+
+
+example:
+
+
+(exec "cgiProc" query)
+
+
+
+
+ In this example,
+ cgiProc could be a cgi processor (e.g., Perl or newLISP)
+ that receives and processes standard input supplied by a string
+ contained in the variable query.
+
+
+
+
+
+
exit
+syntax: (exit [int])
+
+
+ Exits newLISP.
+ An optional exit code, int, may be supplied.
+ This code can be tested by the host operating system.
+ When newLISP is run in daemon server mode
+ using -d as a command-line option,
+ only the network connection is closed,
+ while newLISP stays resident,
+ listening for a new connection.
+
+
+example:
+
+
+(exit 5)
+
+
+
+
+
+
+
exists
+
+syntax: (exists func-conditionlist)
+
+
Successively applies func-condition
+to the elements of list
+and returns the first element
+that meets the condition in func-condition.
+If no element meets the condition,
+nil is returned.
+ In the first syntax,
+ one symbol in sym
+ (or more in sym_2 through sym_n)
+ is looked up in a simple or nested list.
+ They are then expanded
+ to the current binding of the symbol,
+ and the expanded list is returned.
+ The original list remains unchanged.
+
+
+example:
+
+
+(set 'x 2 'a '(d e))
+(expand '(a x b) 'x) → (a 2 b)
+(expand '(a x (b c x)) 'x) → (a 2 (b c 2))
+(expand '(a x (b c x)) 'x 'a) → ((d e) 2 (b c 2))
+
+
+
+
+ expand is useful when composing lambda expressions
+ or doing variable expansion inside macros.
+
+ If more than one symbol is present,
+ expand will work in an incremental fashion:
+
+
+
+
+(set 'a '(b c))
+(set 'b 1)
+
+(expand '(a b c) 'a 'b) → ((1 c) 1 c)
+
+
+
+
+ Like the apply function,
+ expandreduces its argument list.
+
+
+
+syntax: (expand listlist-assoc)
+
+
+ The second syntax of expand allows
+ expansion bindings to be specified on the fly,
+ without performing a set
+ on the participating variables:
+
+
+example:
+
+
+(expand '(a b c) '((a 1) (b 2))) → (1 2 c)
+(expand '(a b c) '((a 1) (b 2) (c (x y z)))) → (1 2 (x y z))
+
+
+
+
+ Note that the contents of the variables
+ in the association list will not change.
+ This is different from the letex function,
+ where variables are set by evaluating
+ and assigning their association parts.
+
+
+
+ This form of expand is frequently used
+ in logic programming,
+ together with the unify function.
+
+
+
+syntax: (expand list)
+
+
+ A third syntax is used to expand only the contents
+ of variables starting with an uppercase character.
+ This PROLOG mode may also be used
+ in the context of logic programming.
+ As in the first syntax of expand,
+ symbols must be preset.
+ Only uppercase variables and those bound
+ to anything other than nil
+ will be expanded:
+
+
+
+example:
+
+
+(set 'A 1 'Bvar 2 'C nil 'd 5 'e 6)
+(expand '(A (Bvar) C d e f)) → (1 (2) C d e f)
+
+
+
+
+ Only the symbols A and Bvar are expanded,
+ since they have capitalized names
+ and non-nil contents.
+
+
+
+ The currying function in the example
+ demonstrating the first syntax of expand
+ can now be written even more simply
+ using an uppercase variable:
+
+In the first syntax,
+explode transforms the string (str)
+into a list of single-character strings.
+Optionally, a chunk size can be specified in int-chunk
+to break the string into multi-character chunks.
+When specifying a value for bool other than nil,
+the last chunk will be omitted
+if it does not have the full length specified
+in int-chunk.
+
+
+example:
+
+
+(explode "newLISP") → ("n" "e" "w" "L" "I" "S" "P")
+
+(join (explode "keep it together")) → "keep it together"
+
+(explode "newLISP" 2) → ("ne" "wL" "IS" "P")
+
+(explode "newLISP" 3) → ("new" "LIS" "P")
+
+; omit last chunk if too short
+(explode "newLISP" 3 true) → ("new" "LIS")
+
+
+ When called in UTF-8–enabled versions of newLISP,
+ explode will work on character boundaries
+ rather than byte boundaries.
+ In UTF-8–encoded strings,
+ characters may contain more than one byte.
+
+
+
+In the second syntax,
+explode explodes a list (list)
+into sublists of chunk size int-chunk,
+which is 1 (one) by default.
+
+
+
+The following shows an example of the last chunk being omitted
+when the value for bool is other than nil,
+and the chunk does not have the full length specified
+in int-chunk.
+
+
+example:
+
+
+(explode '(a b c d e f g h)) → ((a) (b) (c) (d) (e) (f) (g) (h))
+(explode '(a b c d e f g h) 2) → ((a b) (c d) (e f) (g))
+
+; omit last chunk if too short
+(explode '(a b c d e f g h) 2 true) → ((a b) (c d) (e f))
+
+(transpose (explode '(a b c d e f g h) 2))
+→ ((a c e g) (b d f h))
+
+
+
+
+The join and append functions
+are inverse operations of explode.
+
+
+
+
+
+
factor
+syntax: (factor int)
+
+
+ Factors the number in int
+ into its prime components.
+ Floating point numbers in num
+ are truncated to their integer part.
+
+
+example:
+
+
+(factor 123456789123456789) → (3 3 7 11 13 19 3607 3803 52579)
+
+;; check correctness of factoring
+(= (apply * (factor 123456789123456789)) 123456789123456789)
+→ true
+
+;; factor the biggest integer
+(factor 9223372036854775807) → (7 7 73 127 337 92737 649657)
+
+;; primes.lsp - return all primes in a list, up to n
+
+(define (primes n , p)
+ (dotimes (e n)
+ (if (= (length (factor e)) 1)
+ (push e p -1))) p)
+
+(primes 20) → (2 3 5 7 11 13 17 19)
+
+
+
+
+ factor returns nil
+ for numbers smaller than 2.
+ For numbers larger than 9,223,372,036,854,775,807
+ (the largest 64-bit integer)
+ converted from floating point numbers,
+ the largest integer is factored.
+
+
+
+
+
+
fft
+syntax: (fft list-num)
+
+
+ Calculates the discrete Fourier transform
+ on the list of complex numbers in list-num
+ using the FFT method (Fast Fourier Transform).
+ Each complex number is specified by its real part,
+ followed by its imaginary part.
+ If only real numbers are used,
+ the imaginary part is set to 0.0 (zero).
+ When the number of elements in list-num
+ is not a power of 2,
+ fft increases the number of elements
+ by padding the list with zeroes.
+ When the imaginary part of a complex number is 0,
+ simple numbers can be used instead.
+
+ The inverse operation of fft
+ is the ifft function.
+
+
+
+
+
+
file-info
+syntax: (file-info str_name)
+
+
+ Returns a list of information about
+ the file or directory in str_name.
+ newLISP uses the POSIX system call lstat()
+ to get the following information:
+
+ In the second example,
+ the last status change date
+ for the directory /etc
+ is retrieved.
+
+
+
file-info gives file statistics (size) for a linked file,
+not the link, except for the mode field.
+
+
+
+
+
file?
+
+syntax: (file? str-name)
+
+
+ Checks for the existence of
+ a file in str-name.
+ Returns true
+ if the file exists;
+ otherwise, it returns nil.
+ This function will also return
+ true for directories.
+ The existence of a file
+ does not imply anything about
+ its read or write permissions.
+ A file may exist while not having the permissions
+ to read from or write to it by the current user.
+
+ The predicate exp-predicate is applied
+ to each element of the list exp-list.
+ A list is returned containing the elements
+ for which exp-predicate is true.
+ filter works like clean,
+ but with a negated predicate.
+
+
+example:
+
+
+(filter symbol? '(1 2 d 4 f g 5 h)) → (d f g h)
+
+(define (big? x) (> x 5)) → (lambda (x) (> x 5))
+
+(filter big? '(1 10 3 6 4 5 11)) → (10 6 11)
+
+; filter with comparison functor
+
+(set 'L '((a 10 2 7) (b 5) (a 8 3) (c 8) (a 9)))
+
+(filter (curry match '(a *)) L) → ((a 10 2 7) (a 8 3) (a 9))
+
+(filter (curry match '(? ?)) L) → ((b 5) (c 8) (a 9))
+
+(filter (curry match '(* 8 *)) L) → ((a 8 3) (c 8))
+
+→ ((a 10) (a 3) (a 9))
+
+
+
+
+ The predicate may be a built-in predicate,
+ a user-defined function,
+ or a lambda expression.
+
+
+
+ For filtering a list of elements
+ with the elements from another list,
+ use the difference function or
+ intersect
+ (with the list option).
+
+
+
+ See also the related function index,
+ which returns the indices of the filtered elements
+ and clean,
+ which returns all elements of a list
+ for which a predicate is false.
+
+ If the second argument evaluates to a list,
+ then find returns the index position (offset)
+ of the element derived from evaluating exp-key.
+
+
+
+Optionally, an operator or user-defined function
+can be specified in func-compare.
+If exp-key is a string,
+a regular expression option
+can be specified with int-option instead.
+
+
When using regular expressions or comparison functors the system
+variable $0 is set to the last element found.
+
+example:
+
+
+; find an expression in a list
+(find '(1 2) '((1 4) 5 6 (1 2) (8 9))) → 3
+
+(find "world" '("hello" "world")) → 1
+(find "hi" '("hello" "world")) → nil
+
+(find "newlisp" '("Perl" "Python" "newLISP") 1) → 2
+
+; use the comparison functor
+(find 3 '(8 4 3 7 2 6) >) → 4
+$0 → 2
+
+(find "newlisp" '("Perl" "Python" "newLISP")
+ (fn (x y) (regex x y 1))) → 2
+$0 → "newLISP"
+
+(find 5 '((l 3) (k 5) (a 10) (z 22))
+ (fn (x y) (= x (last y)))) → 1
+$0 → (k 5)
+
+(find '(a ?) '((l 3) (k 5) (a 10) (z 22)) match) → 2
+$0 → (a 10)
+
+(find '(X X) '((a b) (c d) (e e) (f g)) unify) → 2
+$0 → (e e)
+
+; define the comparsion functor first for better readability
+(define (has-it-as-last x y) (= x (last y)))
+
+(find 22 '((l 3) (k 5) (a 10) (z 22)) has-it-as-last) → 3
+$0 → (z 22)
+
+
+
+
+Using match and unify,
+list searches can be formulated which are as powerful
+as regular expression searches are for strings.
+
+
+
+
+
Find a string in a string
+
+ If the second argument,
+ str-data,
+ evaluates to a string,
+ then the offset position
+ of the string str-key
+ (found in the first argument,
+ str-data)
+ is returned.
+ In this case,
+ find also works
+ on binary str-data.
+
+
+
+ The presence of a third parameter specifies a search
+ using the regular expression pattern specified in str-pattern,
+ as well as an option number specified in int-option
+ (i.e., 1 (one) for case-insensitive search or 0 (zero)
+ for no special options).
+
+
+
+ In newLISP, regular expressions are standard
+ Perl Compatible Regular Expression (PCRE) searches.
+ Found expressions or subexpressions are returned
+ in the system variables $0, $1, $2, etc.,
+ which can be used like any other symbol.
+ As an alternative,
+ the contents of these variables
+ can also be accessed
+ by using ($ 0), ($ 1), ($ 2), etc.
+ This method allows indexed access
+ (i.e., ($ i), where i is an integer).
+
+
+
+ See regex
+ for the meaning of the
+ option numbers and more information
+ on regular expression searching.
+
+
+example:
+
+
+; simple string search
+(find "world" "Hello world") → 6
+(find "WORLD" "Hello woRLd") → nil
+
+; case-insensitive regex
+
+(find "WorlD" "Hello woRLd" 1) → 6
+
+(find "hi" "hello world") → nil
+(find "Hello" "Hello world") → 0
+
+; regex with default options
+
+(find "cat|dog" "I have a cat" 0) → 9
+$0 → "cat"
+(find "cat|dog" "my dog" 0) → 3
+$0 → "dog"
+(find "cat|dog" "MY DOG" 1) → 3
+$0 → "DOG"
+
+;; find with subexpressions in regular expression
+;; and access with system variables
+
+(set 'str "http://nuevatec.com:80")
+
+(find "http://(.*):(.*)" str 0) → 0
+
+$0 → "http://nuevatec.com:80"
+$1 → "nuevatec.com"
+$2 → "80"
+
+;; system variables as an indexed expression (since 8.0.5)
+($ 0) → "http://nuevatec.com:80"
+($ 1) → "nuevatec.com"
+($ 2) → "80"
+
+ In the first syntax find-all Finds all occurrences of str-pattern
+ in the text str-text,
+ returning a list containing all matching strings.
+ The empty list () is returned
+ if no matches are found.
+
+
+
+ Optionally, an expression can be specified
+ to process the found string or regular subexpressions
+ before placing them into the returned list.
+ An additional option, int-option,
+ specifies special regular expression options
+ (see regex for further details).
+
+ The first example discovers all numbers in a text.
+ The second example shows how an optional expression in expr
+ can work on subexpressions found by the regular expression pattern
+ in str-pattern.
+ The last example retrieves a web page,
+ cleans out all HTML tags,
+ and then collects all words
+ into a unique and sorted list.
+
+
+
+ Note that find-all with strings
+ always performs a regular expression search,
+ even if the option in int-option
+ is omitted.
+
+
+
In the second syntax find-all searches for all list match
+patterns list-pattern in list-lists. As in find-all for
+strings an expression can be specified in expr to further process the matched
+sublist:
+
+example:
+
+
+(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4))) → ((b 2) (a 2))
+
+(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4)) (first $0)) → (b a)
+
+
+
+
find-all for list matches always uses match to compare when
+searching for sublists and always needs a list for the pattern expression.
+
+
In the third syntax find-all can speficy a built-in or user-defined
+function used for comparing list elements with the key expression in expr-keyM:
Any type of expression can be searched for or can be contained in the list. find-all
+in this syntax works similar to filter but with the added benefit of
+beeing able to define a processing expression for the found element.
+ Returns the first element of a list
+ or the first character of a string.
+ The operand is not changed.
+ This function is equivalent to car
+ or head in other LISP dialects.
+
+
+example:
+
+
+(first '(1 2 3 4 5)) → 1
+(first '((a b) c d)) → (a b)
+(set 'aList '(a b c d e)) → (a b c d e)
+(first aList) → a
+aList → (a b c d e)
+
+(set 'A (array 3 2 (sequence 1 6)))
+→ ((1 2) (3 4) (5 6))
+(first A) → (1 2)
+
+
+
+
+ In the second syntax,
+ the first character is returned
+ from the string in str
+ as a string.
+
+
+example:
+
+
+(first "newLISP") → "n"
+(first (rest "newLISP")) → "e"
+
+
+
+
+ Note that first works on character boundaries
+ rather than byte boundaries
+ when the UTF-8–enabled version of newLISP is used.
+ See also the functions last
+ and rest.
+
+
+
+
+
+
flat
+syntax: (flat list)
+
+
+ Returns the flattened form of a list:
+
+
+example:
+
+
+(set 'lst '(a (b (c d))))
+(flat lst) → (a b c d)
+
+(map (fn (x) (ref x lst)) (flat lst))
+→ ((0) (1 0) (1 1 0) (1 1 1))
+
+
+
+
+ flat can be used
+ to iterate through nested lists.
+
+
+
+
+
+
fn
+syntax: (fn (list-parameters) exp-body)
+
+
+ fn is used to define anonymous functions,
+ which are frequently used in map,
+ sort,
+ and anywhere functions can be used as a argument.
+
+
+
+ Using an anonymous function
+ eliminates the need to define
+ a new function with define.
+ Instead, a function is defined on the fly:
+
+ The example defines the function fn(x),
+ which takes an integer (x) and doubles it.
+ The function is mapped onto a list of arguments
+ using map.
+ The second example shows strings being sorted by length.
+
+
+
+ The lambda function
+ (the longer, traditional form)
+ can be used in place of fn.
+
+
+
+
+
+
float
+syntax: (float exp [exp-default] )
+
+
+ If the expression in exp
+ evaluates to a number or a string,
+ the argument is converted to a float
+ and returned.
+ If exp cannot be converted to a float
+ then nil or, if specified,
+ the evaluation of exp-default
+ will be returned.
+ This function is mostly used to convert strings
+ from user input or when reading and parsing text.
+ The string must start with a digit
+ or the + (plus sign), - (minus sign),
+ or . (period).
+ If str is invalid,
+ float returns nil
+ as a default value.
+
+
+
+ Floats with exponents larger than 1e308
+ or smaller than -1e308
+ are converted to +INF or -INF, respectively.
+ The display of +INF and -INF
+ differs on different platforms and compilers.
+
+ Converts number to a 32-bit float
+ represented by an integer.
+ This function is used when passing 32-bit floats
+ to library routines.
+ newLISP floating point numbers
+ are 64-bit and are passed as 64-bit floats
+ when calling imported C library routines.
+
+ Repeatedly evaluates the expressions in body
+ for a range of values specified
+ in num-from and num-to, inclusive.
+ A step size may be specified with num-step.
+ If no step size is specified, 1.0 is assumed.
+
+
+
+ Optionally, a condition for early loop exit
+ may be defined in exp-break.
+ If the break expression evaluates
+ to any non-nil value,
+ the for loop returns with
+ the value of exp-break.
+ The break condition is tested
+ before evaluating body. If a
+ break condition is defined num-step
+ must be defined too.
+
+
+
+ The symbol sym
+ is local in dynamic scope
+ to the for expression.
+ It takes on each value successively
+ in the specified range as an integer value
+ if no step size is specified, or
+ as a floating point value when a step size is
+ present.
+
+ The second example uses
+ a range of numbers
+ from highest to lowest.
+ Note that the step size
+ is always a positive number.
+ In the third example,
+ a break condition is tested.
+
+
+
+ Use the sequence function
+ to make a sequence of numbers.
+
+
+
+
+
+
for-all
+
+syntax: (for-all func-conditionlist)
+
+
Applies the function in func-condition
+to all elements in list.
+If all elements meet the condition in func-condition,
+the result is true;
+otherwise, nil is returned.
Use the exists function
+to check if at least one element in a list
+meets a condition.
+
+
+
+
+
fork
+
+syntax: (fork exp)
+
+
+ The expression in exp is launched
+ as a newLISP child process thread
+ of the platforms OS.
+ The new process inherits
+ the entire address space,
+ but runs independently,
+ so symbol or variable contents
+ changed in the child thread
+ will not affect the parent process
+ or vice versa.
+ The child process ends
+ when the evaluation of exp finishes.
+
+
+
+ On success, fork returns with the child process ID;
+ on failure, nil is returned.
+ See also the wait-pid function,
+ which waits for a child process to finish.
+
+
+
+ This function is only available
+ on Linux/UNIX versions of newLISP
+ and is based on the fork()
+ implementation of the underlying OS.
+ The example illustrates
+ how the child process thread
+ inherits the symbol space
+ and how it is independent of
+ the parent process.
+ The fork statement
+ returns immediately with
+ the process ID 176.
+ The child process increments
+ the variable x
+ by one each second and prints it
+ to standard out (boldface).
+ In the parent process,
+ commands can still be entered.
+ Type x to see that
+ the symbol x still
+ has the value 0 (zero)
+ in the parent process.
+ Although statements entered
+ will mix with the display
+ of the child process output,
+ they will be correctly input
+ to the parent process.
+
+
+
+ The second example illustrates
+ how pipe can be used
+ to communicate between threads.
+
+ Constructs a formatted string
+ from exp-data-1
+ using the format specified
+ in the evaluation of str-format.
+ The format specified is identical
+ to the format used for the printf()
+ function in the ANSI C language.
+ Two or more exp-data arguments
+ can be specified for more than one
+ format specifier in str-format.
+
+
+
+ In an alternative syntax,
+ the data to be formatted
+ can be passed inside a list
+ in list-data.
+
+
+
+ format checks for a valid format string,
+ matching data type, and the correct number of arguments.
+ Wrong formats or data types result in error messages.
+ int, float,
+ or string can be used
+ to ensure correct data types and to avoid error messages.
+
+
+
+ The format string has the following general format:
+
+
+
+
+
"%w.pf"
+
+
+
+ The % (percent sign)
+ starts a format specification.
+ To display a % inside a
+ format string, double it: %%
+
+
+ The w represents the width field.
+ Data is right-aligned,
+ except when preceded
+ by a minus sign,
+ in which case it is left-aligned.
+ When preceded by a zero,
+ the unused space is filled
+ with leading zeroes.
+ The width field is optional
+ and serves all data types.
+
+
+
+ The p represents the precision number
+ of decimals (floating point only)
+ or strings and is separated
+ from the width field by a period.
+ Precision is optional.
+ If preceded by a + (plus sign),
+ positive numbers are displayed with a +.
+ When using the precision field on strings,
+ the number of characters displayed
+ is limited to the number in p.
+
+
+
+ The f represents
+ a type flag and is essential;
+ it cannot be omitted.
+
+
+
+ Below are the types in f:
+
+
+
+
+s text string
+c character (value 1 - 255)
+d decimal (32-bit)
+u unsigned decimal (32-bit)
+x hexadecimal lowercase
+X hexadecimal uppercase
+o octal (32-bits) (not supported on all compilers)
+f floating point
+e scientific floating point
+E scientific floating point
+g general floating point
+
+
+
+
Formatting 64-bit numbers using 32-bit format specifiers will truncate and
+format the lower 32 bits of the number.
+
+
+
For 64-bit numbers (since version 8.9.7) use the following format
+strings on UNIX like operating systems:
+
+ If the format string requires it,
+ newLISP's format will
+ automatically convert integers
+ into floating points
+ or floating points into integers:
+
+ Calculates the future value of a loan
+ with constant payment num-pmt
+ and constant interest rate num-rate
+ after num-nper period of time and
+ a beginning principal value of num-pv.
+ If payment is at the end of the period,
+ int-type is 0 (zero); for payment
+ at the end of each period, int-type is 1.
+ If num-type is omitted, payment
+ at the end of each period is assumed.
+
+ The example illustrates
+ how a loan of $100,000
+ is paid down to a residual of $0.55
+ after 240 monthly payments
+ at a yearly interest rate of 7 percent.
+
+ Calculates the greatest common divisor
+ of a group of integers.
+ The greatest common divisor of two integers
+ that are not both zero
+ is the largest integer that divides both numbers.
+ gcd will calculate the greatest common divisor
+ for the first two integers in int-i
+ and then further reduce the argument list
+ by calculating the greatest common divisor of the result
+ and the next argument in the parameter list.
+
+ See
+ Wikipedia
+ for details and theory about gcd numbers in mathematics.
+
+
+
+
+
+
get-char
+syntax: (get-char int-address)
+
+
+ Gets a character from an address
+ specified in int-address.
+ This function is useful when using
+ imported shared library functions
+ with import.
+
+ Note that it is unsafe to use the get-char function
+ with an incorrect address in int-address. Doing so
+ could result in the system crashing or becoming unstable.
+
+ Gets a 64-bit double float from an address
+ specified in int-address.
+ This function is helpful when using
+ imported shared library functions (with import)
+ that return an address pointer to a double float
+ or a pointer to a structure containing double floats.
+
+ foo is imported and returns a pointer
+ to a double float when called.
+ Note that get-float is unsafe when used
+ with an incorrect address in int-address
+ and may result in the system crashing or becoming unstable.
+
+ Gets a 32-bit integer from
+ the address specified in int-address.
+ This function is handy when using
+ imported shared library functions with import,
+ a function returning an address pointer
+ to an integer, or a pointer to a structure containing integers.
+
+ Gets a 64-bit integer from
+ the address specified in int-address.
+ This function is handy when using import
+ to import shared library functions,
+ a function returning an address pointer to a long integer,
+ or a pointer to a structure containing long integers.
+
+
+example:
+
+
+long long int * foo(void)
+ {
+ int * result;
+ …
+ *result = 123;
+ return(result);
+ }
+
+long long int foo-b(void)
+ {
+ int result;
+ …
+ result = 456;
+ return(result);
+ }
+
+
+
+
+ Consider the C function foo (from a shared library),
+ which returns an integer pointer (address of an integer).
+
+ Gets a character string from the address
+ specified in int-address.
+ This function is helpful when
+ using imported shared library functions
+ with import.
+
+ When a string is passed as an argument,
+ get-string will take its address as the argument.
+ Because get-string always breaks off
+ at the first first \000 (null character) it encounters,
+ it can be used to retrieve a string from a buffer:
+
Reads a web page or file specified by the URL in str-url using
+the HTTP GET protocol. Both http:// and file://
+URLs are handled. "header" can be optionally specified
+to retrieve only the header. An option, "list",
+causes header and page information to be returned as separate strings in a list.
+
+
A "debug" option can be specified either alone or after the
+"header" or "list" option separated by one character,
+i.e. "header debug" or "list debug". This option
+outputs all outgoing information to the console window.
+
+
+ The optional argument int-timeout
+ can specify a value in milliseconds.
+ If no data is available from the host
+ after the specified timeout,
+ get-url returns the string ERR: timeout.
+ When other error conditions occur,
+ get-url returns a string starting with ERR:
+ and the description of the error.
+
+
+
get-url requests are also understood by newLISP server nodes.
+
+ The index page from the site specified
+ in str-url is returned as a string.
+ In the third line,
+ only the HTTP header
+ is returned in a string.
+ Lines 2 and 4 show a
+ timeout value being used.
+
+
+
The second example shows usage of a file:// URL
+to acces /home/db/data.txt on the local file system.
+
+
+ The third example illustrates
+ the use of a proxy server.
+ The proxy server's URL must be
+ in the operating system's environment.
+ As shown in the example,
+ this can be added using
+ the env
+ function.
+
+
+
+ The int-timeout can be followed
+ by an optional custom header in str-header:
+
+
+Custom header
+
+
The custom header may contain options
+ for browser cookies or other directives to the server.
+ When no str-header is specified,
+ newLISP sends certain header information by default.
+ After the following request:
+
+
+
+
+(get-url "http://somehost.com" 5000)
+
+
+
+
+ newLISP will configure and send
+ the request and header below:
+
+ Note that when using a custom header,
+ newLISP will only supply the GET request line,
+ as well as the Host: and Connection: header entries.
+ newLISP inserts all other entries supplied in the custom header
+ between the Host: and Connection: entries.
+ Each entry must end with a carriage return
+ line-feed pair: \r\n.
+
+
+
+
+ See an HTTP transactions reference
+ for valid header entries.
+
+
+
+ Custom headers can also be used
+ in the put-url
+ and post-url functions.
+
+
+
+
+
+
global
+
+syntax: (global sym-1 [sym-2 ...])
+
+
+ One or more symbols in sym-1 [sym-2 ...]
+ can be made globally accessible from contexts other than MAIN.
+ The statement has to be executed in the MAIN context,
+ and only symbols belonging to MAIN can be made global.
+ global returns the last symbol made global.
+
+ The second example shows how constant
+ and global can be combined into one statement,
+ protecting and making a previous function definition global.
+
+
+
+
+
+
+
global?
+
+syntax: (global? sym)
+
+
Checks if symbol in sym is global. Bult-in functions context
+symbols and all symbols made global using the function global
+are global:
+ If the value of exp-condition is not nil or an empty list,
+ the result of evaluating exp-1 is returned;
+ otherwise, the value of exp-2 is returned.
+ If exp-2 is absent, the value of
+ exp-condition is returned.
+
+ The second form of if works similarly
+ to cond, except it does not take
+ parentheses around the condition-body pair of expressions.
+ In this form, if can have
+ an unlimited number of arguments.
+
+ The last expression, "n/a", is optional.
+ When this option is omitted,
+ the evaluation of (>= x 30)
+ is returned, behaving exactly like a traditional
+ cond but without requiring
+ parentheses around the condition-expression pairs.
+
+
+
+ In any case, the whole if expression
+ always returns the last expression or condition evaluated.
+
+ Calculates the inverse discrete Fourier transform
+ on a list of complex numbers in list-num
+ using the FFT method (Fast Fourier Transform).
+ Each complex number is specified by its real part,
+ followed by its imaginary part.
+ In case only real numbers are used,
+ the imaginary part is set to 0.0 (zero).
+ When the number of elements in list-num
+ is not an integer power of 2,
+ ifft increases the number of elements
+ by padding the list with zeroes.
+ When complex numbers are 0 in the imaginary part,
+ simple numbers can be used.
+
+
+example:
+
+
+(ifft (fft '((1 0) (2 0) (3 0) (4 0))))
+→ ((1 0) (2 0) (3 0) (4 0))
+
+;; when imaginary part is 0, plain numbers work too
+
+(ifft (fft '(1 2 3 4)))
+→ ((1 0) (2 0) (3 0) (4 0))
+
+
+
+
+ The inverse operation of ifft
+ is the fft function.
+
+ Imports the function specified in str-function-name
+ from a shared library named in str-lib-name.
+ The functions address,
+ get-char,
+ get-int,
+ get-float,
+ get-string,
+ pack, and
+ unpack
+ can be used to retrieve return values
+ or to unpack data from returned structure addresses.
+ If the library is not located
+ in the normal library search path,
+ str-lib-name must contain
+ the full path name.
+
+
+
+ To transform newLISP data types into the data types
+ needed by the imported function, use the functions
+ float for 64-bit double floats,
+ flt for 32-bit floats,
+ and int for 32-bit integers.
+ By default, newLISP passes
+ floating point numbers
+ as 64-bit double floats,
+ integers as 32-bit integers,
+ and strings as 32-bit integers
+ for string addresses.
+
+
+example:
+
+
+;; import in Linux
+
+(import "libc.so.6" "printf") → printf <400862A0>
+
+;; import in Mac OS X
+
+(import "libc.dylib" "printf") → printf <90022080>
+
+;; import in CYGWIN
+
+(import "cygwin1.dll" "printf") → printf <6106B108>
+
+(printf "%g %s %d %c\n" 1.23 "hello" 999 65)
+1.23 hello 999 A
+→ 17 ; return value
+
+;; import Win32 DLLs in Win32 or CYGWIN version
+
+(import "kernel32.dll" "GetTickCount") → GetTickCount
+(import "user32.dll" "MessageBoxA") → MessageBoxA
+(GetTickCount) → 3328896
+
+
+
+
+
+ In the first example,
+ the string "1.23 hello 999 A"
+ is printed as a side effect,
+ and the value 17 (number of
+ characters printed) is returned.
+ Any C function can be imported
+ from any shared library in this way.
+
+
+
+ The message box example pops up
+ a Windows dialog box, which may be hidden
+ behind the console window.
+ The console prompt does not return until the
+ 'OK' button is pressed in the message box.
+
+
+
+
+;;this pops up a message box
+
+(MessageBoxA 0 "This is the body" "Caption" 1)
+
+
+
+
+
+ The other examples show several imports
+ of Win32 DLL functions and the details of passing values
+ by value or by reference.
+ Whenever strings or numbers are passed by reference,
+ space must be reserved beforehand.
+
+
+
+
+;; allocating space for a string return value
+
+(import "kernel32.dll" "GetWindowsDirectoryA")
+(set 'str (dup "\000" 64) ; reserve space and initialize
+
+(GetWindowsDirectoryA str (length str))
+
+str → "C:\\WINDOWS\000 "
+
+(slice str 0 (find "\000" str)) → "C:\\WINDOWS"
+
+;; or use trim
+(trim str) → "C:\\WINDOWS"
+
+;; passing an integer parameter by reference
+
+(import "kernel32.dll" "GetComputerNameA")
+
+(set 'str (dup "\000" 64) ; reserve space, initialize
+
+;; get size in a buffer lpNum
+(set 'lpNum (pack "lu" (length str)))
+
+;; call the function
+(GetComputerNameA str lpNum)
+
+str → "LUTZ-PC\000 "
+
+(slice str 0 (find "\000" str)) → "LUTZ-PC"
+
+;; or use trim
+(trim str) → "LUTZ-PC"
+
+
+
+
+ import returns the address of the function,
+ which can be used to assign a different name
+ to the imported function.
+
+ Note that the Win32 version of newLISP
+ uses standard call stdcall conventions
+ to call DLL library routines.
+ This is necessary for calling DLLs that belong
+ to the Win32 operating system (e.g., odbc32.dll).
+ Most third-party DLLs are compiled for
+ C declaration cdecl calling conventions
+ and may need to specify the string "cdecl"
+ as an additional last argument when importing functions.
+ newLISP compiled for Linux and other UNIX systems
+ uses the cdecl calling conventions by default
+ and ignores any additional string.
+
+
+
+
+;; force cdecl calling conventions on Win32
+(import "sqlite.dll" "sqlite_open" "cdecl") → sqlite_open <673D4888>
+
+
+
+
+
+ Imported functions may take up to fourteen arguments.
+ Note that floating point arguments
+ take up two spaces each
+ (e.g., passing five floats takes up
+ ten of the fourteen parameters).
+
+
+
+
+
+
+
inc
+syntax: (inc sym [num])
+
+
+ Increments the number in sym by 1
+ or by the optional number num
+ and returns the result.
+ inc performs mixed int
+ and float arithmetic according
+ to the rules outlined below.
+
+
+
+ If num is absent,
+ inc always returns
+ an integer in sym.
+ If the input arguments are floats and num is absent,
+ the input arguments are truncated to integers.
+
+
+
+ Integer calculations (without num)
+ resulting in numbers greater than
+ 9,223,372,036,854,775,807 wrap around to negative numbers.
+ Results smaller than -9,223,372,036,854,775,808
+ wrap around to positive numbers.
+
+
+
+ If num is supplied,
+ inc always returns
+ the result as floating point,
+ even for integer input arguments.
+
+ Applies the predicate exp-predicate
+ to each element of the list exp-list
+ and returns a list containing the indices of the elements
+ for which exp-predicate is true.
+
+
+example:
+
+
+(index symbol? '(1 2 d 4 f g 5 h)) → (2 4 5 7)
+
+(define (big? x) (> x 5)) → (lambda (x) (> x 5))
+
+(index big? '(1 10 3 6 4 5 11)) → (1 3 6)
+
+
+
+
+ The predicate may be a built-in predicate,
+ a user-defined function, or a lambda expression.
+
+
+
+ Use the filter function
+ to return the elements themselves.
+
+
+
+
+
+
int
+
+syntax: (int exp [exp-default] [int-base])
+
+
+ If the expression in exp evaluates to a number or a string,
+ the result is converted to an integer and returned.
+ If exp cannot be converted to an integer,
+ then nil or the evaluation of
+ exp-default will be returned.
+ This function is mostly used when translating strings
+ from user input or from parsing text.
+ If exp evaluates to a string,
+ the string must start with a digit; one or more spaces;
+ or the + or - sign.
+ The string must begin with '0x'
+ for hexadecimal strings or
+ '0' (zero) for octal strings.
+ If str is invalid,
+ int returns nil
+ as a default value if not otherwise specified.
+
+
+
+ A second optional parameter
+ can be used to force the number base
+ of conversion to a specific value.
+
+
+
+ Integers larger than 9,223,372,036,854,775,807
+ are truncated to 9,223,372,036,854,775,807.
+ Integers smaller than -9,223,372,036,854,775,808
+ are truncated to -9,223,372,036,854,775,808.
+
+
+
+ When converting from a float
+ (as in the second form of int),
+ floating point values larger or smaller
+ than the integer maximum or minimum
+ are also truncated.
+ A floating point expression evaluating to NaN
+ is converted to 0 (zero).
+
+ In the second syntax,
+ intersect returns a list of all elements
+ in list-A that are also in list-B,
+ without eliminating duplicates in list-A.
+ bool is an expression evaluating to true
+ or any other value not nil.
+
+ Returns the inversion of a
+ two-dimensional matrix in matrix.
+ The matrix must be square, with the same number
+ of rows and columns, and non-singular (invertible).
+ Matrix inversion can be used
+ to solve systems of linear equations
+ (e.g., multiple regression in statistics).
+ newLISP uses LU-decomposition of
+ the matrix to find the inverse.
+
+
+
+ The dimensions of a matrix
+ are defined by the number of rows
+ times the number of elements
+ in the first row.
+ For missing elements in non-rectangular matrices,
+ 0.0 (zero) is assumed.
+ A matrix can either be a nested list
+ or an array.
+
+
+
+ invert will return nil
+ if the matrix is singular and cannot be inverted.
+
+ Calculate the internal rate of return
+ of a cash flow per time period.
+ The internal rate of return is the interest rate
+ that makes the present value of a cash flow equal to 0.0 (zero).
+ In-flowing (negative values) and out-flowing (positive values)
+ amounts are specified in list-amounts.
+ If no time periods are specified in list-times,
+ amounts in list-amounts correspond to
+ consecutive time periods increasing by 1 (1, 2, 3—).
+ The algorithm used is iterative,
+ with an initial guess of 0.5 (50 percent).
+ Optionally, a different
+ initial guess can be specified.
+ The algorithm returns when a precision
+ of 0.000001 (0.0001 percent) is reached.
+ nil is returned if the algorithm
+ cannot converge after 50 iterations.
+
+
+
+ irr is often used to decide
+ between different types of investments.
+
+ If an initial investment of 1,000
+ yields 500 after the first year,
+ 400 after two years, and so on,
+ finally reaching 0.0 (zero) after five years,
+ then that corresponds to a yearly return
+ of about 20.2 percent.
+ The next line demonstrates the relation
+ between irr and npv.
+ Only 9.9 percent returns are necessary when making
+ the first withdrawal after three years.
+
+
+
+ In the last example, securities
+ were initially purchased for 5,000,
+ then for another 2,000 three months later.
+ After a year, securities for 5,000 are sold.
+ Selling the remaining securities
+ after 18 months renders 6,000.
+ The internal rate of return is 3.2 percent per month,
+ or about 57 percent in 18 months.
+
+
+
+ See also the fv,
+ nper,
+ npv,
+ pmt,
+ and pv functions.
+
+ Concatenates the given
+ list of strings
+ in list-of-strings.
+ If str-joint is present,
+ it is inserted between each string in the join.
+ If bool-trail-joint is true
+ then a joint string is also appended to the last string.
+
In the second version the last character in the string str is returned as a
+string.
+
+
+example:
+
+
+(last "newLISP") → "P"
+
+
+
+
+Note that last works on character boundaries
+rather than byte boundaries
+when the UTF-8–enabled version of newLISP is used.
+See also first, rest and nth.
+
+
+
+
+
+
legal?
+syntax: (legal? str)
+
+
+The token in str is verified as a legal newLISP symbol.
+Non legal symbols can be created using the sym function
+(e.g. symbols containing spaces, quotes, or other characters not normally allowed).
+Non legal symbols are created frequently
+when using them for associative data access:
+
The example shows that the string "one two" does not contain a legal
+symbol although a symbol can be created from this string and treated like a
+variable.
+
+
+
+
+
+
length
+syntax: (length expr)
+
+
Returns the number of elements in a list, the number of rows in
+an array or the number of characters in a string.
+
+
+
length applied to a symbol returns the length of the symbol name.
+Applied to a number, length returns the number of
+bytes needed in memory to store that number: 4 for integers and 8 for floating point numbers.
+
+
+example:
+
+
+(length '(a b (c d) e)) → 4
+(length '()) → 0
+(set 'someList '(q w e r t y)) → (q w e r t y)
+(length someList) → 6
+
+(set 'ary (array 2 4 '(0))) → ((1 2 3 4) (5 6 7 8))
+(length ary) → 2
+
+(length "Hello World") → 11
+(length "") → 0
+
+(length 'someVar) → 7
+(length 123) → 8
+(length 1.23) → 8
+
One or more variables sym1, sym2, ... are declared locally and
+initialized with expressions in exp-init1, exp-init2, etc.
+When the local variables are initialized the initializer expressions evaluate
+using symbol bindings as before the let statement. To incrementally use
+symbol bindings as evaluated during the initialization of locals in let,
+use letn.
+One or more expressions in exp-body are evaluated using the local
+definitions of sym1, sym2 etc. let is useful for
+breaking up complex expressions by defining local variables close to the
+place where they are used. The second form omits the parenthesis around the
+variable expression pairs but functions identical.
+
+
+example:
+
+
+(define (sum-sq a b)
+(let ((x (* a a)) (y (* b b)))
+(+ x y)))
+
+(sum-sq 3 4) → 25
+
+(define (sum-sq a b) ; alternative syntax
+(let (x (* a a) y (* b b))
+(+ x y)))
+
+
+
+
The variables x and y are initialized, then the expression
+
+(+ x y) is evaluated. The let form is just an optimized version and syntactic
+convenience for writing:
+
This functions combines let and expand to
+expand local variables into an expression before evaluating it.
+
+
+
Both forms provide the same functionality, but in the second form the parentheses around the initializers can be omitted.
+
+
+example:
+
+
+(letex '(x 1 y 2 z 3) '(x y z)) → (1 2 3)
+
+
+
+
Before the expression '(x y z) gets evaluated, x, y and z
+
+are literally replaced with the initializers from the letex initializer list.
+The final expression which gets evaluated is '(1 2 3).
+
+
+
The following is a more complex realistic example. letex and
+define-macro are used together to define a dolist-while,
+which loops through a list while certain condition is true:
+
+
+example:
+
+
+(define-macro (dolist-while)
+(letex (var (args 0 0)
+lst (args 0 1)
+cnd (args 0 2)
+body (cons 'begin (1 (args))))
+(let (res)
+(catch (dolist (var lst)
+(if (set 'res cnd) body (throw res)))))))
+
+> (dolist-while (x '(a b c d e f) (!= x 'd)) (println x))
+a
+b
+c
+nil
+>
+
+
+
+
The args function is used to access the unevaluated argument list from
+define-macro.
+
letn is like a nested let and works similar to let, but will
+incrementally use the new symbol bindings when evaluating the initializer expressions as
+if several let were nested. The following comparison
+of let and letn show the difference:
+
+
+example:
+
+
+(set 'x 10)
+(let ((x 1) (y (+ x 1)))
+(list x y)) → (1 11)
+
+(letn ((x 1) (y (+ x 1)))
+(list x y)) → (1 2)
+
+
+
+
While in the first example using let the variable y is
+calculated using the binding of x before the let expression,
+in the second example using letn the variable y is calculated using
+the new local binding of x.
+
+
+
+
+(letn (x 1 y x)
+(+ x y)) → 2
+
+;; same as nested let's
+
+(let (x 1)
+(let (y x)
+(+ x y))) → 2
+
+
+
+
letn works like several nestedlet. The parenthesis
+around the initializer expressions can be omitted.
+
+
+
+
+
+
list
+syntax: (list exp-1 [exp-2 ... ])
+
+
The exp are evaluated and the values used to construct a new list.
+
+
+example:
+
+
+(list 1 2 3 4 5) → (1 2 3 4 5)
+(list 'a '(b c) (+ 3 4) '() '*) → (a (b c) 7 () *)
+
+
+
+
See also cons and push for other
+forms of building lists.
+
+
+
+
+
+
list?
+syntax: (list? exp)
+
+
Returns true only if the value of exp is a list; otherwise
+returns nil. Note that lambda and lambda-macro
+expressions are also recognized as special instances of a list expression.
+
Loads and translates newLISP from a source file specified in one or more str-file-name
+and evaluates the expressions contained in the file(s). When loading is successful
+load returns the result of the last expression in the last file evaluated. If a file
+cannot be loaded load throws an error.
+
+
+
+An optional sym-context can be specified,
+which becomes the context of evaluation,
+unless such a context switch is already present
+in the file being loaded.
+By default,
+files which do not contain context switches
+will be loaded into the MAIN context.
+
+
+
The str-file-name specs can contain URLs. Both http:// and file://
+URLs are supported.
+
In case expressions evaluated during the load are changing the
+context, this will not influence the programming
+module doing the load. The current context
+after the load statement will always be the same as before in the
+load.
+
+
+
Normal file specs and URLs can be mixed in the same load command.
+
+
+
load with HTTP URLs can also be used to load code
+remotely from newLISP server nodes running on UNIX like operating system.
+In this mode, load will issue
+an HTTP GET request to the target URL. Note that a double backslash is required
+when path names are specified relative to the root directory. load
+in HTTP mode will observe a 60-second timeout.
+
+
+
The second to last line causes the files to be loaded in to the context MyCTX.
+The quote forces the context to be created if it did not exist.
+
+
+
The file:// URL is followed by a third / for the directory spec.
+
+
+
+
+
+
local
+syntax: (local (sym-1 [sym-2 ...]) body)
+
+
+Initializes one or more symbols
+in sym-1— to nil,
+evaluates the expressions in body,
+and returns the result of the last evaluation.
+
+
+
+local works similarly to let,
+but local variables are all initialized to nil.
+
+
+
+local provides a simple way
+to localize variables
+without explicit initialization.
+
In the first syntax the expression in num is evaluated and the natural
+logarithmic function is calculated from the result.
+
+
+example:
+
+
+(log 1) → 0
+(log (exp 1)) → 1
+
+
+
+
In the second syntax an arbitrary base can be specified in num-base.
+
+
+example:
+
+
+(log 1024 2) → 10
+(log (exp 1) (exp 1)) → 1
+
+
+
+
See also exp, which is the inverse function to log with
+base e.
+
+
+
+
+
+
lookup
+syntax: (lookup expassoc-list [int-index])
+
+
Finds in assoc-list an association the key element of which
+has the same value as exp and returns the int-index element of
+
+association (or the last element if int-index is absent).
+See also Indexing elements of strings and lists.
+
+
+
lookup is similar to assoc but goes one step further
+by extracting specific element found in the list.
+
+After newlisp 1 2 3 is executed at the command prompt,
+main-args returns a list containing the name of
+the invoking program and three command-line arguments.
+
+
+
+Optionally, main-args can take
+an int-index for indexing into the list.
+Note that an index out of range will cause nil
+to be returned, not the last elements of the list like
+in list-indexing.
+
+
+
+
+newlisp a b c
+
+> (main-args 0)
+"/usr/bin/newlisp"
+> (main-args -1)
+"c"
+> (main-args 2)
+"b"
+> (main-args 10)
+nil
+
+
+
+
+Note that when newLISP is executed from a script,
+main-args also returns the name
+of the script as the second argument:
+
+
+
+
+#!/usr/bin/newlisp
+#
+# script to show the effect of 'main-args' in script file
+
+(print (main-args) "\n")
+(exit)
+
+# end of script file
+
+;; execute script in the OS shell:
+
+script 1 2 3
+
+("/usr/bin/newlisp" "./script" "1" "2" "3")
+
+
+
+
+Try executing this script with different
+command-line parameters.
+
+
+
+
+
+
make-dir
+syntax: (make-dir str-dir-name [int-mode])
+
+
+Creates a directory as specified in str-dir-name,
+with the optional access mode int-mode.
+Returns true or nil
+depending on the outcome.
+If no access mode is specified,
+most UNIX systems default to drwxr-xr-x.
+
+
+
+On UNIX systems, the access mode specified
+will also be masked by the OS's user-mask
+set by the system administrator.
+The user-mask can be retrieved
+on UNIX systems using the command umask
+and is usually 0022 (octal),
+which masks write (and creation) permission
+for non-owners of the file.
+
+
+example:
+
+
+;; 0 (zero) in front of 750 makes it an octal number
+
+(make-dir "adir" 0750)
+
+
+
+
+This example creates a directory named adir
+in the current directory with an access mode of
+0750 (octal 750 = drwxr-x---).
+
+Successively applies the primitive function,
+defined function, or lambda expression
+exp-functor to the arguments specified in
+list-args-1, list-args-2—,
+returning all results in a list.
+Note that the quote before the operand can be omitted,
+since primitives evaluate to themselves in newLISP.
+
+
+
+By incorporating map
+into the function definition,
+we can do the following:
+
+
+
+
+(define (list-map op p lst)
+(map (lambda (x) (op p x)) lst))
+
+(list-map + 2 '(1 2 3 4)) → (3 4 5 6)
+
+(list-map mul 1.5 '(1 2 3 4)) → (1.5 3 4.5 6)
+
+
+
+
+The number of arguments used is determined
+by the length of the first argument list.
+Arguments missing in other argument lists
+cause an error message.
+If an argument list contains too many elements,
+the extra ones will be ignored.
+
+
+
+Note that only functions with applicative
+order of evaluation can be mapped.
+Functions with conditional or delayed evaluation
+of their arguments (e.g., if
+or case) cannot be mapped.
+
Using the first syntax,
+this function performs fast floating point
+scalar operations on two-dimensional matrices
+in matrix-A or matrix-B.
+The type of operation is specified
+by one of the four arithmetic operators
++, -, *, or /.
+This type of arithmetic operator is typically used for integer
+operations in newLISP. In the case of mat, however,
+all operations will be performed as floating point operations
+(add, sub, mul, div).
+
+
Matrices in newLISP are two-dimensional lists or arrays.
+Internally, newLISP translates lists and arrays into fast, accessible
+C-language data objects.
+This makes matrix operations in newLISP
+as fast as those coded directly in C.
+The same is true for the matrix operations
+multiply and invert.
+
+example:
+
+
+(set 'A '((1 2 3) (4 5 6)))
+(set 'B A)
+
+(mat + A B) → ((2 4 6) (8 10 12))
+(mat - A B) → ((0 0 0) (0 0 0))
+(mat * A B) → ((1 4 9) (16 25 36))
+(mat / A B) → ((1 1 1) (1 1 1))
+
+; specify the operator in a variable
+
+(set 'op +)
+(mat op A B) → ((2 4 6) (8 10 12))
+
+
+
+
Using the second syntax,
+all cells in matrix-A
+are multiplied with a scalar
+in number:
+The pattern in list-pattern is matched
+against the list in list-match,
+and the matching expressions are returned in a list.
+The three wildcard characters ?, +,
+and * can be used in list-pattern.
+
+
+
+Wildcard characters may be nested.
+match returns a
+list of matched expressions.
+For each ? (question mark),
+a matching expression element is returned.
+For each + (plus sign) or
+* (asterisk), a list containing
+the matched elements is returned.
+If the pattern cannot be matched
+against the list in list-match,
+match returns nil.
+If no wildcard characters are present
+in the pattern an empty list is returned.
+
+
+
+Optionally, the boolean value true
+(or any other expression not evaluating to nil)
+can be supplied as a third argument.
+This causes match work as it did in
+versions prior to 8.2.3, showing all list
+elements in the returned result.
+
+
+
+match is frequently employed as a functor parameter
+in find, ref,
+ref-all and replace and
+is internally used by find-all for lists.
+
+
+example:
+
+
+(match '(a ? c) '(a b c)) → (b)
+
+(match '(a ? ?) '(a b c)) → (b c)
+
+(match '(a ? c) '(a (x y z) c)) → ((x y z))
+
+(match '(a ? c) '(a x y z c)) → nil
+
+
+(match '(a * c) '(a x y z c)) → ((x y z))
+
+(match '(a (b c ?) x y z) '(a (b c d) x y z)) → (d)
+
+(match '(a (*) x ? z) '(a (b c d) x y z)) → ((b c d) y)
+
+(match '(+) '()) → nil
+
+(match '(+) '(a)) → ((a))
+
+(match '(+) '(a b)) → ((a b))
+
+(match '(a (*) x ? z) '(a () x y z)) → (() y)
+(match '(a (+) x ? z) '(a () x y z)) → nil
+
+
+
+
+Note that the * operator tries to grab
+the fewest number of elements possible,
+but match backtracks and grabs more elements
+if a match cannot be found.
+
+
+
+The + operator works similarly
+to the * operator,
+but it requires at least one list element.
+
+
+
+The following example shows
+how the matched expressions
+can be bound to variables.
+
+
+
+
+(map set '(x y) (match '(a (? c) d *) '(a (b c) d e f)))
+
+x → b
+y → (e f)
+
+
+
+
+Note that match for strings has been eliminated.
+For more powerful string matching, use regex,
+find, find-all
+or parse.
+
+
+
unify is another function for matching
+expressions in a PROLOG like manner.
+
+
+
+
+
max
+syntax: (max num-1 [num-2 ... ])
+
+
+Evaluates the expressions num-1—
+and returns the largest number.
+
+In the first syntax,
+member searches
+for the element exp
+in the list list.
+If the element is a member of the list,
+a new list starting with the element found
+and the rest of the original list
+is constructed and returned.
+If nothing is found,
+nil is returned.
+When specifying num-option
+member performs a regular expression search.
+
+
+example:
+
+
+(set 'aList '(a b c d e f g h)) → (a b c d e f g h)
+(member 'd aList) → (d e f g h)
+(member 55 aList) → nil
+
+
+
+
+In the second syntax,
+member searches
+for str-key in str.
+If str-key is found, all of str
+(starting with str-key) is returned.
+nil is returned if nothing is found.
+
+Calculates the modular value of the
+numbers in num-1 and num-2.
+mod computes the remainder
+from the division of the numerator num-i
+by the denominator num-i + 1.
+Specifically, the return value is
+numerator - n * denominator,
+where n is the quotient
+of the numerator divided by the denominator,
+rounded towards zero to an integer.
+The result has the same sign as
+the numerator and its magnitude
+is less than the magnitude
+of the denominator.
+
+
+example:
+
+
+(mod 10.5 3.3) → 0.6
+(mod -10.5 3.3) → -0.6
+
+
+
+
+Use the % (percent sign)
+function when working with integers only.
+
+
+
+
+
+
mul
+syntax: (mul num-1num-2 [num-3 ... ])
+
+
+Evaluates all expressions num-1—,
+calculating and returning the product.
+mul can perform mixed-type arithmetic,
+but it always returns floating point numbers.
+Any floating point calculation with
+NaN also returns NaN.
+
+Returns the matrix multiplication of matrices
+in matrix-A and matrix-B.
+If matrix-A has the dimensions n by m
+and matrix-B the dimensions k by l
+(m and k must be equal),
+the result is an n by l matrix.
+ multiply can perform mixed-type arithmetic,
+but the results are always double precision floating points,
+even if all input values are integers.
+
+
+
+The dimensions of a matrix are determined
+by the number of rows and the number
+of elements in the first row.
+For missing elements
+in non-rectangular matrices,
+0.0 is assumed.
+A matrix can either be a nested list
+or array.
+
+
+example:
+
+
+(set 'A '((1 2 3) (4 5 6)))
+(set 'B '((1 2) (1 2) (1 2)))
+(multiply A B) → ((6 12) (15 30))
+
+
+
+
+All operations shown here on lists
+can be performed on arrays, as well.
+
+syntax: (name symbol [bool])
+syntax: (name context)
+
+
+Returns as a string, the name of a symbol
+without the context prefix.
+If the expression in bool
+evaluates to anything other than nil,
+the name of the symbol's context is returned instead.
+
+
+
+When context is supplied,
+then name returns the name of the context.
+
+Tests if the result of a
+floating point math operation
+is a NaN.
+Certain floating point operations
+return a special IEEE 754 number format
+called a NaN for 'Not a Number'.
+
+
+example:
+
+
+(set 'x (sqrt -1)) → NaN
+(add x 123) → NaN
+(mul x 123) → NaN
+
+(+ x 123) → 123
+(* x 123) → 0
+
+(> x 0) → nil
+(<= x 0) → nil
+(= x x) → true
+(NaN? x) → true
+
+
+
+
+Note that all floating point arithmetic operations
+with a NaN yield a NaN.
+All comparisons with NaN return nil,
+but true when comparing to itself.
+Comparison with itself, however,
+would result in nottrue when using ANSI C.
+
+
+
+Integer operations treat NaN as 0 (zero) values.
+
+
+
+
+
+
net-accept
+syntax: (net-accept int-socket)
+
+
+Accepts a connection on a socket
+previously put into listening mode.
+Returns a newly created socket handle
+for receiving and sending data
+on this connection.
+
+Note that for ports less than 1024,
+newLISP must be started in superuser mode
+on UNIX-like operating systems.
+
+
+
+See also the server
+and client examples
+in the examples/ directory of the source
+distribution.
+
+
+
+
+
+
net-close
+syntax: (net-close int-socket [true)
+
+
+Closes a network socket in int-socket that
+was previously created by a
+net-connect
+or net-accept function.
+Returns true on success and
+nil on failure.
+
+
+example:
+
+
+(net-close aSock)
+
+
+
+
The optional true flag suppresses immediate shutdown
+of sockets waiting for pending data transmissions to finish.
+In the first syntax connects to a remote host computer
+specified in str-remote-host
+and a port specified in int-port.
+Returns a socket handle
+after having connected successfully;
+else it returns nil.
+
+The above program
+uses the finger service
+on a remote computer.
+This service returns information
+about an account holder
+on this computer.
+Some ISP and UNIX installations
+provide this service.
+
+
+
When executing:
+
+
+
+(finger "johnDoe@someSite.com")
+
+
+
+
+the program tries to connect
+to a server named "someSite.com"
+and sends the string "johnDoe".
+If "someSite.com" is running a finger service,
+it sends back information about the account
+"johnDoe" on this server.
+In case a connection cannot be made,
+the function returns the string "no connection."
+
+
+
+nameSite is split up into
+the account name and host name parts.
+net-connect is used to
+connect to someSite.com
+and returns the socket handle,
+which processes incoming data.
+
+
+
Local domain UNIX sockets
+
+
In the second syntax net-connect connects to a server on the
+local file system via a local domain UNIX socket named using
+str-file-path. Returns a socket handle after having connected
+successfully; else it returns nil.
+
+
+example:
+
+
+(net-connect "/tmp/mysocket") → 3
+
+; on OS/2 use "\\socket\\" prefix
+
+(net-connect "\\socket\\mysocket")
+
+
+
+
+
A local domain file system socket is created and returned.
+On the server side local domain sockets have been created
+using net-listen and net-accept.
+After the connection has been established the functions net-select,
+net-send and net-receive can be used
+as usual for TCP/IP stream communications. This type of connnection can be used as a fast
+bi-directional communications channel between processes on the same file system.
+This type of connection is not available on Win32 platforms.
+
+
UDP communications
+
+
+As a third parameter,
+the string "udp"
+or "u" can be specified
+in the optional str-mode
+to create a socket suited for
+UDP (User Datagram Protocol) communications.
+In UDP mode, net-connect
+does not try to connect
+to the remote host,
+but only binds the socket
+to the remote address.
+A subsequent net-send
+will send a UDP packet
+containing that target address.
+Using net-send-to
+causes that address to be overwritten.
+
+
+
+The functions net-receive
+and net-receive-from
+can also be used
+and will perform UDP communications.
+net-select
+and net-peek
+can be used to check
+for received data
+in a non-blocking fashion.
+
+
+
+If data is never received when
+opening a client connection
+using net-connect,
+then calling net-listen
+with the "udp" option
+may be preferable for starting
+the client side of the connection.
+net-listen binds a specific
+local address and port to the socket.
+When net-connect is used,
+the local address and port
+will be picked by the socket-stack
+functions of the host OS.
+
+
+
UDP multicast communications
+
+When specifying "multi"
+or "m" as a third parameter for str-mode,
+a socket for UDP multicast communications
+will be created.
+Optionally, the fourth parameter
+int-ttl can be specified
+as a TTL (time to live) value.
+If no int-ttl value is specified,
+a value of 3 is assumed.
+
+
+
+Note that specifying UDP multicast mode
+in net-connect does not actually establish
+a connection to the target multicast address
+but only puts the socket into UDP multicasting mode.
+On the receiving side,
+use net-listen
+together with the UDP multicast option.
+
+On the server side,
+net-peek or net-select
+can be used for non-blocking communications.
+In the above example, the server would block
+until a datagram is received.
+
+
+
+The address 226.0.0.1
+is just one multicast address
+in the Class D range of multicast addresses
+from 224.0.0.0 to 239.255.255.255.
+
+Specifying the string "broadcast" or "b"
+in the third parameter, str-mode, causes
+UDP broadcast communications to be set up.
+In this case, the broadcast address
+ending in 255 is used.
+
+Note that on the receiving side,
+net-listen should be used
+with the default address
+specified with an "" (empty string).
+Broadcasts will not be received
+when specifying an address.
+As with all UDP communications,
+net-listen does not actually put
+the receiving side in listen mode,
+but rather sets up the sockets
+for the specific UDP mode.
+
+
+
+The net-select
+or net-peek functions
+can be used to check for
+incoming communications
+in a non-blocking fashion.
+
+
+
+
+
+
net-error
+syntax: (net-error)
+
+
+Retrieves the last error that occurred
+when calling a net-* function.
+When any of the following functions return nil,
+net-error can be called to get more information:
+net-accept,
+net-connect,
+net-eval,
+net-listen,
+net-lookup,
+net-receive,
+net-receive-udp,
+net-select,
+net-send,
+net-send-udp,
+and net-service.
+Functions that communicate using sockets
+close the socket automatically
+and remove it from the
+net-sessions list.
+This makes for a very robust API
+in situations of unreliable net connections.
+Calling any of these functions
+successfully clears the last error.
+
+
+
The following messages are returned:
+
+
+
1: Cannot open socket
+2: Host name not known
+3: Not a valid service
+4: Connection failed
+5: Accept failed
+6: Connection closed
+7: Connection broken
+8: Socket send() failed
+9: Socket recv() failed
+10: Cannot bind socket
+11: Too many sockets in net-select
+12: Listen failed
+13: Badly formed IP
+14: Select failed
+15: Peek failed
+16: Not a valid socket
+
+
+
+example:
+
+
+(net-connect "jhghjgkjhg" 80) → nil
+
+(net-error) → (2 "ERR: Host name not known")
+
+Can be used to evaluate source remotely
+on one or more newLISP servers.
+This function handles all communications necessary
+to connect to the remote servers,
+send source for evaluation, and
+wait and collect responses.
+
+
+
+Beginning with version 8.9.8,
+str-host, int-port, and
+str-expr are evaluated.
+It is no longer necessary to specify them as constant.
+net-eval will evaluate
+these arguments.
+
+
+
+The remote TCP/IP servers
+are started in the following way:
+
+
+
+
+newlisp -c -d 4711 &
+
+;; or with logging connections
+
+newlisp -l -c -d 4711 &
+
+
+
+
+Instead of 4711,
+any other port number can be used.
+Multiple nodes can be started on different hosts
+and with the same or different port numbers.
+The -l or -L logging options
+can be specified to log connections
+and remote commands.
+
+
+
+The -d daemon mode
+allows newLISP to maintain state between connections.
+When keeping state between connections is not desired,
+the inetd daemon mode
+offers more advantages.
+The Internet inetd or xinetd services daemon
+will start a new newLISP process
+for each client connection.
+This makes for much faster servicing
+of multiple connections.
+In -d daemon mode,
+each new client request
+would have to wait for the previous request to be finished.
+See the chapter inetd daemon mode
+on how to configure this mode correctly.
+
+
+
+In the first syntax,
+net-eval talks to only one
+remote newLISP server node,
+sending the host in str-host
+on port int-port
+a request to evaluate the expression
+str-expr.
+If int-timeout is not given,
+net-eval will wait indefinitely for a response.
+Otherwise, if the timeout in milliseconds has expired,
+nil is returned;
+else, the evaluation result of str-expr
+is returned.
+
+The second syntax of net-eval
+returns a list of the results
+after all of the responses are collected
+or timeout occurs.
+Responses that time out
+return nil.
+The last example line shows how to specify
+a local-domain UNIX socket specifying the socket path
+and a port number of 0.
+Connection errors or errors
+that occur when sending information to nodes
+are returned as a list of error numbers
+and descriptive error strings.
+See the function net-error
+for a list of potential error messages.
+
+
+example:
+
+
+(net-eval '(
+("192.168.1.94" 4711 "(+ 3 4)")
+("192.168.1.95" 4711 "(+ 5 6)")
+) 5000)
+→ (7 11)
+
+(net-eval '(
+("localhost" 8081 {(foo "abc")})
+("localhost" 8082 "(myfunc 123)")
+) 3000)
+
+;; inetd or xinetd nodes on the same server and port
+
+(net-eval '(
+("localhost" 2000 {(foo "abc")})
+("localhost" 2000 "(myfunc 123)")
+) 3000)
+
+
+
+
+The first example shows two expressions
+evaluated on two different remote nodes.
+In the second example,
+both nodes run on the local computer.
+This may be useful when debugging
+or taking advantage of multiple CPUs
+on the same computer.
+When specifying 0 for the portnumber
+net-eval takes the hostname as
+file path to the local-domain UNIX socket.
+
+
+
+When nodes are inetd or xinetd-controlled,
+several nodes may have the same node
+for the IP address and port number.
+In this case, the UNIX daemon inetd or xinetd
+will start multiple newLISP servers.
+This is useful when testing distributed programs
+on just one machine.
+The last example illustrates this case.
+
+
+
+The source sent for evaluation
+can consist of entire multiline programs.
+This way, remote nodes can be loaded with programs first,
+then specific functions can be called.
+For large program files, the functions
+put-url or
+save (with a URL file name)
+can be used to transfer programs.
+
+
+
+Optionally, a handler function can be specified.
+This function will be repeatedly called while waiting
+and once for every remote evaluation completion.
+
+The example shows how the list of node specs
+can be assembled from a list of nodes
+and sources to evaluate.
+This may be useful
+when connecting to a larger number of remote nodes.
+Since version 8.9.7, net-eval
+has also been able to evaluate
+the spec given in the node lists.
+This allows the following code:
+
+While waiting for input from remote hosts,
+myhandler will be called with nil
+as the argument to param.
+When a remote node result is completely received,
+myhandler will be called with param
+set to a list containing the remote host name
+or IP number, the port, and the resulting expression.
+net-eval will return true before a timeout
+or nil if the timeout was reached or exceeded.
+All remote hosts that exceeded the timeout limit
+will contain a nil
+in their results list.
+
+
+
+Unless operating in raw mode,
+each piece of code sent to a remote node
+for evaluation should be one expression.
+This can be achieved by putting several statements
+into a begin block.
+
+
+
Raw mode
+
+An additional parameter in each node specification
+can control whether the returned result
+is evaluated (the default behavior) or returned as a string
+as it comes over the communications channel.
+The following example
+illustrates the difference between
+the default evaluated and raw modes
+of net-eval:
+
+While the evaluated mode
+always returns an evaluated expression,
+raw mode returns a string
+terminated by a line-feed.
+The last two statements reveal
+that in the default evaluated mode,
+only the result of the last expression evaluation
+is returned,
+while in raw mode,
+both results are visible,
+each terminated by a line-feed.
+
+
+
+Raw mode returns the same string
+as would be observed when entering expressions
+on the command line,
+while the evaluated mode returns LISP expressions
+ready for further newLISP processing.
+newLISP's net-eval
+protects the expression returned
+with a single quote before evaluating,
+thus ensuring that the expression string received
+is parsed in the receiving environment,
+but the resulting expression itself
+stays in the original form
+sent by the remote node.
+Only one quote gets prepended.
+For that reason,
+only one expression should be sent back
+when working in non-raw mode.
+
+
+
The following example shows this effect:
+
+
+
+(set 'prog [text]
+(list 1 2 3 4)
+(list 'a 'b 'c)
+[/text])
+
+; raw mode
+(net-eval '((host port prog true) ...))
+→ ("(1 2 3 4)\n(a b c)\n")
+
+; normal mode
+(net-eval '((host port prog) ...))
+invalid function in function net-eval : (a b c)
+
+; brace statments with (begin ...)
+(set 'prog [text]
+(begin
+(list 1 2 3 4)
+(list 'a 'b 'c))
+[/text])
+
+; normal mode
+(net-eval '((host port prog) ...))
+→ ((a b c))
+
+
+
+
+The begin in the definition of prog
+forces the return of only one expression,
+which then gets converted correctly
+by the receiving net-eval.
+
+
+
+Note that raw mode
+has always been part of net-eval,
+but it was not documented
+prior to version 8.7.5.
+
+Listens on a port specified in int-port.
+A call to net-listen
+returns immediately with a socket number,
+which is then used by
+the blocking net-accept function
+to wait for a connection.
+As soon as a connection is accepted,
+net-accept returns a socket number
+that can be used to communicate with
+the connecting client.
+
+The example waits for a connection on port 1234,
+then reads incoming lines until
+an empty line is received.
+Note that listening on ports lower than 1024
+may require superuser access on UNIX systems.
+
+
+
+On computers with more than one interface card,
+specifying an optional interface IP address or name
+in str-ip-addr directs net-listen
+to listen on the specified address.
+
+
+
+
+;; listen on a specific address
+(net-listen port "192.168.1.54")
+
+
+
+
Local domain UNIX sockets
+
+
In the second syntax net-listen listens for a client on the
+local file system via a local domain UNIX socket named using
+str-file-path. If successful returns a socket handle which can be used with
+net-accept to accept a client connection; else it returns nil.
+
+
+example:
+
+
+(net-listen "/tmp/mysocket") → 5
+
+; on OS/2 use "\\socket\\" prefix
+
+(net-listen "\\socket\\mysocket")
+
+(net-accept 5)
+
+
+
+
A local domain file system socket is created and listened on.
+A client will try to connect using the same str-file-path.
+After a connection has been accepted the functions net-select,
+net-send and net-receive can be used
+as usual for TCP/IP stream communications. This type of connnection can be used as a fast
+bi-directional communications channel between processes on the same file system.
+This type of connection is not available on Win32 platforms.
+
+
+
UDP communications
+
+
+As a third parameter,
+the optional string "udp" or "u"
+can be specified in str-mode
+to create a socket suited for UDP
+(User Datagram Protocol) communications.
+A socket created in this way
+can be used directly with
+net-receive-from
+to await incoming UDP data
+without using net-accept,
+which is only used in TCP communications.
+The net-receive-from call
+will block until a UDP data packet is received.
+Alternatively, net-select
+or net-peek can be used
+to check for ready data in a non-blocking fashion.
+To send data back to the address and port received
+with net-receive-from,
+use net-send-to.
+
+
+
+Note that net-peer will not work,
+as UDP communications do not maintain
+a connected socket with address information.
+
+The first example listens on a specific network adapter,
+while the second example listens on the default adapter.
+Both calls return a socket number
+that can be used in subsequent net-receive,
+net-receive-from,
+net-send-to,
+net-select,
+or net-peek function calls.
+
+
+
+Both a UDP server and UDP client
+can be set up using net-listen
+with the "udp" option.
+In this mode, net-listen
+does not really listen
+as in TCP/IP communications;
+it just binds the socket
+to the local interface address and port.
+
+
+
+For a working example, see the files
+examples/client and examples/server
+in the newLISP source distribution.
+
+
+
+Instead of net-listen
+and the "udp" option,
+the functions net-receive-udp
+and net-send-udp
+can be used for short transactions
+consisting only of one data packet.
+
+
+
+net-listen, net-select,
+and net-peek can be used
+to facilitate non-blocking reading.
+The listening/reading socket is not closed
+but is used again for subsequent reads.
+In contrast, when the
+net-receive-udp
+and net-send-udp pair is used,
+both sides close the sockets after sending and receiving.
+
+
+
+
UDP multicast communications
+
+
+If the optional string str-mode is specified as
+"multi" or "m",
+net-listen returns a socket suitable for multicasting.
+In this case, str-ip-addr contains one
+of the multicast addresses in the range 224.0.0.0
+to 239.255.255.255.
+net-listen will register str-ip-addr
+as an address on which to receive multicast transmissions.
+This address should not be confused with the IP address
+of the server host.
+
+On the server side,
+net-peek
+or net-select
+can be used for non-blocking communications.
+In the example above,
+the server would block
+until a datagram is received.
+
+Optionally, a bool flag
+can be specified in the second syntax.
+If the expression in bool
+evaluates to anything other than nil,
+host-by-name lookup will be forced,
+even if the name string starts
+with an IP number.
+
+
+
+
+
+
net-peek
+syntax: (net-peek int-socket)
+
+
+Returns the number of bytes
+ready for reading
+on the network socket int-socket.
+If an error occurs
+or the connection is closed,
+nil is Returned.
+
This function is only available on UNIX-based systems
+and must be run in superuser mode, i.e. using: sudo newlisp to
+start newLISP on Mac OS X or other BSD's, or as the root user on Linux.
+Broadcast mode and specifying ranges with with the - (hyphen) or
+* (star) are not available on IPv6 address mode.
+
+
In the first syntax, net-ping sends a ping
+ICMP 64-byte echo request to the address specified in str-address.
+If it is a broadcast address, the ICMP packet will be received
+by all addresses on the subnet. Note that for security reasons,
+many computers do not answer ICMP broadcast ping (ICMP_ECHO) requests.
+An optional timeout parameter can be specified in int-timeout.
+If no timeout is specified, a waiting time of 1000 milliseconds
+(one second) is assumed.
+
+
net-ping returns either a list of lists of IP strings
+and round-trip time in micro seconds for which a response was received
+or an empty list if no response was received.
+
+
+A return value of nil
+indicates a failure.
+Use the net-error function
+to retrieve the error message. If the message reads Cannot open socket,
+it is probably because newLISP is running without root permissions.
+newLISP can be started using:
+
+
+
+sudo newlisp
+
+
+
+Alternatively, newLISP can be installed
+with the set-user-ID bit set to run
+in superuser mode.
+
+In the second syntax, net-ping is run in batch mode.
+Only one socket is opened in this mode, but multiple ICMP packets are sent out—one
+each to multiple addresses specified in a list or specified by range.
+Packets are sent out as fast as possible. In this case, multiple answers can be received.
+If the same address is specified multiple times, thr receiving IP address will be flooded
+with ICMP packets.
+
+
+To limit the number of responses to be waited for in broadcast or batch mode,
+an additional argument indicating the maximum number of responses to receive
+can be specified in int-count. Usage of this parameter can cause
+the function to return sooner than the specified timeout.
+When a given number of responses has been received, net-ping will return
+before the timeout has occurred. Not specifying int-count or specifying 0
+assumes an int-count equal to the number of packets sent out.
+Broadcast or batch mode—as well as normal addresses
+and IP numbers or hostnames— can be mixed in one net-ping statement by
+putting all of the IP specs into a list.
+
+
+The second and third line show how the batch mode of net-ping
+can be initiated by specifying the * (asterisk)
+as a wildcard character for the last subnet octet
+in the IP number. The fourth and fifth line show how an IP
+range can be specified for the last subnet octet in the IP number.
+net-ping will iterate through all numbers
+from either 1 to 254 for the star * or the range specified,
+sending an ICMP packet to each address.
+Note that this is different from the broadcast mode
+specified with an IP octet of 255.
+While in broadcast mode, net-ping sends out only one packet,
+which is received by multiple addresses. Batch mode explicitly generates
+multiple packets, one for each target address. When specifying broadcast
+mode, int-count should be specified too.
+
+
+When sending larger lists of IPs in batch mode over one socket,
+a longer timeout may be necessary to allow enough time for all of the packets
+to be sent out over one socket. If the timeout is too short,
+the function net-ping may return an incomplete list or the empty list ().
+In this case net-error will return a timeout error.
+On error nil is returned and net-error
+can be used to retrieve an error message.
+
+
+On some systems only lists up to a specific length can be handled
+regardless of the timeout specified. In this case the range should
+be broken up in subranges used with multiple net-ping
+invocations. In any case, net-ping will send out packages
+as quickly as possible.
+
+Receives data on the socket int-socket
+into a string contained in sym-buffer.
+A maximum of int-max-bytes is received.
+net-receive returns the number of bytes read.
+If there is a break in the connection,
+nil is returned.
+The space reserved in sym-buffer
+is exactly the size of bytes read.
+
+
+
+Note that net-receive is a blocking call
+and does not return until the data arrives at int-socket.
+Use net-peek
+or net-select to find out
+if a socket is ready for reading.
+
+
+
+Optionally, a wait-string
+can be specified
+as a fourth parameter.
+net-receive then returns after
+a character or string of characters
+matching wait-string
+is received.
+The wait-string will be part
+of the data contained in sym-buffer.
+
+When calling gettime,
+the program connects to port 13
+of the server netcom.com.
+Port 13 is a date-time service
+on most server installations.
+Upon connection, the server sends
+a string containing the date and time of day.
+
+The second example defines a new function
+net-receive-line,
+which returns after receiving a newline character
+(a string containing one character in this example)
+or 256 characters.
+The "\n" string is part of the contents of sBuff.
+
+
+
+Note that when the fourth parameter is specified,
+net-receive is slower than the normal version
+because information is read character by character.
+In most situations, the speed difference can be neglected.
+
+net-receive-from can be used to set up
+non-blocking UDP communications.
+The socket in int-socket
+must previously have been opened
+by either net-listen
+or net-connect
+(both using the "udp" option).
+int-max-size specifies
+the maximum number of bytes that will be received.
+On Linux/BSD, if more bytes are received,
+those will be discarded.
+On Win32, net-receive-from will return nil
+and close the socket.
+
+
+example:
+
+
+;; listen on port 1001 on the default address
+(net-listen 1001 "" "udp") → 1980
+
+;; optionally poll for arriving data with 100ms timeout
+(while (not (net-select 1980 "r" 100000)) (do-something ...))
+
+(net-receive-from 1980 20) → ("hello" "192.168.0.5" 3240)
+
+;; send answer back to sender
+(net-send-to "192.168.0.5" 3240 "hello to you" 1980)
+
+(net-close 1980) ; close socket
+
+
+
+
+The second line in this example is optional.
+Without it, the net-receive-from call
+would block until data arrives.
+A UDP server could be set up
+by listening and polling several ports
+serving them as they receive data.
+
+
+
+Note that net-receive
+could not be used in this case
+because it does not return
+the sender's address and port information,
+which are required to talk back.
+In UDP communications,
+the data packet itself
+contains the address of the sender,
+not the socket over which
+communication takes place.
+
+
+
+See also the net-connect function
+with the "udp" option and the
+net-send-to function
+for sending UDP data packets over open connections.
+
+Receives a User Datagram Protocol (UDP) packet on port int-port,
+reading int-maxsize bytes.
+If more than int-maxsize bytes are received,
+bytes over int-maxsize are discarded on Linux/BSD;
+on Win32, net-receive-udp returns nil.
+net-receive-udp blocks until a datagram arrives
+or the optional timeout value in int-microsec expires.
+When setting up communications between datagram sender and receiver,
+the net-receive-udp statement must be set up first.
+
+
+
+
+No previous setup using net-listen
+or net-connect is necessary.
+
+
+
+net-receive-udp returns a list
+containing a string of the UDP packet
+followed by a string containing
+the sender's IP number and the port used.
+
+
+example:
+
+
+;; wait for datagram with maximum 20 bytes
+(net-receive-udp 1001 20)
+
+;; or
+(net-receive-udp 1001 20 5000000) ; wait for max 5 seconds
+
+;; executed on remote computer
+(net-send-udp "nuevatec.com" 1001 "Hello") → 4
+
+;; returned from the net-receive-udp statement
+→ ("Hello" "128.121.96.1" 3312)
+
+;; sending binary information
+(net-send-udp "ahost.com" 2222 (pack "c c c c" 0 1 2 3))
+→ 4
+
+;; extracting the received info
+(set 'buff (first (net-receive-udp 2222 10)))
+
+(print (unpack "c c c c" buff)) → (0 1 2 3)
+
+
+
+
+See also the net-send-udp
+function for sending datagrams and
+the pack and unpack
+functions for packing and unpacking binary information.
+
+
+
+To listen on a specified address
+on computers with more than one interface card,
+an interface IP address or name can be
+optionally specified in str-addr-if.
+When specifying str-addr-if,
+a timeout must also be specified
+in int-wait.
+
+
+
+As an alternative, UDP communication
+can be set up using net-listen,
+or net-connect
+together with the "udp" option
+to make non-blocking data exchange possible
+with net-receive-from
+and net-send-to.
+
+In the first form,
+net-select finds out about the status
+of one socket specified in int-socket.
+Depending on str-mode,
+the socket can be checked
+if it is ready for reading or writing,
+or if the socket has an error condition.
+A timeout value is specified in int-micro-seconds.
+
+
+
+In the second syntax,
+net-select can check for a list of sockets
+in list-sockets.
+
+
+
+The following value can be given for str-mode:
+
+
+
+"read" or "r" to check if ready for reading or accepting.
+
+"write" or "w" to check if ready for writing.
+"exception" or "e" to check for an error condition.
+
+
+
+Read, send, or accept operations
+can be handled without blocking
+by using the net-select function.
+net-select waits
+for a socket to be ready
+for the value given in int-micro-seconds,
+then returns true or nil
+depending on the readiness of the socket.
+During the select loop,
+other portions of the program can run.
+On error,
+net-error is set.
+When -1 is specified for int-micro-seconds,
+net-select will never time out.
+
+When net-select is used,
+several listen and connection sockets can be watched,
+and multiple connections can be handled.
+When used with a list of sockets,
+net-select will return a list of ready sockets.
+The following example would listen on two sockets
+and continue accepting and servicing connections:
+
+In the second syntax,
+a list is returned
+containing all the sockets
+that passed the test;
+if timeout occurred,
+an empty list is returned.
+An error causes
+net-error to be set.
+
+
+
+Note that supplying a nonexistent socket to net-select
+will cause an error to be set in net-error.
+
+Sends the contents of str-buffer on the connection specified by int-socket.
+If int-num-bytes is specified, up to int-num-bytes are sent.
+If int-num-bytes is not specified, the entire contents will be sent.
+net-send returns the number of bytes sent or nil on failure.
+
+
+On failure use net-error to get more error information.
+
+example:
+
+Sends UDP data packets on open connections.
+The socket in int-socket
+must have previously been opened with a net-connect
+or net-listen function.
+Both functions must be opened
+with their "udp" option.
+The host in str-remotehost
+can be specified either as a hostname
+or as an IP-number string.
+
+
+example:
+
+
+(net-connect "asite.com" 1010 "udp")
+→ 2058 ; get a UDP socket
+
+(net-send-to "asite.com" 1010 "hello" 2058)
+
+;; optionally poll for answer
+(while (not (net-select 2058 "r" 100000))
+(do-something …))
+
+;; receive answering data from UDP server
+(net-receive-from 2058 20)
+→ ("hello to you" "10.20.30.40" 1010)
+
+(net-close 2058)
+
+
+
+
+The second line in the example is optional.
+Without it,
+the net-receive-from call
+would block until data arrives.
+Using polling,
+a client could maintain conversations with several UDP servers
+at the same time.
+
+Sends a User Datagram Protocol (UDP)
+to the host specified in str-remotehost
+and to the port in int-remoteport.
+The data sent is in str-buffer.
+
+
+
+No previous setup using net-connect
+or net-listen is necessary.
+net-send-udp returns immediately
+with the number of bytes sent
+and closes the socket used.
+If no net-receive-udp statement
+is waiting at the receiving side,
+the datagram sent is lost.
+When using datagram communications over insecure connections,
+setting up a simple protocol between sender and receiver
+is recommended for ensuring delivery.
+UDP communication by itself
+does not guarantee reliable delivery
+as TCP/IP does.
+
+
+example:
+
+
+(net-send-udp "somehost.com" 3333 "Hello") → 5
+
+
+
+
+net-send-udp is also suitable
+for sending binary information
+(e.g., the zero character or other nonvisible bytes).
+For a more comprehensive example,
+see net-receive-udp.
+
+
+
+Optionally, the sending socket
+can be put in broadcast mode
+by specifying true
+or any expression
+not evaluating to nil
+in bool:
+
+The UDP will be sent to all nodes
+on the 192.168.1 network.
+Note that on some operating systems,
+sending the network mask 255
+without the booltrue option
+will enable broadcast mode.
+
+
+
+As an alternative,
+the net-connect function
+using the "udp" option—together with
+the net-send-to function—can
+be used to talk to a UDP listener
+in a non-blocking fashion.
+
+Returns a list of active listening and connection sockets.
+
+
+
+
+
+
new
+syntax: (new context-sourcesym-context-target [bool])
+syntax: (new context-source)
+
+
+In the first syntax,
+context-source is the name of an existing context,
+and sym-context-target is the name of a new context
+to be created just like the original,
+with the same variable names and user-defined functions.
+If the context in sym-context-target already exists,
+then new symbols and definitions are added.
+Existing symbols are overwritten
+when the expression in bool
+evaluates to anything besides nil;
+otherwise, the content of existing symbols
+will remain.
+This makes mixins of context objects possible.
+new returns the target context,
+which cannot be MAIN.
+
+
+
+In the second syntax,
+the existing context in context-source
+gets copied into the current context
+as the target context.
+
+
+
+All references to symbols in the originating context
+will be translated to references in the target context.
+This way, all functions and data structures referring to symbols
+in the original context will now refer to symbols in the target context.
+
+
+example:
+
+
+(new CTX 'CTX-2) → CTX-2
+
+;; force overwrite of existing symbols
+(new CTX MyCTX true) → MyCTX
+
+(set 'CTX:x 123)
+(new CTX) → MAIN ; copies x into MAIN
+x → 123
+
+(map new '(Ct-a Ct-b Ct-c)) ; merge into current context
+
+
+
+
+The first line in the example creates a new context
+called CTX-2 that has the exact same structure
+as the original one.
+Note that CTX is not quoted
+because contexts evaluate to themselves,
+but CTX-2 must be quoted because it does not exist yet.
+
+
+
+The second line merges the context CTX into MyCTX.
+Any existing symbols of same name in MyCTX
+will be overwritten.
+Because MyCTX already exists,
+the quote before the context symbol can be omitted.
+
+
+
+The last lines show how a foreign context
+gets merged into the current one
+and how map can be used
+to merge a list of contexts.
+
+
+
+Context symbols need not be mentioned explicitly,
+but they can be contained in variables:
+
+
+example:
+
+
+(set 'foo:x 123)
+(set 'bar:y 999)
+
+(set 'ctxa foo)
+(set 'ctxb bar)
+
+(new ctxa ctxb) ; from foo to bar
+
+bar:x → 123 ; x has been added to bar
+bar:y → 999)
+
+
+
+
+The example refers to contexts in variables
+and merges context foo into bar.
+
+
+
+
+See also the function def-new
+for moving and merging single functions
+instead of entire contexts.
+See the context function
+for a more comprehensive example of new.
+
+
+
+
+
+
nil?
+syntax: (nil? expr)
+
+
+If the expression in expr evaluates to nil,
+then nil? returns true;
+otherwise, it returns nil.
+
+In the first form, normal returns a list of length int-n
+of random, continuously distributed floating point numbers
+with a mean of float-mean
+and a standard deviation of float-stdev.
+The random generator used internally
+can be seeded using the seed function.
+
+In the second form,
+normal returns a single
+normal distributed floating point number:
+
+
+
+
+(normal 0 1) → 0.6630859375
+
+
+
+
+See also the random
+and rand functions
+for evenly distributed numbers,
+amb for randomizing evaluation
+in a list of expressions,
+and seed for setting a different start point
+for pseudo random number generation.
+
+
+
+
+
+
now
+syntax: (now [int-offset])
+
+Returns information about
+the current date and time
+as a list of integers.
+An optional time-zone offset
+can be specified in minutes in int-offset.
+This causes the time to be shifted
+forward or backward in time,
+before being split into separate date values.
+
+The numbers represent the following date-time fields:
+
+
+
+
+
format
description
+
+
year
Gregorian calendar
+
month
(1–12)
+
day
(1–31)
+
hour
(0–23) UCT
+
minute
(0–59)
+
second
(0–59)
+
microsecond
(0–999999)
+ OS-specific, millisecond resolution
+
+
day of current year
Jan 1st is 1
+
day of current week
(1–7) starting Sunday
+
time zone offset in minutes
west of GMT
+
daylight savings time flag
(0–1) on Linux/UNIX
+ bias and in minutes on Win32
+
+
+
+
+
+
+The second example returns the UCT time value of seconds
+after January 1, 1970.
+
+
+
+Ranging from 0 to 23,
+hours are given in Coordinated Universal Time (UCT)
+and are not adjusted for the local time zone.
+The resolution of the microsecond field
+depends on the operating system and platform.
+On some platforms,
+the last three digits of the microseconds field
+are always 0 (zero).
+
+Note that on Solaris,
+the returned time offset value
+is not working correctly in some versions/platforms
+and may contain garbage values.
+
+
+
+On many platforms,
+the daylight savings flag
+is not active
+and returns 0 (zero)
+even during daylight savings time.
+
+
+
+
+
+
null?
+syntax: (null? expr)
+
+
+Checks if an expression evaluates to nil,
+the empty list (),
+the empty string "",
+NaN (not a number),
+or 0 (zero),
+in which case it returns true.
+In all other cases,
+null? returns nil.
+The predicate null? is useful in conjunction with the functions filter or clean to check the outcome of other newLISP operations.
+
+
+example:
+
+
+(map null? '(1 0 0.0 2 NaN "hello" "" (a b c) () nil true))
+→ (nil true true true nil true nil true nil true true nil)
+
+(filter null? '(1 0 2 0.0 NaN "hello" "" (a b c) () nil true))
+→ (0 0 NaN "" () nil)
+
+(clean null? '(1 0 2 0.0 NaN "hello" "" (a b c) () nil true))
+→ (1 2 "hello" (a b c) true)
+
+Calculates the number of payments required to pay a loan of num-pv with a constant interest rate of num-interest and payment num-pmt.
+If num-fv is omitted,
+the future value of the loan is assumed to be 0.0.
+If payment is at the end of the period,
+int-type is 0;
+else it is 1.
+If int-type is omitted,
+0 is assumed.
+
+The example calculates the number of monthly payments required to pay a loan of $100,000 at a yearly interest rate of 7 percent with payments of $775.30.
+
+
+
+See also the fv,
+irr,
+npv,
+pmt,
+and pv functions.
+
+
+
+
+
npv
+syntax: (npv num-interestlist-values)
+
+
+Calculates the net present value of an investment with a fixed interest rate num-interest and a series of future payments and income in list-values.
+Payments are represented by negative values in list-values,
+while income is represented by positive values in list-values.
+
+In the first version,
+nth evaluates int-index
+and uses it as an index
+into list,
+returning the element found
+at that index.
+See also Indexing elements of strings and lists.
+Multiple indices may be specified
+to recursively access elements in nested lists.
+If there are more indices than nesting levels,
+the extra indices are ignored.
+
+
+example:
+
+
+(set 'L '(a b c))
+(nth 0 L) → a
+(nth (L 0)) → a
+; or simply
+(L 0) → a
+
+(set 'names '(john martha robert alex))
+→ (john martha robert alex)
+
+(nth (names 2)) → robert
+; or simpy
+(names 2) → robert
+
+(names -1) → alex
+
+(set 'persons '((john 30) (martha 120) ((john doe) 17)))
+
+(persons 1 1) → 120
+
+(nth (persons 2 0 1)) → doe
+; or simply
+(persons 2 0 1) → doe
+
+; multiple indices in a vector
+(set 'v '(2 0 1))
+(persons v) → doe
+
+(persons -2 0) → martha
+
+(persons 10) → ((john doe) 17)) ; out of bounds
+(person -5) → (john 30) ; out of bounds
+
+
+
+
When using a syntax with parenthesized list and indices (L idx) then
+L can be the context of the default functor L:L. This allows lists
+passed by reference:
+
+
+(set 'L:L '(a b c d e f g))
+
+(define (second ctx)
+ (nth (ctx 1)))
+
+;; passing the list in L:L by reference
+(second L) → b
+
+;; passing the list in L:L by value
+(second L:L) → b
+
+
+
Reference passing is faster and uses less memory in big lists and should
+be used on lists with more than a few hundred items.
+
+
Note that the implicit indexing version of nth is not breaking Lisp
+syntax rules but should be understood as a logical expansion of Lisp syntax rules to
+other data types than built-in functions or lambda expressions. A list in the functor
+position of an s-expression assumes self-indexing functionality using the index
+arguments following.
+
+
+The implicit indexed syntax forms are faster but the other form with an explicit
+nth may be more readable in some situations.
+
+
+
+In the second version,
+nth works on arrays just like it does on lists,
+but out-of-bounds indices will cause an error message.
+
+
+example:
+
+
+(set 'aArray (array 2 3 '(a b c d e f)))
+→ ((a b c) (d e f))
+(nth (aArray 1)) → (d e f)
+(aArray 1) → (d e f)
+
+(nth (aArray 1 0)) → d
+(nth (aArray '(1 0))) → d
+
+(aArray 1 0) → d
+(aArray '(1 0)) → d
+
+
+
+
+In the third version,
+nth returns the character found at the position int-index in str and returns it as a string.
+
+
+example:
+
+
+(nth ("newLISP" 0)) → "n"
+
+("newLISP" 0) → "n"
+`
+("newLISP" -1) → "P"
+
+
+
+
+See also the set-nth function for accessing multidimensional nested lists and arrays.
+See the push and pop functions for accessing multidimensional lists.
+
+
+
+Note also that nth works on character boundaries rather than byte boundaries when using the UTF-8–enabled version of newLISP.
+
+Sets the int-nth element of a list or array with the evaluation of exp-replacement
+and returns the old element. As shown in the last two syntax lines,
+implicit indexing syntax can be used
+for specifying indices. Implicit indexing is the preferred form in
+nth-set and set-nth, but both forms remain valid.
+
+
+
+nth-set performs a destructive operation, changing the original list or array.
+More than one index can be specified to recursively traverse nested list structures
+or multidimensional arrays. An out-of-bounds index always returns the last or first element
+when indexing a list, but it causes an out-of-bound error when indexing an array.
+
+
+
+When replacing in lists, the old element is also contained in the system variable $0 and
+can be used in the replacement expression itself.
+
+
+
+
+(set 'aList '(a b c d e f g))
+
+;; plain syntax for on level index
+(nth-set 4 aList (list $0 'z)) → e ; old value
+
+;; modern syntax and preferred for multiple indices
+(nth-set (aList 4) (list $0 'z)) → e ; old value
+
+aList → (a b c d (e z) f g)
+
+
+
+
+
In the second form,
+the int-nth character in str is replaced with the string in str-replacement.
+Out-of-bounds indices will pick the first or last character for replacement,
+and the system variable $0 is set to the old, replaced character.
+
+
+example:
+
+
+;;;;;;;;;;; usage on lists ;;;;;;;;;;;;
+
+(set 'aList '(a b c d e f g))
+
+(nth-set (aList 2) "I am the replacement") → c ; new syntax
+
+aList → (a b "I am the replacement" d e f g)
+
+$0 → c
+
+(set 'aList '(a b (c d (e f g) h) i))
+(nth-set (aList 2 2 0) 'x) → e
+
+aList → (a b (c d (x f g) h) i)
+$0 → e
+
+(nth-set (aList -2 2 -1) 99) → g
+
+aList → (a b (c d (x f 99) h) i)
+
+;; use indices in a vector
+
+(set 'aList '(a b (c d (e f g) h) i))
+
+(set 'vec (ref 'f aList)) → (2 2 1)
+
+(nth-set (aList vec) 'Z) → f ; old value
+
+aList → (a b (c d (e Z g) h) i)
+
+;; usage on default functors
+
+(set 'db:db '(a b c d e f g))
+
+(nth-set (db 3) 99) → d
+
+db:db → (a b c 99 e f g)
+
+
+
+
+The following examples use nth-set to change the contents of arrays.
+
+
+example:
+
+
+;;;;;;;;;;; usage on arrays ;;;;;;;;;;;;
+
+(set 'myarray (array 3 4 (sequence 1 12)))
+→ ((1 2 3 4) (5 6 7 8) (9 10 11 12))
+
+(nth-set (myarray 2 3) 99) → 12
+myarray
+→ ((1 2 3 4) (5 6 7 8) (9 10 11 99))
+
+(nth-set (myarray -2 1) "hello") → 6
+myarray
+→ ((1 2 3 4) (5 "hello" 7 8) (9 10 11 99))
+
+(nth-set (myarray 1) (array 4 '(a b c d)))
+→ (5 "hello" 7 8)
+myarray
+→ ((1 2 3 4) (a b c d) (9 10 11 99))
+
+;; usage on default functors
+(set 'myarray:myarray (array 7 '(a b c d e f g)))
+
+(nth-set (myarray 3) 99) → d
+myarray:myarray → (a b c 99 e f g)
+
+
+
+
+
When replacing whole rows as in the third example,
+care must be taken to replace it as an array.
+See also the array functions array,
+array?,
+and array-list.
+
+
+
+
In second form,
+the int-nth character in str is replaced with the string in str-replacement.
+
+
+example:
+
+
+;;;;;;;;;;; usage on strings ;;;;;;;;;;;;
+(set 's "abcd")
+
+(nth-set (s 0) "xyz") → "a"
+s → "xyzbcd"
+$0 → "a"
+
+
+
+
+
+nth-set uses the system variable $0 for the element found in lists and strings.
+This can be used in the replacement expression:
+
+See the set-nth function,
+which works like nth-set
+but returns the whole changed expression
+instead of the replaced element.
+set-nth is also slower when doing replacements
+in larger lists or string buffers.
+
+
+
+Use the nth,
+push,
+and pop functions
+to access multidimensional nested lists.
+The nth function
+will also work
+with multidimensional nested arrays.
+
+
+
+
+nth-set works exactly like set-nth but returns the replaced element instead of the whole changed list expression.
+nth-set is much faster when replacing elements in larger lists or arrays.
+
+
+
+
+
+
number?
+syntax: (number? exp)
+
+
+true is returned only if exp evaluates to a floating point number or an integer;
+otherwise,
+nil is returned.
+
+The str-path-file is a file name,
+and str-access-mode is a string specifying the file access mode.
+open returns an integer,
+which is a file handle to be used on subsequent read or write operations on the file.
+On failure,
+open returns nil.
+The access mode "write" creates the file if it doesn't exist,
+or it truncates an existing file to 0 (zero) bytes in length.
+
+
+
+The following strings are legal access modes:
+
+
+
+"read" or "r" for read only access
+
+"write" or "w" for write only access
+"update" or "u" for read/write access
+"append" or "a" for append read/write access
+
+
+The first example uses open to set the device for print and writes the word "hello world" into the file newfile.data.
+The second example reads a byte value at offset 6 in the same file (the ASCII value of 'w' is 119).
+Note that using close on (device) automatically resets device to 0 (zero).
+
+
+
+As an additional str-option,
+"non-block" or "n" can be specified after the "read" or "write" option.
+Only available on UNIX systems,
+non-blocking mode can be useful when opening named pipes but is not required to perform I/O on named pipes.
+
+
+
+To create a named pipe in newLISP,
+use the exec or import function:
+
+Evaluates expressions exp-x from left to right until finding a result that does not evaluate to nil or the empty list ().
+The result is the return value of the or expression.
+
+
+example:
+
+
+(set 'x 10)
+(or (> x 100) (= x 10)) → true
+(or "hello" (> x 100) (= x 10)) → "hello"
+(or '()) → nil
+(or true) → true
+(or) → nil
+
+
+
+
+
+
ostype
+syntax: ostype
+
+
ostype is a built-in system constant
+containing the name of the operating system
+newLISP is running on.
+
+example:
+
+
+ostype → "Win32"
+
+
+
+
One of the following strings is returned: "Linux", "BSD", "OSX", "Tru64Unix", "Solaris", "Win32", or "OS/2".
+
+
+
+
ostype can be used to write platform-independent code:
+Packs one or more expressions (exp-1 to exp-n)
+into a binary format specified in the format string str-format,
+returning the binary structure in a string buffer.
+The symmetrical unpack function is used
+for unpacking. The expression arguments can also be given in a list.
+pack and unpack are useful
+when reading and writing binary files
+(see read-buffer and
+write-buffer)
+or when unpacking binary structures
+from return values of imported C functions
+using import.
+
+
+
+The following characters are used in str-format:
+
+
+
+
+
+
format
description
+
+
+
c
+
+
a signed 8-bit number
+
+
+
+
b
+
an unsigned 8-bit number
+
+
+
+
d
+
a signed 16-bit short number
+
+
+
+
u
+
an unsigned 16-bit short number
+
+
+
+
ld
+
a signed 32-bit long number
+
+
+
+
lu
+
an unsigned 32-bit long number
+
+
+
+
Ld
+
a signed 64-bit long number
+
+
+
+
Lu
+
an unsigned 64-bit long number
+
+
+
+
f
+
a float in 32-bit representation
+
+
+
+
lf
+
a double float in 64-bit representation
+
+
+
+
sn
+
a string of n null padded ASCII characters
+
+
+
+
nn
+
n null characters
+
+
+
+
>
+
+
switch to big endian byte order
+
+
+
+
<
+
switch to little endian byte order
+
+
+
+
+
+
+
+Note that newLISP only supports 32-bit, signed integers
+and treats lu and ld the same way internally.
+
+
+
+pack will convert all floats into integers
+when passed to b, c, d, ld,
+or lu formats.
+It will also convert integers into floats
+when passing them to f and lf formats.
+
Note that the list should be referenced directly in pack,
+so the pointers passed by adr are valid. adr would be written
+as char * adr[] in the C-programming language and represents a 32-bit pointer to an
+array of 32-bit string pointers.
+
+
+
+The > and < specifiers
+can be used to switch between little endian
+and big endian byte order
+when packing or unpacking:
+
+
+
+
+(pack "d" 1) → "\001\000" ;; on little endian CPU
+(pack ">d" 1) → "\000\001" ;; force big endian
+
+(pack "ld" 1) → "\001\000\000\000" ;; on little endian CPU
+(pack "<ld" 1) → "\000\000\000\001" ;; force big endian
+
+
+
+
+Switching the byte order will affect all number formats with 16-,
+32-,
+or 64-bit sizes.
+
+
+
+The pack and unpack format need not be the same:
+
+Breaks the string that results from evaluating str-data into string tokens,
+which are then returned in a list.
+When no str-break is given,
+parse tokenizes according to newLISP's internal parsing rules.
+A string may be specified in str-break for tokenizing only at the occurrence of a string.
+If an int-option number is specified,
+a regular expression pattern may be used in str-break.
+
+
+
+When str-break is not specified,
+the maximum token size is 2048 for quoted strings and 256 for identifiers.
+In this case,
+newLISP uses the same faster tokenizer it uses for parsing LISP source.
+If str-data is specified,
+there is no limitation on the length of tokens.
+A different algorithm is used that splits the source string str-data at the string in str-break.
+
+The last two examples show a regular expression
+as the break string with the default option 0 (zero).
+Instead of { and } (left and right curly brackets),
+quotes can be used to limit the pattern.
+In this case,
+double backslashes must be used
+inside the pattern.
+The last pattern could be used
+for parsing CVS files.
+For the regular expression option numbers,
+see regex.
+
Parses a date from a text string in str-date
+using a format as defined in str-format, which uses
+the same formatting rules found in date.
+The function parse-date returns the number of seconds passed
+since January 1, 1900.
+
+
This function is not available on Win32 platforms.
See the date function for all possible format descriptors.
+
+
+
+
+
peek
+syntax: (peek int-handle)
+
+
+Returns the number of bytes ready to be read on a file descriptor;
+otherwise,
+it returns nil if the file descriptor is invalid.
+peek can also be used to check stdin.
+This function is only available on UNIX-like operating systems.
+
+
+example:
+
+
+(peek 0) ; check # of bytes ready on stdin
+
+
+
+
+Use the net-peek function
+to check for network sockets,
+or for the number of available bytes on them.
+On UNIX systems,
+net-peek can be used
+to check file descriptors.
+The difference is that
+net-peek also sets
+net-error.
+
+
+
+
+
+
pipe
+syntax: (pipe)
+
+
+Creates an inter-process communications pipe and returns the read and write handles to it within a list.
+
+
+example:
+
+
+(pipe) → (3 4) ; 3 for read, 4 for writing
+
+
+
+
+The pipe handles can be passed to a child process or thread launched via process or to fork for inter-process communications.
+
+
+
+Note that the pipe does not block when being written to,
+but it does block reading until bytes are available.
+A read-line blocks until a newline character is received.
+A read-buffer blocks when fewer characters than specified are available from a pipe that has not had the writing end closed by all processes.
+
+
+
+More than one pipe can be opened if required.
+
+
+
+newLISP can also use named pipes.
+See the open function for further information.
+
+Calculates the payment for a loan based on a constant interest of num-interest and constant payments over num-periods of time.
+num-future-value is the value of the loan at the end (typically 0.0).
+When paying at the end of each period,
+num-type is 0 (zero);
+otherwise,
+it is 1.
+If omitted,
+int-type is assumed to be 0 (zero) for payment at the end of a period.
+
+
+example:
+
+
+(pmt (div 0.07 12) 240 100000) → -775.2989356
+
+
+
+
+The above example calculates a payment of $775.30 for a loan of $100,000 at a yearly interest rate of 7 percent.
+It is calculated monthly and paid over 20 years (20 * 12 = 240 monthly periods).
+This illustrates the typical way payment is calculated for mortgages.
+
+
+
+See also the fv,
+irr,
+nper,
+npv,
+and pv functions.
+
+
+
+
+
+
pop
+syntax: (pop list [int-index-1 [int-index-2 ... ]])
+syntax: (pop list [list-indexes])
+
+syntax: (pop str [int-index [int-length]])
+
+
Using pop elements can be removed from lists and characters from strings.
+
+
+In the first syntax pop extracts an element from the list found
+by evaluating list.
+If a second parameter is present,
+the element at int-index is extracted and returned.
+See also Indexing elements of strings and lists.
+
+
+
+In the second version,
+indices are specified in the list list-indexes.
+This way,
+pop works easily together with ref
+and ref-all,
+which return lists of indices.
+
+
+
+pop changes the contents of the target list.
+The popped element is returned.
+
+
+example:
+
+
+(set 'pList '((f g) a b c "hello" d e 10))
+
+(pop pList) → (f g)
+(pop pList) → a
+plist → (b c "hello" d e 10)
+
+(pop pList 3) → d
+(pop pList 100) → 10
+pList → (b c "hello" e)
+
+(pop pList -1) → e
+pList → (b c "hello")
+
+(pop pList -2) → c
+pList → (b "hello")
+
+(set 'pList '(a 2 (x y (p q) z)))
+
+(pop pList -1 2 0) → p
+
+;; use indices in a list
+(set 'pList '(a b (c d () e)))
+
+(push 'x pList '(2 2 0)) → x
+pList
+→ (a b (c d (x) e))
+
+(ref 'x pList) → (2 2 0)
+
+(pop pList '(2 2 0)) → x
+
+Sends an HTTP POST request to the URL in str-url.
+POST requests are used to post information collected from web entry forms to a web site.
+Most of the time,
+the function post-url mimics what a web browser would do when sending information collected in an HTML form to a server,
+but it can also be used to upload files (see an HTTP reference).
+The function returns the page returned from the server in a string.
+
+
+
+When post-url encounters an error,
+it returns a string description of the error beginning with ERR:.
+
+
+
+The last parameter,
+int-timeout,
+is for an optional timeout value,
+which is specified in milliseconds.
+When no response from the host is received before the timeout has expired,
+the string ERR:
+timeout is returned.
+
+The above example uploads a user name and city using a special format called application/x-www-form-urlencoded.
+post-url can be used to post other content types such as files or binary data.
+See an HTTP reference for other content-type specifications and data encoding formats.
+When the content-type parameter is omitted,
+post-url assumes application/x-www-form-urlencoded as the default content type.
+
+
+
Additional parameters
+
+When str-content-type is specified,
+the str-option"header" or "list" can be specified as the return page.
+If the int-timeout option is specified,
+the custom header option str-header can be specified,
+as well.
+See the function get-url for details on both of these options.
+
+Reformats expressions for print,
+save,
+or source.
+The first parameter,
+int-length,
+specifies the maximum line length,
+and str-tab specifies the string used to indent lines.
+All parameters are optional.
+pretty-print returns the current settings or the new settings when one or both parameters are specified.
+
+The first example reports the default settings of 64 for the maximum line length and a TAB character for indenting.
+The third example changes the line length only.
+
+
+
+Note that pretty-print cannot be used to prevent line breaks from being printed.
+To completely suppress pretty printing,
+use the function string to convert the expression to a raw unformatted string as follows:
+
+
+example:
+
+
+;; print without formatting
+
+(print (string my-expression))
+
+
+
+
+
+
+
+
primitive?
+syntax: (primitive? exp)
+
+
+Evaluates and tests if exp is a primitive symbol and returns true or nil depending on the result.
+
+
+example:
+
+
+(set 'var define)
+(primitive? var) → true
+
+
+
+
+
+
+
print
+syntax: (print exp-1 [exp-2 ... ])
+
+
+Evaluates and prints exp-1—
+to the current I/O device,
+which defaults to the console window.
+See the built-in function device for details on how to specify a different I/O device.
+
+
+
+List expressions are indented by the nesting levels of their opening parentheses.
+
+
+
+Several special characters may be included in strings encoded with the escape character \:
+
+
+
+
+
escaped character
description
+
+
+
\n
+
the line-feed character (ASCII 10)
+
+
+
+
+
\r
+
the carriage-return character (ASCII 13)
+
+
+
+
\t
+
the tab character (ASCII 9)
+
+
+
+
+
\nnn
+
where nnn is a decimal ASCII code between 000 and 255
+
+
+
+
+
+
+
+example:
+
+
+(print (set 'res (+ 1 2 3)))
+(print "the result is" res "\n")
+
+"\065\066\067" → "ABC"
+
+
+
+
+ To finish printing with a line feed,
+ use println.
+
+
+
+
+
+
println
+syntax: (println exp-1 [exp-2 ... ])
+
+
+ Evaluates and prints exp-1—
+ to the current I/O device,
+ which defaults to the console window.
+ A line feed is printed at the end.
+ See the built-in function device for details on how to specify a different I/O device.
+ println works exactly like print but emits a line-feed character at the end.
+
+ Returns the probability Q of an observed Chi²
+ statistic in num-chi2 with num-df degrees of freedom to be equal to or greater than.
+ prob-chi2 is derived from the incomplete Gamma function gammai.
+
+ Returns the probability of num-z,
+ not to exceed the observed value where num-z is a normal distributed value with a mean of 0.0 and a standard deviation of 1.0.
+
+ In the first syntax,
+ process launches a process specified in str-command and immediately returns with the
+ process ID or nil if a the process could not be created. On Mac OS X and other UNIX, the application
+ or script must be specified with its full path-name. The new process inherits the OS envrionment from the
+ parent process.
+
+
+
Command line arguments are parsed out at spaces. Arguments containing spaces must be delimited using
+ single quotes on Mac OS X and other UNIX. On Win32 double quotes are used. The process id returned
+ can be used to destroy the running process using destroy, if the process does
+ not exit by itself.
+
+
+example:
+
+
+(process "notepad") → 1894 ; on Win32
+
+
+
+
+ In the second syntax,
+ standard input and output of the created process can be redirected to pipe handles.
+ When remapping standard I/O of the launched application to a pipe,
+ it is possible to communicate with the other application via write-line and read-line or write-buffer and read-buffer statements:
+
+
+example:
+
+
+;; Linux/UNIX
+;; create pipes
+(map set '(myin bcout) (pipe))
+(map set '(bcin myout) (pipe))
+
+;; launch UNIX 'bc' calculator application
+(process "/usr/bin/bc" bcin bcout) → 7916
+
+(write-buffer myout "3 + 4\n") ; bc expects a linefeed
+
+(read-line myin) → "7"
+
+
+;; bc can use bignums with arbitrary precision
+
+(write-buffer myout "123456789012345 * 123456789012345\n")
+
+(read-line myin) → "15241578753238669120562399025"
+
+;; destroy the process
+(destroy 7916)
+
+;; Win32
+(map set '(myin cmdout) (pipe))
+(map set '(cmdin myout) (pipe))
+
+(process "cmd" cmdin cmdout) ; Win32 command shell
+
+(write-line "dir c:\\*.bat" myout)
+
+(read-buffer myin 'buff 2000)
+
+(println buff) ; directory listing
+
+
+
+
+ On Win32 versions of newLISP,
+ a fourth optional parameter of int-win32-option can be specified to control the display status of the application.
+ This option defaults to 1 for showing the application's window,
+ 0 for hiding it,
+ and 2 for showing it minimized on the Windows launch bar.
+
+
+
+ On both Win32 and Linux/UNIX systems,
+ standard error will be redirected to standard out by default.
+ On Linux/UNIX,
+ an optional pipe handle for standard error output can be defined.
+ In this case,
+ peek can be used to check for information on the pipe handles:
+
+
+
+
+;; create pipes
+(map set '(myin bcout) (pipe))
+(map set '(bcin myout) (pipe))
+(map set '(errin errout) (pipe))
+
+;; launch UNIX 'bc' calculator application
+(process "bc" bcin bcout errout)
+
+(write-buffer myout command)
+
+;; wait for bc sending result or error info
+(while (and (= (peek myin) 0)
+ (= (peek errin) 0)) (sleep 10))
+
+(if (> (peek errin) 0)
+ (println (read-line errin)))
+
+(if (> (peek myin) 0)
+ (println (read-line myin)))
+
+
+
+
+ Not all interactive console applications can have their standard I/O channels remapped.
+ Sometimes only one channel,
+ in or out,
+ can be remapped.
+ In this case,
+ specify 0 (zero) for the unused channel.
+ The following statement uses only the launched application's output:
+
+
+
+
+(process "app" 0 myout)
+
+
+
+
+ Normally,
+ two pipes are used:
+ one for communications to the child process and the other one for communications from the child process.
+
+
+
+ See also the pipe and share functions for inter-process communications and the semaphore function for synchronization of several processes.
+ See the fork function for starting separate newLISP threads on Linux/UNIX.
+
+
+
+
+
+
protected?
+
+syntax: (protected? sym)
+
+
Checks checks if a symbol in sym is protected. Protected symbols are built-in
+functions, context symbols and all symbols made constant using the constant
+function:
+ Inserts the value of exp into the list list.
+ If int-index is present,
+ the element is inserted at that index.
+ If the index is absent,
+ the element is inserted at index 0 (zero),
+ the first element.
+ push is a destructive operation that changes the contents of the target list.
+ The element inserted is returned.
+ See also Indexing elements of strings and lists.
+
+
+
+ If more than one int-index is present,
+ the indices are used to access a nested list structure.
+ Improper indices (those not matching list elements) are discarded.
+
+
+
+ The second version takes a list of list-indexes but is otherwise identical to the first.
+ In this way,
+ push works easily together with ref
+ and ref-all,
+ which return lists of indices.
+
+
+
+ If list does not contain a list,
+ list must contain a nil and will be initialized to the empty list.
+
+
+
+ Repeatedly using push to the end of a list
+ using -1 as the int-index
+ is optimized and as fast as pushing
+ to the front of a list
+ with no index at all.
+ This can be used to efficiently grow a list.
+
+
+example:
+
+
+; inserting in front
+(set 'pList '(b c)) → (b c)
+(push 'a pList) → a
+pList → (a b c)
+
+; insert at index
+(push "hello" pList 2) → "hello"
+pList → (a b "hello" c)
+
+; optimized appending at the end
+(push 'z pList -1) → z
+pList → (a b "hello" c z)
+
+; inserting lists in lists
+(push '(f g) pList) → (f g)
+pList → ((f g) a b "hello" c z)
+
+; inserting at negative index
+(push 'x pList -3) → x
+pList → ((f g) a b "hello" x c z)
+
+; using multiple indices
+(push 'h pList 0 -1) → h
+pList → ((f g h) a b "hello" x c z)
+
+; use indices in a list
+(set 'pList '(a b (c d () e)))
+
+(push 'x pList '(2 2 0)) → x
+pList → (a b (c d (x) e))
+
+(ref 'x pList) → (2 2 0)
+
+(pop pList '(2 2 0)) → x
+
+;; push on strings
+
+(set 'str "abcdefg")
+
+(push "hijk" str -1) → "hijk"
+str → "abcdefghijk"
+
+(push "123" str) → "123"
+str → "123abcdefghijk"
+
+(push "4" str 3) → "4"
+str → "1234abcdefghijk"
+
+; push on uninitialized symbol
+aVar → nil
+
+(push 999 aVar) → 999
+
+aVar → (999)
+
+
+
+
+ See also the pop function,
+ which is the inverse operation to push,
+ and the set-nth,
+ nth-set,
+ and nth functions,
+ which can all take multidimensional indices into lists.
+
+ The HTTP PUT protocol is used to transfer information in str-content to a file specified in str-url.
+ The lesser-known HTTP PUT mode is frequently used for transferring web pages from HTML editors to Web servers.
+ In order to use PUT mode,
+ the web server's software must be configured correctly.
+ On the Apache web server,
+ use the 'Script PUT' directive in the section where directory access rights are configured.
+
+
+
+ Optionally,
+ an int-timeout value can be specified in milliseconds as the last parameter.
+ put-url will return ERR:
+ timeout when the host gives no response and the timeout expires.
+ On other error conditions,
+ put-url returns a string starting with ERR: and the description of the error.
+
+
+
+ put-url requests are also understood by newLISP server nodes.
+
+ The first example creates a file called myFile.txt on the target server and stores the text string 'Hi there' in it.
+ In the second example,
+ the local file webpage.html is transferred to asite.com.
+
+
+
+ On an Apache web server,
+ the following could be configured in httpd.conf.
+
+
+example:
+
+
+<directory /www/htdocs>
+Options All
+Script PUT /cgi-bin/put.cgi
+</directory>
+
+
+
+
+ The script put.cgi would contain code to receive content from the web server via STDIN.
+ The following is a working put.cgi written in newLISP for the Apache web server:
+
+
+example:
+
+#!/usr/home/johndoe/bin/newlisp
+#
+#
+# get PUT method data from CGI STDIN
+# and write data to a file specified
+# int the PUT request
+#
+#
+
+
+(print "Content-type: text/html\n\n")
+
+(set 'cnt 0)
+(set 'result "")
+
+(if (= "PUT" (env "REQUEST_METHOD"))
+ (begin
+ (set 'len (integer (env "CONTENT_LENGTH")))
+
+ (while (< cnt len)
+ (set 'n (read-buffer (device) 'buffer len))
+ (if (not n)
+ (set 'cnt len)
+ (begin
+ (inc 'cnt n)
+ (write-buffer result buffer))))
+
+ (set 'path (append
+ "/usr/home/johndoe"
+ (env "PATH_TRANSLATED")))
+
+ (write-file path result)
+ )
+)
+
+(exit)
+
+
+
+
+ Note that the script appends ".txt" to the path to avoid the CGI execution of uploaded malicious scripts.
+ Note also that the two lines where the file path is composed may work differently in your web server environment.
+ Check environment variables passed by your web server for composition of the right file path.
+
+
+
+ put-url returns content returned by the put.cgi script.
+
+
+
Additional parameters
+
+ In str-option,
+ "header" or "list" can be specified for the returned page.
+ If the int-timeout option is specified,
+ the custom header option str-header can be specified,
+ as well.
+ See the function get-url for details on both of these options.
+
+
+
+ See also the functions get-url and post-url,
+ which can be used to upload files when formatting form data as multipart/form-data.
+
+ Calculates the present value of a loan with the constant interest rate num-interest and the constant payment num-pmt after num-nper number of payments.
+ The future value num-pmt is assumed to be 0.0 if omitted.
+ If payment is at the end of each period,
+ 0 (zero) is assumed for int-type;
+ otherwise 1 is assumed.
+
+
+example:
+
+
+(pv (div 0.07 12) 240 775.30) → -100000.1373
+
+
+
+ In the example,
+ a loan that would be paid off (future value = 0.0) in 240 payments of $775.30 at a constant interest rate of 7 percent per year would start out at $100,000.14.
+
+
+
+ See also the fv,
+ irr,
+ nper,
+ npv,
+ and pmt functions.
+
+
+
+
+
+
+
quote
+syntax: (quote exp)
+
+
+ Returns exp without evaluating it.
+ The same effect can be obtained by prepending a ' (single quote) to exp.
+
+
+example:
+
+
+(quote x) → x
+(quote 123) → 123
+(quote (a b c)) → (a b c)
+(= (quote x) 'x) → true
+
+
+
+
+
+
quote?
+syntax: (quote? exp)
+
+
+ Evaluates and tests whether exp is quoted.
+ Returns true or nil depending on the result.
+
+
+example:
+
+
+(set 'var ''x) → 'x
+(quote? var) → true
+
+
+
+ Note that in the set statement,
+ ''x is quoted twice because the first quote is lost during the evaluation of the set assignment.
+
+
+
+
+
+
rand
+syntax: (rand int-range [int-N])
+
+
+ Evaluates the expression in int-range
+ and generates a random number in the range of
+ 0 (zero) to (int-range - 1).
+ When 0 (zero) is passed,
+ the internal random generator
+ is initialized using
+ the current value returned by
+ the C time() function.
+ Optionally, a second parameter
+ can be specified to return
+ a list of length int-N
+ of random numbers.
+
+ The first line in the example
+ prints equally distributed 0's and 1's,
+ while the second line produces a list
+ of 100 integers with
+ 0, 1, and 2 equally distributed.
+ Use the random
+ and normal functions
+ to generate floating point
+ random numbers,
+ and use seed to vary
+ the initial seed
+ for random number generation.
+
+ In the first form,
+ random returns a list of int-n
+ evenly distributed floating point numbers
+ scaled (multiplied) by float-scale,
+ with an added offset of float-offset.
+ The starting point of the internal random generator
+ can be seeded using seed.
+
+ Rearranges the order of elements in list
+ into a random order.
+
+
+example:
+
+
+(randomize '(a b c d e f g)) → (b a c g d e f)
+(randomize (sequence 1 5)) → (3 5 4 1 2)
+
+
+
+
+ randomize will always return
+ a sequence different from the previous one
+ without the optional bool flag.
+ This may require the function to calculate
+ several sets of reordered elements,
+ which in turn may lead to different processing times
+ with different invocations of the function
+ on the same input list length.
+ To allow for the output to be equal
+ to the input, true
+ or any expression evaluating to
+ not nil
+ must be specified in bool.
+
+
+
+ randomize uses
+ an internal pseudo random sequence generator
+ that returns the same series of results
+ each time newLISP is started.
+ Use the seed function to
+ change this sequence.
+
+ Reads a maximum of int-size bytes
+ from a file specified in int-file
+ into a buffer in sym-buffer.
+ Any data referenced by the symbol sym-buffer
+ prior to the reading is deleted.
+ The handle in int-file
+ is obtained from a previous open statement.
+ The symbol sym-buffer contains data
+ of type string after the read operation.
+
+
+
+ Optionally,
+ a string to be waited for
+ can be specified in str-wait.
+ read-buffer will read
+ a maximum amount of bytes
+ specified in int-size
+ or return earlier
+ if str-wait was found
+ in the data.
+ The wait-string is part
+ of the returned data and must
+ not contain binary 0 (zero)
+ characters.
+
+
+
+ Returns the number of bytes read or nil
+ when the wait-string was not found.
+ In any case,
+ the bytes read are put into the buffer
+ pointed to by sym-buffer,
+ and the file pointer of the file read
+ is moved forward.
+ If no new bytes have been read,
+ sym-buffer will contain nil.
+
+ Reads a byte from a file specified
+ by the file handle in int-file.
+ The file handle is obtained from
+ a previous open operation.
+ Each read-char advances
+ the file pointer by one byte.
+ Once the end of the file is reached,
+ nil is returned.
+
+ Use read-line
+ and device to read
+ whole text lines at a time.
+ Note that newLISP supplies
+ a fast built-in function
+ called copy-file
+ for copying files.
+
+ The file myfile is read,
+ then encrypted using the password "secret"
+ before being written back into a new file titled "myfile.enc"
+ in the current directory.
+
+
+
+ read-file can take an http://
+ or file:// URL in str-file-name.
+ In this case, read-file works exactly like
+ get-url and can take
+ the same additional parameters.
+
+ The file somefile.tgz is retrieved from
+ the remote location http://asite.com.
+ The file transfer will time out after 10 seconds
+ if it is not finished.
+ In this mode, read-file can also be used
+ to transfer files from remote newLISP server nodes.
+ Reads a key from the keyboard
+ and returns an integer value.
+ For navigation keys,
+ more than one read-key call
+ must be made.
+ For keys representing ASCII characters,
+ the return value is the same
+ on all OSes, except for navigation keys
+ and other control sequences like function keys,
+ in which case the return values may vary
+ on different OSes and configurations.
+
+
+
+example:
+
+
+(read-key) → 97 ; after hitting the A key
+(read-key) → 65 ; after hitting the shifted A key
+(read-key) → 10 ; after hitting [enter] on Linux
+(read-key) → 13 ; after hitting [enter] on Win32
+
+(while (!= (set 'c (read-key)) 1) (println c))
+
+
+
+
+ The last example can be used
+ to check return sequences
+ from navigation and function keys.
+ To break out of the loop,
+ press Ctrl-A.
+
+
+
+ Note that read-key will not work
+ from the newLISP-GS front-end
+ or any other application running
+ newLISP over a TCP/IP port connection.
+
+
+
+
+
+
+
read-line
+syntax: (read-line [int-file])
+
+
+ Reads from the current I/O device a string
+ delimited by a line-feed character (ASCII 10).
+ There is no limit
+ to the length of the string
+ that can be read.
+ The line-feed character is not part of the returned string.
+ The line always breaks on a line feed,
+ which is then swallowed.
+ A line breaks on a carriage return (ASCII 13)
+ only if followed by a line feed,
+ in which case both characters are discarded.
+ A carriage return alone only breaks and is swallowed
+ if it is the last character in the stream.
+
+
+
+ By default,
+ the current device
+ is the keyboard (device 0).
+ Use the built-in function device
+ to specify a different I/O device (e.g., a file).
+ Optionally,
+ a file handle can be specified
+ in the int-file obtained
+ from a previous open statement.
+
+
+
+ The last buffer contents
+ from a read-line operation
+ can be retrieved using current-line.
+
+ The first example reads input from the keyboard
+ and converts it to a number.
+ In the second example,
+ a file is read line by line
+ and displayed on the screen.
+ The write-line statement
+ takes advantage of the fact
+ that the result from the last
+ read-line operation
+ is stored in a system internal buffer.
+ When write-line
+ is used without argument,
+ it writes the contents
+ of the last read-line buffer
+ to the screen.
+
+
+
+ See also the current-line function
+ for retrieving this buffer.
+
+
+
+
+
real-path
+syntax: (real-path [str-path])
+
+
+ Returns the full path
+ from the relative file path
+ given in str-path.
+ If a path is not given,
+ "." (the current directory) is assumed.
+
+ The output length is limited
+ by the OS's maximum allowed path length.
+ If real-path fails
+ (e.g., because of a nonexistent path),
+ nil is returned.
+
+ ref searches for the key expression exp-key
+ in list and returns a list of integer indices
+ or an empty list if exp-key cannot be found.
+ ref can work together with push
+ and pop,
+ both of which can also take lists of indices.
+
+
+
+The optional func-compare
+contains a comparison operator
+or function. In this case the system variable $0 contains
+the last expression found.
+
+example:
+
+
+(set 'pList '(a b (c d () e)))
+
+(push 'x pList '(2 2 0)) → x
+
+pList → (a b (c d (x) e))
+
+(ref 'x pList) → (2 2 0)
+
+; or form suitable for context default functors
+(ref (pList 'x) → (2 2 0)
+
+(ref '(x) pList) → (2 2)
+
+(set 'v (ref '(x) pList)) → (2 2)
+
+(pList v) → (x)
+
+(ref '(c d (x) e) pList) → (2)
+
+(ref 'foo pList) → ()
+
+(pop pList '(2 2 0)) → x
+
+; with optional comparison function
+
+(ref 'e '(a b (c d (e) f))) → (2 2 0)
+
+(ref 'e '(a b (c d (e) f)) =) → (2 2 0)
+$0 → e
+
+(ref 'e '(a b (c d (e) f)) >) → (0)
+$0 → a
+
+(ref 'e '(a b (c d (e) f)) (fn (x y) (or (= x y) (= y 'd)))) → (2 1)
+$0 → d
+
+; define the comparison function first
+(define (is-it-or-d x y) (or (= x y) (= y 'd)))
+
+(ref 'e '(a b (c d (e) f)) is-it-or-d) → (2 1)
+$0 → d
+
+
+
+
+The following example shows the use of
+match and unify
+to formulate searches that are as powerful as regular expressions are
+for strings:
+
+
+
+
+(ref '(a ?) '((l 3) (a 12) (k 5) (a 10) (z 22)) match) → (1)
+$0 → (a 12)
+
+(ref '(X X) '( ((a b) (c d)) ((e e) (f g)) ) unify) → (1 0)
+$0 → (e e)
+
+(ref '(X g) '( ((a b) (c d)) ((e e) (f g)) ) unify) → (1 1)
+$0 → (f g)
+
+
+
+
+The first line searches for a list pair
+where the two elements are equal.
+The second searches for a list pair
+with the symbol g as the second member.
+
+
+
When using the second syntax, the list can be passed by a context
+identifying a default functor:
+
+
+
+(set 'L:L '(a b (c d) e f))
+
+(ref (L 'd)) → (2 1)
+
+
+
+
This is suitable when passing lists by reference using a context.
+ Works similarly to ref,
+ but returns a list of all index vectors found
+ for exp in list.
+
+
+
+By default, ref-all checks if expressions are equal.
+With func-compare, more complex comparison functions
+can be defined.
+
+
+example:
+
+
+(set 'L '(a b c (d a f (a h a)) (k a (m n a) (x))))
+
+(ref-all 'a L) → ((0) (3 1) (3 3 0) (3 3 2) (4 1) (4 2 2))
+
+(L '(3 1)) → a
+
+(map 'L (ref-all 'a L)) → (a a a a a a)
+
+; with comparison operator
+
+(set 'L '(a b c (d f (h l a)) (k a (m n) (x))))
+
+(ref-all 'c L) → ((2))
+
+(ref-all 'c L >) → ((0) (1) (3 2 2) (4 1))
+
+(ref-all 'a L (fn (x y) (or (= x y) (= y 'k))))
+→ ((0) (3 2 2) (4 0) (4 1))
+
+(ref-all nil L (fn (x y) (> (length y) 2)))
+→ ((3) (3 2) (4))
+
+; define the comparison functions first
+(define (is-long? x y) (> (length y) 2)) ; the x gets occupied by 'nil
+
+(ref-all nil L is-long?) → ((3) (3 2) (4))
+
+(define (is-it-or-d x y) (or (= x y) (= y 'd)))
+
+(ref-all 'e '(a b (c d (e) f)) is-it-or-d) → ((2 1) (2 2 0))
+
+
+
+
+The comparison function can be a previously defined function.
+Note that the comparison function always takes two arguments,
+even if only the second argument is used
+inside the function (as in the example using long?).
+
+
+
+Using the match
+and unify functions,
+list searches can be formulated that are as powerful
+as regular expression searches are for strings.
+
+
+
+
+(ref-all '(a ?) '((l 3) (a 12) (k 5) (a 10) (z 22)) match)
+→ ((1) (3))
+
+(ref-all '(X X) '( ((a b) (c d)) ((e e) (f g)) ((z) (z))) unify)
+→ ((1 0) (2))
+
+(ref-all '(X g) '( ((x y z) g) ((a b) (c d)) ((e e) (f g))) unify)
+→ ((0) (2 1))
+
Searches for exp-key in list and replaces the found element with exp-replacement.
+The list can be nested. The system variable $0 contains the expression found
+and can be used in exp-replacement. The function returns the old replaced element.
For examples on how to use func-compare see set-ref-all
+
+
See also set-ref which returns the whole changed list
+instead of the old element, but else works identical. For changing all
+occurences of an element in a list use set-ref-all.
+ Performs a Perl Compatible Regular Expression (PCRE) search
+ on str-text with the pattern specified in str-pattern.
+ The same regular expression pattern matching
+ is also supported in the functions directory,
+ find, find-all,
+ parse, replace,
+ and search when using these functions on strings.
+
+
+
+ regex returns a list with the matched strings and substrings
+ and the beginning and length of each string inside the text.
+ If no match is found, it returns nil.
+ The offset numbers can be used for subsequent processing.
+
+
+
+ regex also sets the variables $0, $1,
+ and $2—
+ to the expression and subexpressions found.
+ Just like any other symbol in newLISP,
+ these variables or their equivalent expressions
+ $0, $1, and $2— can be used in other
+ LISP expressions for further processing.
+
+ The second example shows the usage of extra options,
+ while the third example demonstrates more complex parsing of two subexpressions,
+ which where marked by parentheses in the search pattern.
+ In the last example,
+ the expression and subexpressions are retrieved using the system variables $0 to $2 or their equivalent expression ($ 0) to ($ 2).
+
+
+
+ When "" (quotes) are used
+ to delimit strings
+ that include literal backslashes,
+ the backslash must be doubled in the regular expression pattern.
+ As an alternative, { } (curly brackets)
+ or [text] and [/text] (text tags)
+ can be used to delimit text strings.
+ In these cases, no extra backslashes are required.
+
+
+
+ Characters escaped by a backslash in newLISP
+ (e.g., the quote \" or \n)
+ need not to be doubled in a regular expression pattern,
+ which itself is delimited by quotes.
+
+
+
+
+;; double backslash for parentheses (special char in regex)
+(regex "\\(abc\\)" "xyz(abc)xyz") → ("(abc)" 3 5)
+
+;; one backslash for quotes (special char in newLISP)
+(regex "\"" "abc\"def") → ("\"" 3 1)
+
+;; brackets as delimiters
+(regex {\(abc\)} "xyz(abc)xyz") → ("(abc)" 3 5)
+
+;; brackets as delimiters and quote in pattern
+(regex {"} "abc\"def") → ("\"" 3 1)
+
+;; text tags as delimiters, good for multiline text in CGI
+(regex [text]\(abc\)[/text] "xyz(abc)xyz") → ("(abc)" 3 5)
+(regex [text]"[/text] "abc\"def") → ("\"" 3 1)
+
+
+
+
+ When curly brackets or text tags
+ are used to delimit the pattern string
+ instead of quotes,
+ a simple backslash is sufficient.
+ The pattern and string are then passed in raw form
+ to the regular expression routines.
+ When curly brackets are used inside a pattern
+ itself delimited by curly brackets,
+ the inner brackets must be balanced, as follows:
+
+ The following constants can be used for int-option.
+ Several options can be combined using a binary or | (pipe).
+ The uppercase names are used in the PCRE regex documentation and could be predefined in init.lsp.
+ The last option is a newLISP custom option only to be used in replace;
+ it can be combined with PCRE options.
+
+
+
+ PCRE_CASELESS 1 ; treat uppercase like lowercase
+ PCRE_MULTILINE 2 ; limit search at a newline like Perl's /m
+ PCRE_DOTALL 4 ; . (dot) also matches newline
+ PCRE_EXTENDED 8 ; ignore whitespace except inside char class
+ PCRE_ANCHORED 16 ; anchor at the start
+ PCRE_DOLLAR_ENDONLY 32 ; $ matches at end of string, not before newline
+ PCRE_EXTRA 64 ; additional functionality currently not used
+ PCRE_NOTBOL 128 ; first ch, not start of line; ^ shouldn't match
+ PCRE_NOTEOL 256 ; last char, not end of line; $ shouldn't match
+ PCRE_UNGREEDY 512 ; invert greediness of quantifiers
+ PCRE_NOTEMPTY 1024 ; empty string considered invalid
+ PCRE_UTF8 2048 ; pattern and strings as UTF-8 characters
+
+ REPLACE_ONCE 0x8000 ; replace only one occurrence
+ ; only for use in replace
+
+
+
+ Note that regular expression syntax is very complex
+ and feature-rich with many special characters and forms.
+ Please consult a book or the PCRE manual pages for more detail.
+ Most PERL books or introductions to Linux or UNIX
+ also contain chapters about regular expressions.
+ See also http://www.pcre.org
+ for further references and manual pages.
+
+
+
+
+
+
+
remove-dir
+syntax: (remove-dir str-path)
+
+
+ Removes the directory
+ whose path name is specified in str-path.
+ The directory must be empty for remove-dir to succeed.
+ Returns nil on failure.
+
+
+example:
+
+
+(remove-dir "temp")
+
+
+
+
+ Removes the directory temp
+ in the current directory.
+
+ Renames a file or directory entry
+ given in the path name str-path-old
+ to the name given in str-path-new.
+ Returns nil or true
+ depending on the operation's success.
+
+ If the second argument is a list,
+ replace replaces all elements in the list list
+ that are equal to the expression in exp-key.
+ The element is replaced with exp-replacement.
+ Note that replace is destructive. It
+ changes the list passed to it and
+ returns the changed list.
+ The number of replacements made
+ is contained in the system variable $0 when the function returns.
+ During executions of the replacement expression,
+ the system variable $0
+ is set to the expression to be replaced.
+
+
+
+Optionally, func-compare can specify a comparison operator
+or user-defined function.
+By default, func-compare is the = (equals sign).
+
+
+example:
+
+
+;; list replacement
+
+(set 'aList '(a b c d e a b c d))
+
+(replace 'b aList 'B) → (a B c d e a B c d)
+aList → (a B c d e a B c d)
+$0 → 2 ; number of replacements
+
+;; list replacement with special compare functor/function
+
+; replace all numbers where 10 < number
+(set 'L '(1 4 22 5 6 89 2 3 24))
+
+(replace 10 L 10 <) → (1 4 10 5 6 10 2 3 10)
+
+; same as:
+
+(replace 10 L 10 (fn (x y) (< x y))) → (1 4 10 5 6 10 2 3 10)
+
+; change name-string to symbol, x is ignored as nil
+
+(set 'AL '((john 5 6 4) ("mary" 3 4 7) (bob 4 2 7 9) ("jane" 3)))
+
+(replace nil AL (cons (sym ($0 0)) (rest $0))
+ (fn (x y) (string? (y 0))))
+→ ((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3))
+
+
+
+
+Using the match and unify functions,
+list searches can be formulated that are as powerful as regular expression string searches:
+ The last form of replace has only two arguments:
+ the expression expr and list.
+ This form removes all exprs found in list.
+
+
+example:
+
+
+;; removing elements from a list
+
+(set 'lst '(a b a a c d a f g))
+(replace 'a lst) → (b c d f g)
+lst → (b c d f g)
+
+$0 → 4
+
+
+
+
+
+
String replacement without regular expression
+
+ If all arguments are strings,
+ replace replaces all occurrences
+ of str-key in str-data
+ with the evaluated exp-replacement,
+ returning the changed string.
+ The expression in exp-replacement
+ is evaluated for every replacement.
+ The number of replacements made
+ is contained in the system variable $0.
+ This form of replace
+ can also process binary 0s (zeros).
+
+
+example:
+
+
+;; string replacement
+(set 'str "this isa sentence")
+(replace "isa" str "is a") → "this is a sentence"
+
+
+
+
+
+
Regular expression replacement
+
+ The presence of a fourth parameter
+ indicates that a regular expression search
+ should be performed with a regular expression pattern
+ specified in str-pattern
+ and an option number specified in int-option
+ (e.g., 1 (one) for case-insensitive searching
+ or 0 (zero) for a standard
+ Perl Compatible Regular Expression (PCRE) search).
+ See regex above for details.
+
+
+
+ By default, replace replaces all occurrences
+ of a search string even if a beginning-of-line specification
+ is included in the search pattern.
+ After each replace,
+ a new search is started at a new position in str-data.
+ Setting the option bit to 0x8000 in int-option
+ will force replace to replace only the first occurrence.
+ The changed string is returned.
+
+
+
+ replace with regular expressions
+ also sets the internal variables
+ $0, $1, and $2—
+ with the contents of the expressions
+ and subexpressions found.
+ These can be used to perform replacements
+ that depend on the content found during replacement.
+ The symbols $0, $1, and $2— can be used
+ in expressions just like any other symbols.
+ If the replacement expression
+ evaluates to something other than a string,
+ no replacement is made.
+ As an alternative,
+ the contents of these variables can also be accessed
+ by using ($ 0), ($ 1), ($ 2), and so forth.
+ This method allows indexed access
+ (e.g., ($ i),
+ where i is an integer).
+
+
+
After all replacements are made, the number of replacements
+is contained in the system variable $0.
+
+
+example:
+
+
+;; using the option parameter to employ regular expressions
+
+(set 'str "ZZZZZxZZZZyy") → "ZZZZZxZZZZyy"
+(replace "[x|y]" str "PP" 0) → "ZZZZZPPZZZZPPPP"
+str → "ZZZZZPPZZZZPPPP"
+
+;; using system variables for dynamic replacement
+
+(set 'str "---axb---ayb---")
+(replace "(a)(.)(b)" str (append $3 $2 $1) 0)
+→ "---bxa---bya---"
+
+str → "---bxa---bya---"
+
+;; using the 'replace once' option bit 0x8000
+
+(replace "a" "aaa" "X" 0) → "XXX"
+
+(replace "a" "aaa" "X" 0x8000) → "Xaa"
+
+;; URL translation of hex codes with dynamic replacement
+
+(set 'str "xxx%41xxx%42")
+(replace "%([0-9A-F][0-9A-F])" str
+ (char (integer (append "0x" $1))) 1)
+
+str → "xxxAxxxB"
+
+$0 → 2
+
+
+
+
+ The set-nth and
+ set-assoc functions
+ can also be used to change an element in a list.
+
The function set-assoc behaves like the older replace-assoc
+replacing an association with exp-key in the association list list-assoc
+with exp-replacement. An association list is a list
+whose elements are in turn lists, the first element serving as a key.
+
+example:
+
+
+(set 'aList '((a 1 2 3) (b 4 5 6) (c 7 8 9)))
+
+(set-assoc (aList 'b) '(q "the replacement"))
+→ ((a 1 2 3) (q "the replacement") (c 7 8 9))
+
+aList → ((a 1 2 3) (q "I am the replacement") (c 7 8 9))
+
+
+
+
set-assoc uses the system variable $0 for the association found.
+This can be used in the replacement expression:
+See also the assoc function
+for accessing association lists. assoc-set works like set-assoc
+but returns the old association element instead of the entire list. To remove associations
+use pop-assoc.
+
Note that this function is deprecated and will be removed in a future version. Use
+set-assoc or pop-assoc instead. This
+new functions also handle multiple keys for accessing elements in nested association
+lists.
+
+
+In the first syntax, replace-assoc replaces an association element with exp-key
+in the association list-assoc with exp-replacement.
+In the second syntax, replace-assoc removes an association from the list and returns it.
+
+
+
+
+
+
reset
+syntax: (reset)
+syntax: (reset true)
+
+
+ In the first syntax,
+ reset returns to the top level of evaluation,
+ switches the trace mode off,
+ turns the command-line mode on,
+ and switches to the MAIN context/namespace.
+ reset restores the top-level variable environment
+ using the saved variable environments on the stack.
+ It also fires an error "user reset - no error".
+ This behavior can be used when writing error handlers.
+
+
+
+ reset may return memory
+ that was claimed by newLISP
+ to the operating system.
+ reset walks through the entire cell space,
+ which may take a few seconds in a heavily loaded system.
+
+
+
+ reset occurs automatically after an error condition.
+
+
+
+ In the second syntax,
+ reset will stop the current process
+ and start a new clean newLISP process
+ with the same command-line parameters.
+ This mode will only work when newLISP was started
+ using its full path-name, e.g. /usr/bin/newlisp
+ instead of only newlisp.
+ This mode is not available on Win32.
+
+syntax: (rotate list [int-count])
+syntax: (rotate str [int-count])
+
+
+ Rotates and returns
+ the list or string in str.
+ A count can be optionally specified in int-count
+ to rotate more than one position.
+ If int-count is positive,
+ the rotation is to the right;
+ if int-count is negative,
+ the rotation is to the left.
+ If no int-count is specified,
+ rotate rotates 1 to the right.
+ rotate is a destructive function
+ that changes the contents of
+ the original list or string.
+
+ When working on a string,
+ rotate works on byte boundaries
+ rather than character boundaries.
+
+
+
+
+
+
round
+syntax: (round number [int-digits])
+
+
Rounds the number in number
+to the number of digits given in int-digits.
+When decimals are being rounded, int-digits is negative.
+It is positive when the integer part of a number is being rounded.
+
+
If int-digits is omitted, the function rounds to 0 decimal
+digits.
+ In the first syntax,
+ the save function writes
+ the contents of the newLISP workspace
+ (in textual form) to the file str-file.
+ save is the inverse function of load.
+ Using load on files
+ created with save causes
+ newLISP to return to the same state
+ as when save was originally invoked.
+ System symbols starting with the $ character
+ (e.g., $0 from regular expressions
+ or $main-args from the command line)
+ are not saved.
+
+
+
+ In the second syntax,
+ symbols can be supplied as arguments.
+ If sym-n is supplied,
+ only the definition of that symbol is saved.
+ If sym-n evaluates to a context,
+ all symbols in that context are saved.
+ More than one symbol can be specified,
+ and symbols and context symbols can be mixed.
+ When contexts are saved,
+ system variables and symbols starting with the $ character
+ are not saved.
+ Specifying system symbols explicitly
+ causes them to be saved.
+
+
+
+ Each symbol is saved
+ by means of a set statement or—if
+ the symbol contains a lambda or lambda-macro function—by
+ means of define
+ or define-macro statements.
+
+ Since all context symbols are part of the context MAIN,
+ saving MAIN saves all contexts.
+
+
+
+ Saving to a URL
+ will cause an HTTP PUT request send to the URL.
+ In this mode,
+ save can also be used
+ to push program source
+ to remote newLISP server nodes.
+ Note that a double backslash is required
+ when path names are specified
+ relative to the root directory.
+ save in HTTP mode will
+ observe a 60-second timeout.
+
+
+
+ Symbols made using sym
+ that are incompatible with the normal syntax rules for symbols
+ are serialized using a sym statement
+ instead of a set statement.
+
+
+
+ save serializes contexts and symbols
+ as if the current context is MAIN.
+ Regardless of the current context,
+ save will always generate the same output.
+
+
+
+ See also the functions load
+ (the inverse operation of save)
+ and source,
+ which saves symbols and contexts to a string
+ instead of a file.
+
+Searches a file specified by its handle in int-file for a string in str-search.
+int-file can be obtained from a previous open file. After the search,
+the file pointer is positioned at the beginning or the end of the searched string or at the end
+of the file if nothing is found.
+
+
If bool-flag evaluates to nil or if bool-flag is missing,
+then the filepointer is positioned at the beginning of the searched string, else at the end
+of the searched string.
+
In int-options, the options flags can be specified to perform
+a PCRE regular expression search. See the function regex for details.
+If int-options is mot specified a faster, plain string search is performed.
+search returns the new file position or nil if nothing is found.
+
+
+
When using the regular expression options flag, patterns found are stored in the system variables
+$0 to $15.
The file init.lsp is opened and searched for the string define and the
+line in which the string occurs is printed.
+
+
The second example looks for all lines in the file program.c which start with
+the string #define and prints the rest of the line after the string "#define ".
+ Seeds the internal random generator
+ that generates numbers for amb,
+ normal,
+ rand,
+ and random
+ with the number specified in int-seed.
+ Note that the random generator used in newLISP
+ is the C-library function rand().
+ All randomizing functions in newLISP
+ are based on this function.
+
+
+
+ Note that the maximum value for int-seed
+ is limited to 16 or 32 bits,
+ depending on the operating system used.
+ Internally,
+ only the 32 least significant bits are passed
+ to the random seed function of the OS.
+
+
+example:
+
+
+(seed 12345)
+
+(seed (date-value))
+
+
+
+
+ After using seed with the same number,
+ the random generator starts the same sequence of numbers.
+ This facilitates debugging
+ when randomized data are involved.
+ Using seed,
+ the same random sequences can be generated
+ over and over again.
+
+
+
+ The second example is useful for guaranteeing
+ a different seed any time the program starts.
+
+
+
+
+
+
seek
+syntax: (seek int-file [int-position])
+
+
+ Sets the file pointer to the new position int-position
+ in the file specified by int-file.
+ The new position is expressed as an offset from
+ the beginning of the file,
+ 0 (zero) meaning the beginning of the file.
+ If no int-position is specified,
+ seek returns the current position in the file.
+ If int-file is 0 (zero),
+ on BSD, seek will return
+ the number of characters
+ printed to STDOUT,
+ and on Linux and Win32,
+ it will return -1.
+ On failure,
+ seek returns nil.
+ When int-position is set to -1,
+ seek sets the file pointer
+ to the end of the file.
+
+
+
seek can set the file position past the current end of the file. Subsequent
+writing to this position will extend the file and fill unused positions with zero's.
+The blocks of zeros are not actually allocated on disk, so the file takes up less
+space and is called a sparse file.
+ In the first two forms,
+ select picks one or more elements
+ from list using one or more indices
+ specified in list-selection or the int-index_i.
+
+
+example:
+
+
+(set 'lst '(a b c d e f g))
+
+(select lst '(0 3 2 5 3)) → (a d c f d)
+
+(select lst '(-2 -1 0)) → (f g a)
+
+(select lst -2 -1 0) → (f g a)
+
+
+
+
+ In the second two forms,
+ select picks one or more characters
+ from string
+ using one or more indices specified in list-selection
+ or the int-index_i.
+
+ Selected elements can be repeated and do not have to appear in order,
+ although this speeds up processing.
+ The order in list-selection or int-index_i
+ can be changed to rearrange elements.
+
+ A semaphore is an interprocess synchronization object
+ that maintains a count between 0 (zero) and some maximum value.
+ Useful in controlling
+ access to a shared resource,
+ a semaphore is set to signaled
+ when its count is greater than zero
+ and to non-signaled
+ when its count is zero.
+
+
+
+ A semaphore is created using the first syntax.
+ This returns the semaphore ID,
+ an integer used subsequently as int-id
+ when the semaphore function is called.
+ Initially, the semaphore has a value of zero, which
+ represents the non-signaled state.
+
+
+
+ If calling semaphore with a negative value in int-wait
+ causes it to be decremented below zero,
+ the function call will block until another process or thread
+ signals the semaphore with a positive value in int-signal.
+ Calls to the semaphore with int-wait or int-signal
+ effectively try to increment or decrement the semaphore value
+ by a positive or negative value specified in int-signal
+ or int-wait.
+ Because the value of a semaphore must never fall below zero,
+ the function call will block when this is attempted
+ (i.e., a semaphore with a value of zero
+ will block until another process or thread
+ increases the value with a positive int-signal).
+
+
+
+ The second syntax is used to inquire about the value of a semaphore
+ by calling semaphore with the int-id only.
+ This form is not available on Win32.
+
+
+
+ Supplying 0 (zero) as the last argument
+ will release system resources for the semaphore,
+ which then becomes unavailable.
+ Any pending waits on this semaphore
+ in other child threads or processes
+ will be released.
+
+
+
+ On Win32, only parent and child processes can share a semaphore.
+ On Linux/UNIX, independent processes can share a semaphore.
+
+
+
+ The following code examples summarize the different syntax forms:
+
+
+
+
+;; init semaphores
+(semaphore)
+
+;; assign a semaphore to sid
+(set 'sid (semaphore))
+
+;; inquire the state of a semaphore (not on Win32)
+(semaphore sid)
+
+;; put sid semaphore in wait state (-1)
+(semaphore sid -1)
+
+;; run sid semaphore previously put in wait (always 1)
+(semaphore sid 1)
+
+;; run sid semaphore with X times a skip (backward or forward) on the function
+(semaphore sid X)
+
+;; release sid semaphore systemwide (always 0)
+(semaphore sid 0)
+
+
+
+
+ The following example shows semaphores controlling a child process:
+
+
+example:
+
+
+;; counter thread output in bold
+
+(define (counter n)
+ (println "counter started")
+ (dotimes (x n)
+ (semaphore sid -1)
+ (println x)))
+
+;; hit extra <enter> to make the prompt come back
+;; after output to the console from counter thread
+
+> (set 'sid (semaphore))
+
+> (semaphore sid)
+0
+
+> (fork (counter 100))
+
+counter started
+> (semaphore sid 1)
+0
+> (semaphore sid 3)
+1
+2
+3
+> (semaphore sid 2)
+4
+
+5
+> _
+
+
+
+
+ After the semaphore is acquired in sid,
+ it has a value of 0
+ (the non-signaled state).
+ When starting the thread counter,
+ the semaphore will block after the initial start message
+ and will wait in the semaphore call.
+ The -1 is trying to decrement the semaphore,
+ which is not possible because its value is already zero.
+ In the interactive, main parent process,
+ the semaphore is signaled by raising its value by 1.
+ This unblocks the semaphore call in the counter thread,
+ which can now decrement the semaphore from 1 to 0
+ and execute the print statement.
+ When the semaphore call is reached again,
+ it will block because the semaphore is already in the wait
+ (0) state.
+
+
+
+ Subsequent calls to semaphore
+ with numbers greater than 1
+ give the counter thread an opportunity
+ to decrement the semaphore several times before blocking.
+
+
+
+ More than one thread can participate in controlling the semaphore,
+ just as more than one semaphore can be created.
+ The maximum number of semaphores is controlled
+ by a systemwide kernel setting on UNIX-like operating systems.
+
+
+
+ Use the fork function
+ to start a new thread
+ and the share function
+ to share information between threads.
+ For a more comprehensive example of
+ using semaphore to synchronize threads,
+ see the prodcons.lsp example
+ in the examples/ directory
+ in the source distribution,
+ as well as the examples and modules
+ distributed with newLISP.
+
+ Generates a sequence of numbers
+ from num-start to num-end
+ with an optional step size of num-step.
+ When num-step is omitted,
+ the value 1 (one) is assumed.
+ The generated numbers are of type integer
+ (when no optional step size is specified)
+ or floating point
+ (when the optional step size is present).
+
+ Creates a geometric sequence
+ with num-count elements
+ starting with the element in num-start.
+ Each subsequent element
+ is multiplied by num-factor.
+ The generated numbers
+ are always floating point numbers.
+
+
+
When num-count is less then 1 then series
+returns an empty list.
+ Use the sequence function
+ to generate arithmetic sequences.
+
+
+
+
+
+
set
+syntax: (set sym-1exp-1 [sym-2exp-2 ... ])
+
+
+ Evaluates both arguments and
+ then assigns the result of exp
+ to the symbol found in sym.
+ The set expression
+ returns the result of the assignment.
+ The assignment is performed by copying
+ the contents of the right side
+ into the symbol.
+ The old contents of the symbol
+ are deleted.
+ An error message results
+ when trying to change the contents
+ of the symbols nil, true,
+ or a context symbol.
+ set can take multiple argument pairs.
+
+ Symbols can be set to
+ lambda or lambda-macro expressions.
+ This operation is equivalent
+ to using define
+ or define-macro.
+
+
+
+
+(set 'double (lambda (x) (+ x x)))
+→ (lambda (x) (+ x x))
+
+
+
+
+ is equivalent to:
+
+
+
+
+(define (double x) (+ x x))
+→ (lambda (x) (+ x x))
+
+
+
+
+ is equivalent to:
+
+
+
+
+(define double (lambda (x) (+ x x)))
+→ (lambda (x) (+ x x))
+
+
+
+
+ Use the constant function
+ (which works like set)
+ to protect the symbol from subsequent alteration.
+ Using the setq function
+ eliminates the need to quote the variable symbol.
+
+
+
+
+
+
setq
+syntax: (setq sym-1exp-1 [sym-2exp-2 ... ])
+
+
+ Works just like set,
+ except the symbol in sym
+ is not quoted.
+ Like set,
+ setq can take multiple arguments.
+
+
+example:
+
+
+(setq x 123) → 123
+
+; multiple args
+
+(setq x 1 y 2 z 3) → 3
+
+x → 1
+y → 2
+z → 3
+
+ Reports or switches to a different locale
+ on your operating system or platform.
+ When used without arguments,
+ set-locale reports
+ the current locale being used.
+ When str-locale is specified,
+ set-locale switches to the locale
+ with all category options turned on
+ (LC_ALL).
+ Placing an empty string in str-locale
+ switches to the default locale
+ used on the current platform.
+ set-locale returns either the current settings
+ or nil if the requested change
+ could not be performed.
+
+
+example:
+
+
+(set-locale) ; report current locale
+
+(set-locale "") ; set default locale of your platform
+
+
+
+
+ By default,
+ newLISP starts up with the POSIX C default locale.
+ This guarantees that newLISP's behavior will be identical
+ on any platform locale:
+
+
+
+
+;; after newLISP start up
+
+(set-locale) → "C"
+
+
+
+
+ In int-category,
+ integer numbers may be specified
+ as category options
+ for fine-tuning certain aspects
+ of the locale,
+ such as number display,
+ date display, and so forth.
+ The numbers used vary from system to system.
+ The options valid on your platform
+ can be found in the C include file locale.h.
+ This file defines constants like
+ LC_ALL, LC_NUMERIC, and LC_MONETARY.
+ When set-locale is used without the option number,
+ it assumes the LC_ALL option,
+ which turns on all options for that locale.
+
+
+
+ Note that the locale also controls
+ the decimal separator in numbers.
+ The default C locale uses the decimal dot,
+ but most others use a decimal comma.
+ Since version 8.4.4,
+ newLISP has been parsing decimal comma numbers correctly.
+
+
+
+ Note that using set-locale
+ does not change the behavior
+ of regular expressions in newLISP.
+ To localize the behavior of PCRE
+ (Perl Compatible Regular Expressions),
+ newLISP must be compiled
+ with different character tables.
+ See the file, LOCALIZATION,
+ in the newLISP source distribution
+ for details.
+
+ set-nth works like nth-set,
+ except instead of returning the replaced element,
+ it returns the entire changed expression.
+ For this reason,
+ set-nth is slower on larger data objects.
+
+
Searches for exp-key in list and replaces the found element with exp-replacement.
+The list can be nested. The system variable $0 contains the expression found
+and can be used in exp-replacement. The function works like ref-set but returns
+the whole list changed instead of the old element.
Searches for exp-key in list and replaces each instance of the found element with exp-replacement.
+The list can be nested. The system variable $0 contains the expression found
+and can be used in exp-replacement. The function works like ref-set but returns
+the whole list changed:
Using the default functor in the (listkey) pattern allows the
+list to be passed by reference to a userdefined function containing a set-ref-all
+statemen. This would result in less memory usage and higher speeds in when doing replacements
+in large lists:
When evaluating (foo data), the list in data:data will be passed
+by reference and set-ref-all will make the changes on the original, not on
+a copy of data:data.
+ In the second syntax, the result of evaluating
+ one of the optional expressions
+ expr-1, expr-2, or expr-3 is returned,
+ instead of -1, 0, or 1.
+ In absence of expression expr-2 or expr-3,
+ nil is returned.
+
+
+example:
+
+
+(sgn x -1 0 1) ; works like (sgn x)
+(sgn x -1 1 1) ; return -1 for negative x all others 1
+(sgn x nil true true) ; return nil for negative else true
+(sgn x (abs x) 0) ; return (abs x) for negative x, 0 for x = 0, else nil
+
+
+
+
+ Any expression or constant can be used for
+ expr-1, expr-2, or expr-3.
+
+ Accesses shared memory
+ for communicating between
+ several newLISP processes or threads.
+ When called without arguments,
+ share requests a page of shared memory
+ (the page is 4k on Win32 but may differ on Linux/UNIX)
+ from the operating system.
+ This returns a memory address on Linux/UNIX
+ and a handle on Win32,
+ which can then be
+ assigned to a variable
+ for later reference.
+ This function is not available on OS/2.
+
+
+
+ To set the contents of shared memory,
+ use the third syntax of share.
+ Supply a shared memory address on Linux/UNIX
+ or a handle on Win32 in int-address-or-handle,
+ along with an integer, float, or string expression
+ in exp-value.
+ Using this syntax,
+ the value supplied in exp-value
+ is also the return value.
+
+
+
+ To access the contents of shared memory,
+ use the second syntax of share,
+ supplying only the shared memory address or handle.
+ The return value will be an integer or floating point number,
+ a string, or nil or true.
+ If the memory has not been previously set to a value,
+ nil will be returned.
+
+
+
+ Only available on UNIX-like operating systems,
+ the last syntax unmaps a shared memory address.
+ Note that using a shared address after unmapping it
+ will crash the system.
+
+
+
+ Memory can be shared between
+ parent and child processes or threads,
+ but not between independent processes.
+
+ For a more comprehensive example of using shared memory
+ in a multithreaded Linux/UNIX application,
+ see the file example/prodcons.lsp in the
+ newLISP source distribution.
+
+
+
+ Note that shared memory access
+ between different threads or processes
+ should be synchronized using a semaphore.
+ Simultaneous access to shared memory
+ can crash the running process/thread.
+
+
+
+ To find out the maximum length of a string buffer
+ that could be stored in a shared memory address,
+ execute the following:
+
+ The statement above tries to initialize
+ a shared memory address to 100,000 bytes,
+ but only 4087 will be initialized
+ as a string buffer.
+ The page size of this platform is
+ 4096 bytes—4087 plus 8 bytes
+ of header information for type and size,
+ as well as 1 terminating byte for displayable strings.
+
+
+
+ On Linux/UNIX systems,
+ more than one number or string
+ can be stored in one memory page
+ by using offsets added to the main segment address:
+
+ For numbers, reserve 12 bytes;
+ for strings, reserve 12 bytes,
+ plus the length of the string,
+ as well as 1 for the terminating zero-byte.
+ For the boolean values nil and true,
+ 4 bytes should be reserved.
+
+
+
+ Note that a shorter string
+ could accidentally be overwritten
+ with a longer one.
+ Therefore,
+ shared strings should be stored
+ after other shared number fields
+ or should reside on their own shared memory page.
+
+
+
+ The functions get-int,
+ get-float,
+ get-string,
+ and get-char—as
+ well as pack
+ and unpack—could
+ also be used to access contents
+ from a shared memory page.
+ This low-level address
+ requires precise knowledge
+ of the type of information stored,
+ but it allows for very compact storage
+ of information without type/header information
+ in a string buffer.
+
+ Sets a user-defined handler in sym-handler for a signal specified in int-signal
+ or sets to a function expression in func-handler.
+
+ If nil is specified,
+ the signal handler will be set to SIG_IGN, and the signal will be ignored.
+ Specifying true will set the signal handler to SIG_DFL, the default handler
+ of the underlying platform OS. On startup newLISP either specifies an empty
+ newLISP handler or a Ctrl-C handler for SIGINT and a waitpipd(-1, 0, WNOHANG)
+ C-call for SIGCHLD.
+
+
+
+ Different signals are available
+ on different OS platforms
+ and Linux/UNIX flavors.
+ The numbers to specify in int-signal
+ also differ from platform to platform.
+ Valid values can normally be extracted from a file found in /usr/include/sys/signal.h or /usr/include/signal.h.
+
+
+
+ Some signals make newLISP exit
+ even after a user-defined handler
+ has been specified and executed
+ (e.g., signal SIGKILL).
+ This behavior may also be different
+ on different platforms.
+
+
+example:
+
+
+(constant 'SIGINT 2)
+(define (ctrlC-handler) (println "ctrl-C has been pressed"))
+
+(signal SIGINT 'ctrlC-handler)
+
+; now press ctrl-C
+; the following line will appear
+; this will only work in an interactive terminal window
+; and will not work in the newLISP-GS editor
+
+ctrl-C has been pressed
+
+
+
+
+ On Win32,
+ the above example would
+ execute the handler
+ before exiting newLISP.
+ On most Linux/UNIX systems,
+ newLISP would stay loaded
+ and the prompt would appear
+ after hitting the [enter] key.
+
+
+
+ Instead of specifying a symbol containing the signal handler,
+ a function can be specified directly.
+ The signal number is passed as a parameter:
+
+
+
+
+(signal SIGINT exit) → $signal-2
+
+(sginal SIGINT (fn (s) (println "signal " s " occurred")))
+
+
+
+
+ Note that the signal SIGKILL
+ (9 on most platforms)
+ will always terminate the application
+ regardless of an existing signal handler.
+
+
+
+ The signal could have been sent
+ from another shell on the same computer:
+
+
+
+
+kill -s SIGINT 2035
+
+
+
+
+ In this example,
+ 2035 is the process ID
+ of the running newLISP.
+
+
+
+ The signal could also have been sent
+ from another newLISP application:
+
+ When importing kill,
+ make sure it always receives an integer
+ for the signal number.
+ If needed,
+ use the int function
+ to first convert the number.
+
+
+
+ If newLISP receives a signal
+ while evaluating another function,
+ it will still accept the signal
+ and the handler function will be executed:
+
+
+
+
+(constant 'SIGINT 2)
+(define (ctrlC-handler) (println "ctrl-C has been pressed"))
+
+(signal SIGINT 'ctrlC-handler)
+;; or
+(signal SIGINT ctrlC-handler)
+
+
+(while true (sleep 300) (println "busy"))
+
+;; generates following output
+busy
+busy
+busy
+ctrl-C has been pressed
+busy
+busy
+…
+
+
+
+
+ Specifying only a signal number
+ will return either the name of
+ the current defined handler function
+ or nil.
+
+
+
+ The user-defined signal handler
+ can pass the the signal number
+ as a parameter.
+
+
+
+
+(define (signal-handler sig)
+ (println "received signal: " sig))
+
+;; set all signals from 1 to 8 to the same handler
+(for (s 1 8)
+ (signal s 'signal-handler))
+
+
+
+
+ In this example,
+ all signals from 1 to 8 are set
+ to the same handler.
+
+
+
+
+
+
+
+
silent
+
+syntax: (silent [expr-1 [expr-2 ... ]])
+
+
+ Evaluates one or more expressions in expr-1—.
+ silent is similar to begin,
+ but it suppresses console output
+ of the return value
+ and the following prompt.
+ It is often used
+ when communicating from
+ a remote application with newLISP
+ (e.g., GUI front-ends
+ or other applications controlling newLISP),
+ and the return value is of no interest.
+
+
+
+ Silent mode is reset when returning to a prompt.
+ This way,
+ it can also be used without arguments
+ in a batch of expressions.
+ When in interactive mode,
+ hit [enter] twice after a statement
+ using silent
+ to get the prompt back.
+
+
+
+example:
+
+
+(silent (my-func)) ; same as next
+
+(silent) (my-func) ; same effect as previous
+
+
+
+
+
+
+
sin
+syntax: (sin num-radians)
+
+
+ Calculates the sine function
+ from num-radians
+ and returns the result.
+
Calculates the hyperbolic sine of num-radians.
+The hyperbolic sine is defined mathematically as: (exp (x) - exp (-x)) / 2.
+An overflow to inf may occur if num-radians is too large.
+ Gives up CPU time
+ to other processes
+ for the amount of milliseconds specified
+ in int-milli-seconds.
+
+
+example:
+
+
+(sleep 1000) ; sleeps 1 second
+
+
+
+
+ On some platforms,
+ sleep is only available
+ with a resolution of one second.
+ In this case,
+ the parameter int-milli-seconds
+ will be rounded to the nearest
+ full second.
+
+ In the first form,
+ slice copies a sublist
+ from a list.
+ The original list is left unchanged.
+ The sublist extracted
+ starts at index int-index
+ and has a length of int-length.
+ If int-length is negative
+ slice will take the parameter
+ as offset counting from the end and copy
+ up to that offset.
+ If the parameter is omitted,
+ slice copies all of the elements
+ to the end of the list.
+
+(slice '(a b c d e f) 3 2) → (d e)
+(slice '(a b c d e f) 2 -2) → (c d)
+(slice '(a b c d e f) 2) → (c d e f)
+(slice '(a b c d e f) -4 3) → (c d e)
+
+(set 'A (array 3 2 (sequence 1 6))) → ((1 2) (3 4) (5 6))
+(slice A 1 2) → ((3 4) (5 6))
+
+
+
+
+ In the second form,
+ a part of the string in str
+ is extracted.
+ int-index contains the start index
+ and int-length contains the length
+ of the substring.
+ If int-length is not specified,
+ everything to the end of the string is extracted.
+ slice also works on string buffers
+ containing binary data like 0's (zeroes).
+ It operates on byte boundaries
+ rather than character boundaries.
+ See also Indexing elements of strings and lists.
+
+ Note that an implicit slice
+ is available for lists.
+ See the chapter Implicit rest and slice.
+
+
+
+ Be aware that rest
+ always works on byte boundaries
+ rather than character boundaries
+ in the UTF-8–enabled version of newLISP.
+ As a result,
+ slice can be used
+ to manipulate binary content.
+
+
+
+
+
+
sort
+syntax: (sort list [func-compare])
+
+
+ All members in list
+ are sorted in ascending order.
+ Anything may be sorted,
+ regardless of the types.
+ When members are themselves lists,
+ each list element
+ is recursively compared.
+ If two expressions
+ of different types are compared,
+ the lower type is sorted
+ before the higher type
+ in the following order:
+
+ The sort is destructive,
+ changing the order of the elements in the original list.
+ The return value of sort is a copy of the sorted list.
+
+
+
+ An optional comparison operator,
+ user-defined function,
+ or anonymous function
+ can be supplied.
+ The functor or operator
+ can be given with or without
+ a preceding quote.
+
+
+example:
+
+
+(sort '(v f r t h n m j)) → (f h j m n r t v)
+(sort '((3 4) (2 1) (1 10))) → ((1 10) (2 1) (3 4))
+(sort '((3 4) "hi" 2.8 8 b)) → (2.8 8 "hi" b (3 4))
+
+(set 's '(k a l s))
+(sort s) → (a k l s)
+
+(sort '(v f r t h n m j) '>)
+→ (v t r n m j h f)
+;; the quote can be omitted beginning with version 8.4.5
+(sort '(v f r t h n m j) >)
+→ (v t r n m j h f)
+(sort s <) → (a k l s)
+(sort s >) → (s l k a)
+s → (s l k a)
+
+;; define a comparison function
+(define (comp x y)
+ (> (last x) (last y)))
+
+(set 'db '((a 3) (g 2) (c 5)))
+
+(sort db comp) → ((c 5) (a 3) (g 2))
+
+;; use an anonymous function
+(sort db (fn (x y) (> (last x) (last y))))
+
+ Works almost identically to save,
+ except symbols and contexts get serialized to a string
+ instead of being written to a file.
+ Multiple variable symbols,
+ definitions, and contexts
+ can be specified.
+ If no argument is given,
+ source serializes the entire
+ newLISP workspace.
+ When context symbols are serialized,
+ any symbols contained within that context
+ will be serialized, as well.
+ Symbols containing nil
+ are not serialized.
+ System symbols beginning with the $ (dollar sign) character
+ are only serialized when mentioned explicitly.
+
+
+
+ Symbols not belonging to the current context
+ are written out with their context prefix.
+
+
+example:
+
+
+(define (double x) (+ x x))
+
+(source 'double) → "(define (double x)\n (+ x x))\n\n"
+
+
+
+
+ As with save,
+ the formatting of line breaks
+ and leading spaces or tabs
+ can be controlled using the
+ pretty-print function.
+
+
+
+
+
+
sqrt
+syntax: (sqrt num)
+
+
+ Calculates the square root from
+ the expression in num
+ and returns the result.
+
+ In the first version,
+ starts-with checks if the string str
+ starts with a key string in str-key and
+ returns true or nil
+ depending on the outcome.
+
+
+
+ If a regular expression number is specified in num-option,
+ str-key contains a regular expression pattern.
+ See regex for valid option numbers.
+
+
+example:
+
+
+(starts-with "this is useful" "this") → true
+(starts-with "this is useful" "THIS") → nil
+(starts-with "this is useful" "THIS" nil) → true
+;; use regular expressions
+(starts-with "this is useful" "this|that" 1) → true
+
+
+
+
+
+ In the second version,
+ starts-with checks to see if a list
+ starts with the list element in expr.
+ true or nil is returned
+ depending on outcome.
+
+
+example:
+
+
+(starts-with '(1 2 3 4 5) 1) → true
+(starts-with '(a b c d e) 'b) → nil
+(starts-with '((+ 3 4) b c d) '(+ 3 4)) → true
+
+ Translates into a string anything that results
+ from evaluating exp-1—.
+ If more than one expression is specified,
+ the resulting strings are concatenated.
+
+ Use the append
+ and join
+ (allows the joining string
+ to be specified) functions
+ to concatenate strings.
+ Use the source function
+ to convert a lambda expression
+ into its newLISP source string representation.
+
+
+
+
+
+
string?
+syntax: (string? exp)
+
+
+ Evaluates exp and tests
+ to see if it is a string.
+ Returns true or nil
+ depending on the result.
+
+
+example:
+
+
+(set 'var "hello")
+(string? var) → true
+
+
+
+
+
+
+
sub
+syntax: (sub num-1 [num-2 ... ])
+
+
+ Successively subtracts
+ the expressions in num-1,
+ num-2—.
+ sub performs mixed-type arithmetic
+ and handles integers or floating points,
+ but it will always return
+ a floating point number.
+ If only one argument is supplied,
+ its sign is reversed.
+ Any floating point calculation
+ with NaN also returns NaN.
+
+ In the first form,
+ swap switches the elements in list
+ at indices num-1 and num-2
+ and returns the changed list.
+
+
+
+ In the second form,
+ the characters in str at indices num-1 and num-2
+ are swapped and the changed string is returned.
+
+
+
+ In the third form,
+ the contents of the two unquoted symbols in
+ sym-1 and sym-2 are swapped.
+
+
+
+ swap is a destructive operation
+ that changes the contents of the list, string,
+ or symbols involved.
+
+
+example:
+
+
+(set 'lst '(a b c d e f))
+
+(swap 0 5 lst) → '(f b c d e a)
+lst → '(f b c d e a)
+
+(swap 0 -1 lst) → '(a b c d e f)
+lst → '(a b c d e f)
+
+(swap 3 4 "abcdef") → "abcedf"
+
+(set 'x 1 'y 2)
+
+(swap x y) → 1
+
+x → 2
+y → 1
+
+
+
+
+
+
+
sym
+syntax: (sym string [sym-contextnil-flag] )
+syntax: (sym number [sym-contextnil-flag] )
+
+syntax: (sym symbol [sym-contextnil-flag] )
+
+
+ Translates the first argument in string,
+ number, or symbol
+ into a symbol and returns it.
+ If the optional context is not specified
+ in sym-context,
+ the current context is used
+ when doing symbol lookup or creation.
+ Symbols will be created
+ if they do not already exist.
+ When the context does not exist
+ and the context is specified by a quoted symbol,
+ the symbol also gets created.
+ If the context specification is unquoted,
+ the context is the specified name
+ or the context specification is a variable
+ containing the context.
+
+
+
+ sym can create symbols within the symbol table
+ that are not legal symbols in newLISP source code
+ (e.g., numbers or names containing special characters
+ such as parentheses, colons, etc.).
+ This makes sym usable
+ as a function for associative memory access,
+ much like hash table access
+ in other scripting languages.
+
+
+
+ As a third optional argument,
+ nil can be specified
+ to suppress symbol creation
+ if the symbol is not found.
+ In this case,
+ sym returns nil
+ if the symbol looked up does not exist.
+ Using this last form,
+ sym can be used
+ to check for the existence
+ of a symbol.
+
+
+example:
+
+
+(sym "some") → some
+(set (sym "var") 345) → 345
+var → 345
+(sym "aSym" 'MyCTX) → MyCTX:aSym
+(sym "aSym" MyCTX) → MyCTX:aSym ; unquoted context
+
+(sym "foo" MyCTX nil) → nil ; 'foo does not exist
+(sym "foo" MyCTX) → foo ; 'foo is created
+(sym "foo" MyCTX nil) → foo ; foo now exists
+
+
+
+
+ Because the function sym
+ returns the symbol looked up or created,
+ expressions with sym can be embedded
+ directly in other expressions
+ that use symbols as arguments.
+ The following example shows
+ the use of sym
+ as a hash-like function
+ for associative memory access,
+ as well as symbol configurations
+ that are not legal newLISP symbols:
+
+
+example:
+
+
+;; using sym for simulating hash tables
+
+(set (sym "John Doe" 'MyDB') 1.234)
+(set (sym "(" 'MyDB) "parenthesis open")
+(set (sym 12 'MyDB) "twelve")
+
+(eval (sym "John Doe" 'MyDB)) → 1.234
+(eval (sym "(" 'MyDB)) → "parenthesis open"
+(eval (sym 12 'MyDB)) → "twelve"
+
+;; delete a symbol from a symbol table or hash
+(delete (sym "John Doe" 'MyDB)) → true
+
+
+
+
+ The last statement shows
+ how a symbol can be eliminated
+ using delete.
+
+
+
+ The third syntax allows symbols to be used
+ instead of strings for the symbol name
+ in the target context.
+ In this case,
+ sym will extract the name from the symbol
+ and use it as the name string
+ for the symbol in the target context:
+
+
+example:
+
+
+(sym 'myVar 'FOO) → FOO:myVar
+
+(define-macro (def-context)
+ (dolist (s (rest (args)))
+ (sym s (first (args)))))
+
+(def-context foo x y z)
+
+(symbols foo) → (foo:x foo:y foo:z)
+
+
+
+
+ The def-context macro
+ shows how this could be used
+ to create a macro that creates
+ contexts and their variables
+ in a dynamic fashion.
+
+
+
+ Available since version 8.7.4,
+ one syntax of the context function
+ can be used to create, set, and evaluate symbols
+ in a shorter, faster way.
+
+
+
+
+
+
+
symbol?
+syntax: (symbol? exp)
+
+
+ Evaluates the exp expression
+ and returns true if the value is a symbol;
+ otherwise, it returns nil.
+
+
+example:
+
+
+(set 'x 'y) → y
+
+(symbol? x) → true
+
+(symbol? 123) → nil
+
+(symbol? (first '(var x y z))) → true
+
+
+
+
+
+ The first statement sets the contents of x
+ to the symbol y.
+ The second statement then checks the contents of x.
+ The last example checks the first element of a list.
+
+
+
+
+
+
symbols
+syntax: (symbols [context])
+
+
+ Returns a sorted list of all symbols
+ in the current context
+ when called without an argument.
+ If a context symbol is specified,
+ symbols defined in that context are returned.
+
+
+example:
+
+
+(symbols) ; list of all symbols in current context
+(symbols 'CTX) ; list of symbols in context CTX
+(symbols CTX) ; omitting the quote
+(set 'ct CTX) ; assigning context to a variable
+(symbols ct) ; list of symbols in context CTX
+
+
+
+
+ The quote can be omitted
+ because contexts evaluate to themselves.
+
+
+
+
+
+
sys-error
+syntax: (sys-error)
+
+
+ Reports error numbers generated
+ by the underlying OS
+ newLISP is running on.
+ The error numbers reported
+ may differ on the platforms
+ newLISP has been compiled for.
+ Consult the platform's C library information,
+ (e.g., the GNU libc reference).
+ Most errors reported
+ refer to system resources such as files and semaphores.
+
+
+
+ Whenever a function in newLISP
+ within the system resources area
+ returns nil,
+ sys-error can be checked
+ for the underlying reason.
+ For file operations,
+ sys-error may be set
+ for nonexistent files
+ or wrong permissions
+ when accessing the resource.
+ Another cause of error
+ could be the exhaustion of certain system resources
+ like file handles or semaphores.
+
+
+
+example:
+
+
+;; trying to open a nonexistent file
+(open "blahbla" "r") → nil
+
+(sys-error) → 2
+
+(sys-error 0) → 0 ; clear errno
+
+
+
+
+ The error number can be cleared
+ by giving a 0 (zero)
+ for the optional argument.
+
+
+
+
+
+
sys-info
+syntax: (sys-info [int-idx])
+
+
+ Calling sys-info
+ without int-idx
+ returns a list of internal resource statistics.
+ Eight integers report the following status:
+
+
+
+ 0 - Number of LISP cells
+ 1 - Maximum number of LISP cells constant
+ 2 - Number of symbols
+ 3 - Evaluation/recursion level
+ 4 - Environment stack level
+ 5 - Maximum call stack constant
+ 6 - Version number as an integer constant
+ 7 - Operating system constant:
+ linux=1, bsd=2, osx=3, solaris=4, cygwin=5, win32=6,
+ os/2=7, tru64unix=9
+ the highest bit 7 will be set for UTF-8 versions (add 128)
+ bit 6 will be added for library versions (add 64)
+
+
+
+ The numbers from 0 to 7
+ indicate the optional offset
+ in the returned list.
+
+
+
+ When using int-idx,
+ one element of the list will be returned.
+
+ The number for the maximum of LISP cells
+ can be changed via the -m
+ command-line switch.
+ For each megabyte of LISP cell memory,
+ 64k memory cells can be allocated.
+ The maximum call stack depth
+ can be changed using the -s
+ command-line switch.
+
+
+
+
+
+
tan
+syntax: (tan num-radians)
+
+
+ Calculates the tangent function from num-radians
+ and returns the result.
+
+ Works together with
+ the catch function.
+ throw forces the return of a previous catch statement
+ and puts the exp into the result symbol of catch.
+
+ The last example shows a shorter form of catch,
+ which returns the throw result directly.
+
+
+
+ throw is useful for breaking out of a loop
+ or for early return from user-defined functions
+ or expression blocks.
+ In the following example,
+ the begin block will return X
+ if (foo X) is true;
+ else Y will be returned:
+
+ throw will not cause an error exception.
+ Use throw-error
+ to throw user error exceptions.
+
+
+
+
+
+
+
throw-error
+syntax: (throw-error expr)
+
+
+ Causes a user-defined error exception
+ with text provided by evaluating expr.
+
+
+example:
+
+
+(define (foo x y)
+ (if (= x 0) (throw-error "first argument cannot be 0"))
+ (+ x y))
+
+(foo 1 2) → 3
+
+(foo 0 2) ; causes a user error exception
+user error : first argument cannot be 0
+called from user-defined function foo
+
+
+
+
+ The user error can be handled
+ like any other error exception
+ using user-defined error handlers
+ and the error-event function,
+ or the form of catch
+ that can capture error exceptions.
+
+
+
+
+
+
time
+syntax: (time exp [int-count)
+
+
+ Evaluates the expression in exp
+ and returns the time spent on evaluation
+ in milliseconds.
+
+
+example:
+
+
+(time (myprog x y z)) → 450
+
+(time (myprog x y z) 10) → 4420
+
+
+
+
+ In first the example,
+ 450 milliseconds elapsed
+ while evaluating (myprog x y z).
+ The second example returns the time
+ for ten evaluations of (myprog x y z).
+ See also date,
+ date-value,
+ time-of-day,
+ and now.
+
+
+
+
+
+
time-of-day
+
+syntax: (time-of-day)
+
+
+ Returns the time in milliseconds
+ since the start of the current day.
+
+ Starts a one-shot timer
+ firing off the Unix signal SIGALRM, SIGVTALRM,
+ or SIGPROF after the time in seconds
+ (specified in num-seconds) has elapsed.
+ When the timer fires,
+ it calls the user-defined function
+ in sym-event-handler.
+
+
+
+ On Linux/UNIX,
+ an optional 0, 1,
+ or 2 can be specified
+ to control how the timer counts.
+ With default option 0,
+ real time is measured.
+ Option 1 measures the time
+ the CPU spends processing in the thread or process
+ owning the timer.
+ Option 3 is a combination of both
+ called profiling time.
+ See the UNIX man page setitimer()
+ for details.
+
+
+
+ The event handler
+ can start the timer again
+ to achieve a continuous flow of events.
+ Starting with version 8.5.9,
+ seconds can be defined
+ as floating point numbers
+ with a fractional part
+ (e.g., 0.25 for 250 milliseconds).
+
+
+
+ Defining 0 (zero) as time
+ shuts the running timer down
+ and prevents it from firing.
+
+
+
+ When called with sym-event-handler,
+ timer returns the elapsed time
+ of the timer in progress.
+ This can be used to program
+ timelines or schedules.
+
+
+
+ timer called without arguments
+ returns the symbol of the current event handler.
+
+ The example shows an event handler, ticker,
+ which starts the timer again after each event.
+
+
+
+ Note that a timer cannot interrupt an
+ ongoing built-in function.
+ The timer interrupt gets registered by newLISP,
+ but a timer handler cannot run
+ until one expression is evaluated
+ and the next one starts.
+ To interrupt an ongoing I/O operation with timer,
+ use the following pattern,
+ which calls net-select
+ to test if a socket is ready for reading:
+
+ In this example,
+ the until loop will run
+ until something can be read from socket,
+ or until ten seconds have passed
+ and the timeout variable is set.
+
+ Returns a copy of the string in str
+ with the first character converted to uppercase.
+ When the optional bool parameter
+ evaluates to any value other than nil,
+ the rest of the string is converted to lowercase.
+
+ Tracing is switched on when exp evaluates to anything
+ besides nil or an empty list ().
+ When no argument is supplied,
+ trace evaluates to true or nil
+ depending on the current trace mode.
+ If trace mode is switched on,
+ newLISP goes into debugging mode after entering
+ the next user defined function,
+ displaying the function and highlighting the current expression
+ upon entry and exit.
+
+
+ Highlighting is done by bracketing the expression
+ between two # (number sign) characters.
+ This can be changed to a different character
+ using trace-highlight.
+ Upon exit from the expression,
+ the result of its evaluation
+ is also reported.
+
+
+
+ If an expression occurs more than once in a function,
+ the first occurrence of the executing function
+ will always be highlighted (bracketed).
+
+
+
+ newLISP execution stops with a prompt line
+ at each entry and exit of an expression.
+
+
+
+
+[-> 2] s|tep n|ext c|ont q|uit >
+
+
+
+
+ At the prompt,
+ an s, n, c,
+ or q can be entered
+ to step into or
+ merely execute the next expression.
+ Any expression can be entered
+ at the prompt for evaluation.
+ Entering the name of a variable,
+ for example,
+ would evaluate to its contents.
+ In this way,
+ a variable's contents
+ can be checked during debugging
+ or set to different values.
+
+
+example:
+
+
+;; switches newLISP into debugging mode
+(trace true) → true
+
+;; the debugger will show each step
+(my-func a b c)
+
+;; switched newLISP out of debugging mode
+(trace nil) → nil
+
+
+
+ To set break points
+ where newLISP should interrupt
+ normal execution
+ and go into debugging mode,
+ put (trace true) statements
+ into the LISP code where execution
+ should switch on the debugger.
+
+
+
+ Use the debug function
+ as a shortcut for the above example.
+
+ Sets the characters or string of characters
+ used to enclose expressions
+ during trace.
+ By default,
+ the # (number sign) is used
+ to enclose the expression highlighted
+ in trace mode.
+ This can be changed to different characters
+ or strings of up to seven characters.
+ If the console window accepts terminal control characters,
+ this can be used to display the expression in a different color,
+ bold, reverse, and so forth.
+
+
+
+ Two more strings can optionally be specified
+ for str-header and str-footer,
+ which control the separator and prompt.
+ A maximum of 15 characters is allowed
+ for the header and 31 for the footer.
+
+
+example:
+
+
+;; active expressions are enclosed in >> and <<
+
+(trace-highlight ">>" "<<")
+
+;; 'bright' color on a VT100 or similar terminal window
+
+(trace-highlight "\027[1m" "\027[0m")
+
+
+
+
+
+ The first example replaces the default # (number sign)
+ with a >> and <<.
+ The second example works on most Linux shells.
+ It may not, however, work in console windows
+ under Win32 or CYGWIN,
+ depending on the configuration of the terminal.
+
+
+
+
+
+
+
+
transpose
+syntax: (transpose matrix)
+
+
+ Transposes a matrix
+ by reversing the rows and columns
+ and converting all of the cells
+ to floating point numbers.
+ Any kind of list-matrix
+ can be transposed.
+ Matrices are made rectangular
+ by filling in nil for missing elements,
+ omitting elements where appropriate,
+ or expanding atoms in rows into lists.
+ Matrix dimensions are calculated
+ using the number of rows in the original matrix
+ for columns and the number of elements in the first row
+ as number of rows for the transposed matrix.
+
+
+
+ The dimensions of a matrix
+ are defined by the number of rows
+ and the number of elements in the first row.
+ A matrix can either be a nested list
+ or an array.
+
+
+example:
+
+
+(set 'A '((1 2 3) (4 5 6)))
+(transpose A) → ((1 4) (2 5) (3 6))
+(transpose (list (sequence 1 5))) → ((1) (2) (3) (4) (5))
+
+(transpose '((a b) (c d) (e f))) → ((a c e) (b d f))
+
+
+
+
+ The number of columns in a matrix
+ is defined by the number of elements
+ in the first row of the matrix.
+ If other rows have fewer elements,
+ transpose will assume nil
+ for those missing elements.
+ Superfluous elements in a row will be ignored.
+
+ The first syntax trims the string str from both sides,
+ stripping the leading and trailing characters as given
+ in str-char.
+ If str-char contains no character,
+ the space character is assumed.
+ trim returns the new string.
+
+
+
+ The second syntax can either trim
+ different characters from both sides
+ or trim only one side
+ if an empty string is specified
+ for the other.
+
+ If the expression in expr
+ evaluates to anything other than nil,
+ or the empty list ()
+ true? returns true;
+ else it returns nil.
+
+
+example:
+
+
+(map true? '(x 1 "hi" (a b c) nil ()))
+→ (true true true true nil nil)
+(true? nil) → nil
+(true? '()) → nil
+
+
+
+
Since version 9.1 true? behaves like if
+rejecting the empty list ()
+
+
+
+
+
+
unicode
+
+syntax: (unicode str)
+
+
+ Converts ASCII/UTF-8 character strings in str
+ to UCS-4–encoded Unicode of 4-byte integers per character.
+ This function is only available
+ on UTF-8–enabled versions of newLISP.
+
+ On big endian CPU architectures,
+ the byte order will be reversed from high to low.
+ The unicode and utf8 functions
+ are the inverse of each other.
+ These functions are only necessary
+ if UCS-4 Unicode is in use.
+ Most systems use UTF-8 encoding only.
+
+
+
+
+
+
unify
+syntax: (unify expr-1expr-2 [list-env])
+
+
+ Evaluates and matches
+ expr-1 and expr-2.
+ Expressions match if they are equal
+ or if one of the expressions is
+ an unbound variable
+ (which would then be bound to the other expression).
+ If expressions are lists,
+ they are matched by comparing subexpressions.
+ Unbound variables start with an uppercase character
+ to distinguish them from symbols.
+ unify returns nil
+ when the unification process fails,
+ or it returns a list of variable associations on success.
+ When no variables were bound,
+ but the match is still successful,
+ unify returns an empty list.
+ newLISP uses a modified J. Alan Robinson unification algorithm
+ with occurs check.
+
+
+
+ Like matchunify is frequently
+ employed as a parameter functor in find,
+ ref, ref-all and
+ replace.
+
+
+
+example:
+
+
+(unify 'A 'A) → () ; tautology
+
+(unify 'A 123) → ((A 123)) ; A bound to 123
+
+(unify '(A B) '(x y)) → ((A x) (B y)) ; A bound to x, B bound to y
+
+(unify '(A B) '(B abc)) → ((A abc) (B abc)) ; B is alias for A
+
+(unify 'abc 'xyz) → nil ; fails because symbols are different
+
+(unify '(A A) '(123 456)) → nil ; fails because A cannot be bound to different values
+
+(unify '(f A) '(f B)) → ((A B)) ; A and B are aliases
+
+(unify '(f A) '(g B)) → nil ; fails because heads of terms are different
+
+(unify '(f A) '(f A B)) → nil ; fails because terms are of different arity
+
+(unify '(f (g A)) '(f B)) → ((B (g A))) ; B bound to (g A)
+
+(unify '(f (g A) A) '(f B xyz)) → ((B (g xyz)) (A xyz)) ; B bound to (g xyz) A to xyz
+
+(unify '(f A) 'A) → nil ; fails because of infinite unification (f(f(f …)))
+
+(unify '(A xyz A) '(abc X X)) → nil ; indirect alias A to X doesn't match bound terms
+
+(unify '(p X Y a) '(p Y X X)) → '((Y a) (X a))) ; X alias Y and binding to 'a
+
+(unify '(q (p X Y) (p Y X)) '(q Z Z)) → ((Y X) (Z (p X X))) ; indirect alias
+
+;; some examples taken from http://en.wikipedia.org/wiki/Unification
+
+
+
+
+ unify can take an optional binding
+ or association list in list-env.
+ This is useful when chaining unify expressions
+ and the results of previous unify bindings
+ must be included:
+
+
+example:
+
+
+(unify '(f X) '(f 123)) → ((X 123))
+
+(unify '(A B) '(X A) '((X 123)))
+→ ((X 123) (A 123) (B 123))
+
+
+
+
+ In the previous example,
+ X was bound to 123 earlier
+ and is included in the second statement
+ to pre-bind X.
+
+
+
+ Note that variables are not actually bound
+ as a newLISP assignment. Rather,
+ an association list is returned
+ showing the logical binding.
+ A special syntax of expand
+ can be used to actually replace bound variables
+ with their terms:
+
+
+
+
+(set 'bindings (unify '(f (g A) A) '(f B xyz)))
+→ ((B (g xyz)) (A xyz))
+
+(expand '(f (g A) A) bindings) → (f (g xyz) xyz)
+
+; or in one statement
+(expand '(f (g A) A) (unify '(f (g A) A) '(f B xyz)))
+→ (f (g xyz) xyz)
+
+
+
+
The function bind can be used to set unified
+variables:
+
+
+
+(bind (unify '(f (g A) A) '(f B xyz)))
+
+A → xyz
+B → (g xyz)
+
+
+
+
+
+
+ The following example shows how propositional logic
+ can be modeled using unify
+ and expand:
+
+
+
+
+; if somebody is human, he is mortal -> (X human) :- (X mortal)
+; socrates is human -> (socrates human)
+; is socrates mortal? -> ? (socrates mortal)
+
+(expand '(X mortal)
+ (unify '(X human) '(socrates human)))
+→ (socrates mortal)
+
+
+
+
+ The following is a more complex example
+ showing a small, working PROLOG (Programming in Logic)
+ implementation.
+
+ The program handles a database of facts
+ and a database of simple
+ A is a fact if B is a factrules.
+ A fact is proven true
+ if it either can be found in the facts database
+ or if it can be proven using a rule.
+ Rules can be nested:
+ for example, to prove that somebody (knows physics),
+ it must be proved true that somebody is a physicist.
+ But somebody is only a physicist
+ if that person studied physics.
+ The <- symbol
+ separating the left and right terms of the rules
+ is not required
+ and is only added to make the rules database
+ more readable.
+
+
+
+ This implementation does not handle multiple terms
+ in the right premise part of the rules,
+ but it does handle backtracking of the rules database
+ to try out different matches.
+ It does not handle backtracking
+ in multiple premises of the rule.
+ For example,
+ if in the following rule A if B and C and D,
+ the premises B and C succeed
+ and D fails,
+ a backtracking mechanism might need to go back
+ and reunify the B or A terms
+ with different facts or rules
+ to make D succeed.
+
+
+
+ The above algorithm could be written differently
+ by omitting expand
+ from the definition of prove-rule
+ and by passing the environment, e,
+ as an argument to the unify and query functions.
+
+
+
+ A learning of proven facts
+ can be implemented by appending them
+ to the facts database
+ once they are proven.
+ This would speed up subsequent queries.
+
+
+
+ Larger PROLOG implementations
+ also allow the evaluation of terms in rules.
+ This makes it possible to implement functions
+ for doing other work
+ while processing rule terms.
+ prove-rule could accomplish this testing
+ for the symbol eval in each rule term.
+
+
+
+
+
+
unique
+syntax: (unique list)
+
+
+ Returns a unique version of list
+ with all duplicates removed.
+
+
+example:
+
+
+(unique '(2 3 4 4 6 7 8 7)) → (2 3 4 6 7 8)
+
+
+
+
+ Note that the list does not need to be sorted,
+ but a sorted list makes unique perform faster.
+
+ unless is equivalent to
+ (if (not
+ exp-conditionexp-1 [exp-2])).
+ If the value of exp-condition is nil
+ or the empty list (),
+ exp-1 is evaluated;
+ otherwise, exp-2 is evaluated.
+
+ Unpacks a binary structure
+ in str-addr-packed
+ into LISP variables
+ using the format in str-format.
+ unpack is the reverse operation of pack.
+ Note that str-addr-packed
+ may also be an integer representing a memory address.
+ This facilitates the unpacking of structures
+ returned from imported, shared library functions.
+
+ Evaluates the condition
+ in exp-condition body.
+ If the result is nil or the empty list (),
+ the expressions in body are evaluated.
+ Evaluation is repeated until the exp-condition results in a value
+ other than nil or the empty list.
+ The result of the last expression evaluated
+ is the return value of the until expression.
+ until works like
+ (while (not …)).
+
+ On big endian CPU architectures,
+ the byte order will be reversed
+ from highest to lowest.
+ The utf8
+ and unicode functions
+ are the inverse of each other.
+ These functions are only necessary
+ if UCS-4 Unicode is in use.
+ Most systems use UTF-8 Unicode encoding only.
+
+
+
+
+
+
utf8len
+syntax: (utf8len str)
+
+
Returns the number of characters in a UTF-8–encoded string.
+UTF-8 characters can be encoded in more than one 8-bit byte.
+utf8len returns the number of UTF-8 characters in a string.
+This function is only available on UTF-8–enabled versions of newLISP.
+ Constructs and returns
+ a UUID (Universally Unique IDentifier).
+ Without a node spec in str-node,
+ a type 4 UUID random generated byte number
+ is returned.
+ When the optional str-node parameter is used,
+ a type 1 UUID is returned.
+ The string in str-node
+ specifies a valid MAC (Media Access Code)
+ from a network adapter installed on the node
+ or a random node ID.
+ When a random node ID is specified,
+ the least significant bit of the first node byte
+ should be set to 1
+ to avoid clashes with real MAC identifiers.
+ UUIDs of type 1 with node ID
+ are generated from a timestamp and other data.
+ See RFC 4122
+ for details on UUID generation.
+
+
+example:
+
+
+;; type 4 UUID for any system
+
+(uuid) → "493AAD61-266F-48A9-B99A-33941BEE3607"
+
+;; type 1 UUID preferred for distributed systems
+
+;; configure node ID for ether 00:14:51:0a:e0:bc
+(set 'id (pack "cccccc" 0x00 0x14 0x51 0x0a 0xe0 0xbc))
+
+(uuid id) → "0749161C-2EC2-11DB-BBB2-0014510AE0BC"
+
+
+
+
+ Each invocation of the uuid function
+ will yield a new unique UUID.
+ The UUIDs are generated without systemwide
+ shared stable store (see RFC 4122).
+ If the system generating the UUIDs
+ is distributed over several nodes,
+ then type 1 generation should be used
+ with a different node ID on each node.
+ For several processes on the same node,
+ valid UUIDs are guaranteed
+ even if requested at the same time.
+ This is because the process ID
+ of the generating newLISP process
+ is part of the seed
+ for the random number generator.
+ When type 4 IDs are used on a distributed system,
+ two identical UUID's are still highly unlikely
+ and impossible for type 1 IDs
+ if real MAC addresses are used.
+
+
+
+
+
+
+
wait-pid
+syntax: (wait-pid int-pid [int-options])
+
+
+ Waits for a child process specified in int-pid to end.
+ The child process was previously started
+ with process or fork.
+ When the child process specified in int-pid ends,
+ a status value describing the reason for termination
+ of the child process or thread is returned.
+ The interpretation of the returned status value
+ differs between Linux and other flavors of UNIX.
+ Consult the Linux/UNIX man pages
+ for the waitpid command
+ (without the hyphen used in newLISP)
+ for further information.
+
+
+
+ When -1 is specified for int-pid,
+ the status information of any child process started is returned.
+ When 0 is specified,
+ wait-pid only watches
+ child processes in the same process group
+ as the calling process.
+ Any other negative value for int-pid
+ reports child processes in the same process group
+ as specified with a negative sign in int-pid.
+
+
+
+ This function is only available on Linux
+ and other UNIX-like operating systems
+ or on a CYGWIN compiled version of newLISP
+ on Win32.
+ An option can be specified in int-option.
+ See Linux/UNIX documentation
+ for details on options.
+
+
+example:
+
+(set 'pid (fork (my-thread)))
+
+(set 'status (wait-pid pid)) ; wait until my-thread ends
+
+(println "thread: " pid " has finished with status: " status)
+
+
+
+ The process my-thread is started,
+ then the main program blocks
+ in the wait-pid call
+ until my-thread has finished.
+
+
+
+
+
+
when
+syntax: (when exp-conditionbody)
+
+
The statements in body are only evaluated if exp-condition
+evalutes to true
+
+
Because when does not have an else condition as in
+if, the statements in body need not to be grouped with
+begin:
+ Evaluates the condition
+ in exp-condition.
+ If the result is not nil or the empty list (),
+ the expressions in body are evaluated.
+ Evaluation is repeated until an exp-condition results
+ in nil or the empty list ().
+ The result of the body's last expression
+ is the return value of
+ the while expression.
+
+ Using the first syntax,
+ write-buffer writes int-size bytes
+ from a buffer in sym-buffer or str-buffer
+ to a file specified in int-file,
+ previously obtained from a file open operation.
+ If int-size is not specified,
+ all data in sym-buffer or str-buffer
+ is written.
+ write-buffer returns the number of bytes written
+ or nil on failure.
+
+
+
+ The string buffer symbol can be used
+ with or without quoting a symbol.
+
+ The code in the example writes 100 bytes
+ to the file myfile.ext
+ from the contents in data.
+
+
+
+ Using the second syntax,
+ write-buffer appends contents from a string
+ specified in sym-buffer or str-buffer
+ to the string specified in str-device,
+ which acts like a stream device.
+
+ Writes a byte specified in int-byte
+ to a file specified by the file handle in int-file.
+ The file handle is obtained
+ from a previous open operation.
+ Each write-char advances the file pointer
+ by one byte.
+
+ Use the print
+ and device functions
+ to write larger portions of data at a time.
+ Note that newLISP already supplies a faster
+ built-in function called
+ copy-file.
+
+ The file myfile is read,
+ encrypted using the password secret,
+ and written back into the new file myfile.enc
+ in the current directory.
+
+
+
+ write-file can take an
+ http:// or file:// URL
+ in str-file-name.
+ In this case,
+ write-file works exactly like put-url
+ and can take the same additional parameters:
+
+
+example:
+
+
+(write-file "http://asite.com/message.txt" "This is a message" )
+
+
+
+
+ The file message.txt is created
+ and written at a remote location, http://asite.com,
+ with the contents of str-buffer.
+ In this mode,
+ write-file can also be used to transfer files
+ to remote newLISP server nodes.
+
+ The string in str
+ and the line termination character(s)
+ are written to the console or a file.
+ If no file handle is specified in int-file,
+ write-line writes to the current device,
+ normally the console screen.
+ When all arguments are omitted,
+ write-line writes the contents
+ of the last read-line to the screen.
+
+ The first example puts a string out on the current device,
+ which is probably the console window (device 0).
+ The second example opens/creates a file,
+ writes a line to it,
+ and closes the file.
+ The third example shows the usage of write-line
+ without arguments.
+ The contents of init.lsp
+ are written to the console screen.
+
+
+
+ In the second syntax,
+ a string can be specified
+ as a device in str-device
+ (like the write-buffer function).
+ When a string device is written to,
+ the string in str-device gets appended with str
+ and the line termination character(s).
+
+
+
+
+
+
+
xml-error
+syntax: (xml-error)
+
+
+ Returns a list of error information
+ from the last xml-parse operation;
+ otherwise, returns nil
+ if no error occurred.
+ The first element contains text
+ describing the error,
+ and the second element is a number indicating
+ the last scan position in the source XML text,
+ starting at 0 (zero).
+
+ Parses a string containing XML 1.0 compliant,
+ well-formed XML.
+ xml-parse does not perform DTD validation.
+ It skips DTDs (Document Type Declarations)
+ and processing instructions.
+ Nodes of type ELEMENT, TEXT, CDATA,
+ and COMMENT are parsed, and
+ a newLISP list structure is returned.
+ When an element node does not have
+ attributes or child nodes,
+ it instead contains an empty list.
+ Attributes are returned as association lists,
+ which can be accessed using assoc.
+ When xml-parse fails
+ due to malformed XML,
+ nil is returned
+ and xml-error can be used
+ to access error information.
+
+ Optionally, the int-options parameter
+ can be specified
+ to suppress whitespace,
+ empty attribute lists,
+ and comments.
+ It can also be used
+ to transform tags
+ from strings into symbols.
+ Another function, xml-type-tags,
+ serves for translating the XML tags.
+ The following option numbers can be used:
+
+
+
+
+
+
+
option
description
+
1
suppress whitespace text tags
+
2
suppress empty attribute lists
+
4
suppress comment tags
+
8
translate string tags into symbols
+
+
16
add SXML (S-expression XML) attribute tags
+
+
+
+
+ Options can be combined
+ by adding the numbers
+ (e.g., 3 would combine the options
+ for suppressing whitespace text tags/info
+ and empty attribute lists).
+
+
+
+ The following examples
+ show how the different options can be used:
+
+ The TEXT elements containing only whitespace
+ make the output very confusing.
+ As the database in example.xml only contains data,
+ we can suppress whitespace and comments
+ with option (+ 1 3):
+
+ The resulting output looks much more readable,
+ but it can still be improved
+ by using symbols instead of strings
+ for the tags "FRUIT", "NAME", "COLOR", and "PRICE",
+ as well as by suppressing the XML type tags
+ "ELEMENT" and "TEXT" completely
+ using the xml-type-tags directive.
+
+
+
+
+Suppressing XML type tags with xml-type-tags and translating string tags into symbol tags:
+
+
+
+;; suppress all XML type tags for TEXT and ELEMENT
+;; instead of "CDATA", use cdata and instead of "COMMENT", use !--
+
+(xml-type-tags nil 'cdata '!-- nil)
+
+;; turn on all options for suppressing whitespace and empty
+;; attributes, translate tags to symbols
+
+(xml-parse (read-file "example.xml") (+ 1 2 8))
+→ ((DATABASE (("name" "example.xml"))
+ (!-- "This is a database of fruits")
+ (FRUIT (NAME "apple") (COLOR "red") (PRICE "0.80"))
+ (FRUIT (NAME "orange") (COLOR "orange") (PRICE "1.00"))
+ (FRUIT (NAME "banana") (COLOR "yellow") (PRICE "0.60"))))
+
+
+
+
+ When tags are translated into symbols by using option 8,
+ a context can be specified in sym-context.
+ If no context is specified,
+ all symbols will be created inside the current context.
+
+ Specifying nil for the XML type tags TEXT and ELEMENT
+ makes them disappear.
+ At the same time,
+ parentheses of the child node list
+ are removed so that
+ child nodes now appear as members of the list,
+ starting with the tag symbol
+ translated from the string tags
+ "FRUIT", "NAME", etcetera.
+
+
+
+Parsing into SXML (S-expressions XML) format:
+
+ Using xml-type-tags to suppress
+ all XML-type tags—along with the option numbers
+ 1, 4, 8, and 16—SXML
+ formatted output can be generated:
+
+ Note that using option number 16
+ causes an @ (at symbol) to be added to attribute lists.
+
+
+
+ See also the xml-type-tags function
+ for further information on XML parsing.
+
+
+Parsing into a specified context
+
When parsing XML expressions XML tags are translated into newLISP symbols.
+The sym-context option specifies the target context for the symbol
+creation:
+
If the context does not exist, it will be created. If it exists, the quote can
+be omitted or the context can be referred to by a variable.
+
+
+
+
+
+
+
+
+Using a call back function
+
Normally xml-parse will not return until all parsing has finished.
+Using the func-callback option xml-parse will call back after
+each tag closing with the generated S-expression and a start position and
+length in the source XML:
+ Can suppress completely
+ or replace the XML type tags
+ "TEXT", "CDATA", "COMMENT", and "ELEMENT"
+ with something else specified
+ in the parameters.
+
+
+
+ Note that xml-type-tags
+ only suppresses or translates the tags themselves
+ but does not suppress or modify the tagged information.
+ The latter would be done
+ using option numbers in xml-parse.
+
+
+
+ Using xml-type-tags without arguments
+ returns the current type tags:
+
+ The first example just shows the currently used type tags.
+ The second example specifies suppression of the "TEXT" and "ELEMENT" tags
+ and shows cdata and !-- instead of
+ "CDATA" and "COMMENT".
+
+
+
+
+
+
zero?
+syntax: (zero? expr)
+
+
+ Checks the evaluation of expr
+ to see if it equals 0 (zero).
+
+ zero? will return nil
+ on data types other than numbers.
+
+
+
+
+
+
+( ∂ )
+
+
+
+
+
+
newLISP APPENDIX
+
+
Error codes
+
+
+
+ not enough memory 1
+ environment stack overflow 2
+ call stack overflow 3
+ problem accessing file 4
+ not an expression 5
+ missing parenthesis 6
+ string token too long 7
+ missing argument 8
+ number or string expected 9
+ value expected 10
+ string expected 11
+ symbol expected 12
+ context expected 13
+ symbol or context expected 14
+ list expected 15
+ list or array expected 16
+ list or symbol expected 17
+ list or string expected 18
+ list or number expected 19
+ array expected 20
+ array, list or string expected 21
+ lambda expected 22
+ lambda-macro expected 23
+ invalid function 24
+ invalid lambda expression 25
+ invalid macro expression 26
+ invalid let parameter list 27
+ problem saving file 28
+ division by zero 29
+ matrix expected 30
+ wrong dimensions 31
+ matrix is singular 32
+ syntax in regular expression 33
+ throw without catch 34
+ problem loading library 35
+ import function not found 36
+ symbol is protected 37
+ error number too high 38
+ regular expression 39
+ missing end of text [/text] 40
+ mismatch in number of arguments 41
+ problem in format string 42
+ data type and format don't match 43
+ invalid parameter 44
+ invalid parameter: 0.0 45
+ invalid parameter: NaN 46
+ illegal parameter type 47
+ symbol not in MAIN context 48
+ symbol not in current context 49
+ target cannot be MAIN 50
+ list index out of bounds 51
+ array index out of bounds 52
+ string index out of bounds 53
+ nesting level too deep 54
+ user error 55
+ user reset - 56
+ received SIGINT - 57
+ function is not reentrant 58
+
+
+
+
+
+
+
+
TCP/IP and UDP Error Codes
+
+
+
+ 0: No error
+ 1: Cannot open socket
+ 2: Host name not known
+ 3: Not a valid service
+ 4: Connection failed
+ 5: Accept failed
+ 6: Connection closed
+ 7: Connection broken
+ 8: Socket send() failed
+ 9: Socket recv() failed
+10: Cannot bind socket
+11: Too much sockets in net-select
+12: Listen failed
+13: Badly formed IP
+14: Select failed
+15: Peek failed
+16: Not a valid socket
+
+
+
+
+
+( ∂ )
+
+
+
+
+
+
+
+
+
+
+
GNU Free Documentation License
+
Version 1.2, November 2002
+
+
+Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+
+
+
+0. PREAMBLE
+
+
The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+
This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+
We have designed this License in order to use it for manuals for
+free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
1. APPLICABILITY AND DEFINITIONS
+
+
This License applies to any manual or other work, in any medium,
+that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The "Document", below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as "you". You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+
A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+
A "Secondary Section" is a named appendix or a front-matter section
+of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+
The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+
The "Cover Texts" are certain short passages of text that are
+listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+
A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called "Opaque".
+
+
Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+
The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+
A section "Entitled XYZ" means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as "Acknowledgements",
+"Dedications", "Endorsements", or "History".) To "Preserve the Title"
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+
The Document may include Warranty Disclaimers next to the notice
+which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
2. VERBATIM COPYING
+
+
You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+
You may also lend copies, under the same conditions stated above,
+and
+you may publicly display copies.
+
+
3. COPYING IN QUANTITY
+
+
If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+
If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+
If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+
It is requested, but not required, that you contact the authors of
+the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
4. MODIFICATIONS
+
+
You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+
+
A. Use in the Title Page (and on the covers, if
+any) a title distinct from that of the Document, and from those of
+previous versions (which should, if there were any, be listed in the
+History section of the Document). You may use the same title as a
+previous version if the original publisher of that version gives
+permission.
+
B. List on the Title Page, as authors, one or
+more persons or entities responsible for authorship of the
+modifications in the Modified Version, together with at least five of
+the principal authors of the Document (all of its principal authors, if
+it has fewer than five), unless they release you from this requirement.
+
C. State on the Title page the name of the
+publisher of the Modified Version, as the publisher.
+
D. Preserve all the copyright notices of the
+Document.
+
E. Add an appropriate copyright notice for your
+modifications adjacent to the other copyright notices.
+
F. Include, immediately after the copyright
+notices, a license notice giving the public permission to use the
+Modified Version under the terms of this License, in the form shown in
+the Addendum below.
+
G. Preserve in that license notice the full
+lists of Invariant Sections and required Cover Texts given in the
+Document's license notice.
+
H. Include an unaltered copy of this License.
+
I. Preserve the section Entitled "History",
+Preserve its Title, and add to it an item stating at least the title,
+year, new authors, and publisher of the Modified Version as given on
+the Title Page. If there is no section Entitled "History" in the
+Document, create one stating the title, year, authors, and publisher of
+the Document as given on its Title Page, then add an item describing
+the Modified Version as stated in the previous sentence.
+
J. Preserve the network location, if any, given
+in the Document for public access to a Transparent copy of the
+Document, and likewise the network locations given in the Document for
+previous versions it was based on. These may be placed in the "History"
+section. You may omit a network location for a work that was published
+at least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
K. For any section Entitled "Acknowledgements"
+or "Dedications", Preserve the Title of the section, and preserve in
+the section all the substance and tone of each of the contributor
+acknowledgements and/or dedications given therein.
+
L. Preserve all the Invariant Sections of the
+Document, unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
M. Delete any section Entitled "Endorsements".
+Such a section may not be included in the Modified Version.
+
N. Do not retitle any existing section to be
+Entitled "Endorsements" or to conflict in title with any Invariant
+Section.
+
O. Preserve any Warranty Disclaimers.
+
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+
You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+
You may add a passage of up to five words as a Front-Cover Text, and
+a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+
The author(s) and publisher(s) of the Document do not by this
+License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
5. COMBINING DOCUMENTS
+
+
You may combine the Document with other documents released under
+this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+
The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+
In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements."
+
+
6. COLLECTIONS OF DOCUMENTS
+
+
You may make a collection consisting of the Document and other
+documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+
You may extract a single document from such a collection, and
+distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
7. AGGREGATION WITH INDEPENDENT WORKS
+
+
A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+
If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
8. TRANSLATION
+
+
Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+
If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
9. TERMINATION
+
+
You may not copy, modify, sublicense, or distribute the Document
+except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
10. FUTURE REVISIONS OF THIS LICENSE
+
+
The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+
Each version of the License is given a distinguishing version
+number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GNU GENERAL PUBLIC LICENSE
+
Version 3, 29 June 2007
+
+
+
+ Copyright (C) 2007 Free Software Foundation, Inc. http://fsf.org/
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.i
+
+
+
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
+
+
+
+
+
+
+
+
+( ∂ )
+
+
+
+
+
+
diff --git a/doc/newlispdoc-man.txt b/doc/newlispdoc-man.txt
new file mode 100644
index 0000000..4db8ecd
--- /dev/null
+++ b/doc/newlispdoc-man.txt
@@ -0,0 +1,69 @@
+newlispdoc(1) Commandline Parameters newlispdoc(1)
+
+
+
+NAME
+ newlispdoc - generate documentation from newLISP source comments
+
+SYNOPSIS
+ newlispdoc [-s] lisp-file1 [lisp-file2 ...]
+
+ newlispdoc [-url] urls-file
+
+DESCRIPTION
+ newlispdoc is a commandline utility written in newLISP to generate HTML
+ documentation from comments written in newLISP source files. Consult
+ /usr/share/doc/newlisp/newLISPdoc.html for a detailed description on
+ how to write comments usable for newlispdoc. The newlispdoc command
+ should be executed from inside the directory where the newLISP source
+ files can be found. The generated documetation files will have .html
+ added to the name of the source file. An index.html page is generated,
+ which is listing for each file links to all the documented functions.
+
+OPTIONS
+ -s this option causes newlispdoc to also generate a syntax high-
+ lighted HTML file of the source. A link to this file will be
+ present in the HTML documentation of this file. The generated
+ file will have the added extension .src.html.
+
+ lisp-file
+ is a commented newLISP source file from which a documentation
+ file will be generated.
+
+ -url this option is used to retrieve newLISP source files for docu-
+ mentation from remote locations.
+
+ urls-file
+ is a file containing urls of newLISP source files, one url per
+ line.
+
+EXAMPLES
+ Generate all documentation form files in the current directory.
+ newlispdoc afile.lsp bfile.lsp
+
+
+ Generate documentation and syntax highlighted HTML versions from all
+ lisp files in the current directory
+ newlispdoc -s *.lsp
+
+ Retrieve source files for documentation from remote locations. Each
+ file is specified on one line in urls.txt with its http:// address.
+ newlispdoc -s -url urls.txt
+
+EXIT STATUS
+ newlispdoc returns a zero exit status for normal exit or writes a usage
+ message if not enough paramneters are supplied.
+
+AUTHOR
+ Lutz Mueller
+
+SEE ALSO
+ newlisp(1) - newlisp man page
+
+ http://www.newlisp.org/ - the newLISP home page
+
+
+
+
+version 1.4 January 2008 newlispdoc(1)
+
diff --git a/doc/newlispdoc.1 b/doc/newlispdoc.1
new file mode 100644
index 0000000..4f22f30
--- /dev/null
+++ b/doc/newlispdoc.1
@@ -0,0 +1,48 @@
+.TH newlispdoc 1 "January 2008" "version 1.4" "Commandline Parameters"
+.SH NAME
+.B newlispdoc
+\- generate documentation from newLISP source comments
+.SH SYNOPSIS
+.B newlispdoc
+[\-s] lisp\-file1 [lisp\-file2 ...]
+
+.B newlispdoc
+[\s] [\-url] urls-file
+.SH DESCRIPTION
+newlispdoc is a commandline utility written in newLISP to generate HTML documentation from comments written in newLISP source files. Consult /usr/share/doc/newlisp/newLISPdoc.html for a detailed description on how to write comments usable for newlispdoc. The newlispdoc command should be executed from inside the directory where the newLISP source files can be found. The generated documetation files will have .html added to the name of the source file. An index.html page is generated, which is listing for each file links to all the documented functions.
+.SH OPTIONS
+.TP
+\-s
+this option causes newlispdoc to also generate a syntax highlighted HTML file of the source. A link to this file will be present in the HTML documentation of this file. The generated file will have the added extension .src.html.
+.TP
+lisp\-file
+is a commented newLISP source file from which a documentation file will be generated.
+.TP
+\-url
+this option is used to retrieve newLISP source files for documentation from remote locations.
+.TP
+urls-file
+is a file containing urls of newLISP source files, one url per line.
+.SH EXAMPLES
+.TP
+Generate all documentation form files in the current directory.
+.B newlispdoc
+afile.lsp bfile.lsp
+.PP
+.TP
+Generate documentation and syntax highlighted HTML versions from all lisp files in the current directory
+.B newlispdoc
+\-s *.lsp
+.TP
+Retrieve source files for documentation from remote locations. Each file is specified on one line in urls.txt with its http:// address.
+.B newlispdoc
+\-s \-url urls.txt
+.SH EXIT STATUS
+newlispdoc returns a zero exit status for normal exit or writes a usage message if not enough paramneters are supplied.
+.SH AUTHOR
+Lutz Mueller
+.SH SEE ALSO
+newlisp(1) \- newlisp man page
+
+http://www.newlisp.org/ \- the newLISP home page
+
diff --git a/examples/client b/examples/client
new file mode 100755
index 0000000..9c132e5
--- /dev/null
+++ b/examples/client
@@ -0,0 +1,37 @@
+#!/usr/bin/newlisp
+
+;; client for client/server demo
+;;
+;; USAGE: client hostName
+;;
+;; 'hostName' contains a string with the name or IP number
+;; of the computer running the server application
+;;
+;; The client prompts for input and sends it to the
+;; server which sends it back converted to uppercase
+;;
+;; The server has to be started first in a different
+;; terminal window or on a different computer.
+;;
+;; v 1.3
+;;
+
+(define (net-client-receive socket , buf)
+ (net-receive socket 'buf 256)
+ (print "\n" buf "\ninput:")
+ (if (= buf "bye bye!") (exit))
+ (net-send socket (read-line)))
+
+(define (client host-computer)
+ (set 'socket (net-connect host-computer 1111))
+ (if (not socket)
+ (print "could not connect, is the server started?\n")
+ (while true (net-client-receive socket))))
+
+(if (not (main-args 2))
+ (begin
+ (print "USAGE: client hostName\n")
+ (exit)))
+
+(client (main-args 2))
+(exit)
diff --git a/examples/finger b/examples/finger
new file mode 100755
index 0000000..b68ac62
--- /dev/null
+++ b/examples/finger
@@ -0,0 +1,35 @@
+#!/usr/bin/newlisp
+#
+# v 1.1 changes for changed 'main-args'
+# v 1.2 eliminated 'net-cleanup'
+# v 1.3 replaced concat with append
+# v 1.4 direct string form of net-send, eplace name with user
+#
+
+(define (finger nameSite , socket buffer user site)
+ (map set '(user site) (parse nameSite "@"))
+ (set 'socket (net-connect site 79))
+ (if (not socket)
+ (begin
+ (print "Could not connect\n")
+ (exit)))
+ (if (not (net-send socket (append user "\r\n")))
+ (print "no connection\n")
+ (net-finger-receive socket)))
+
+(define (net-finger-receive socket , str)
+ (if (not (net-receive socket 'str 512))
+ (print "Receive failed\n")
+ (print "\n" str "\n"))
+ (if socket (net-close socket)))
+
+(set 'params (main-args))
+(if (< (length params) 3)
+ (begin
+ (print "USAGE: finger name@host\n")
+ (exit)))
+(finger (nth 2 params))
+(exit)
+
+;eof;
+
diff --git a/examples/form.cgi b/examples/form.cgi
new file mode 100755
index 0000000..a5aab36
--- /dev/null
+++ b/examples/form.cgi
@@ -0,0 +1,36 @@
+#!/usr/bin/newlisp
+#
+# Demo of CGI 1.1 interface
+#
+# version 1.1
+#
+# get form data from CGI STDIN parse and
+# write back to the client browser
+#
+#
+#
+
+
+(print "Content-type: text/html\r\n\r\n")
+(println "
")
+(dolist (e (env)) (print e " "))
+(println " ")
+(println "CGI by newLISP v." (sys-info -2))
+(exit)
diff --git a/examples/form.html b/examples/form.html
new file mode 100644
index 0000000..fc99c8d
--- /dev/null
+++ b/examples/form.html
@@ -0,0 +1,35 @@
+
+A form to check newLISP CGI
+
+
A test form for checking out the POST method in HTTP.
+
Change "localhost" in the action statement to the correct hostname, if trying this remotely.
+
+
+
diff --git a/examples/init.lsp.example b/examples/init.lsp.example
new file mode 100755
index 0000000..6c3feec
--- /dev/null
+++ b/examples/init.lsp.example
@@ -0,0 +1,61 @@
+;; init.lsp - newLISP initialization file
+;; gets loaded automatically on newLISP startup
+;; newLISP looks for it in: /usr/share/newlisp/init.lsp
+;;
+;; defines some useful macros, none of these
+;; are required in the other sample programs
+;; but some implement forms frequently used
+;; in other LISPs
+;;
+;; v.8.7.11
+;;
+;; fixed a wrong logic in conditional making of defun macro
+;;
+;; macro for 'defun' like in other LISPs
+;; usage: (defun foo (x y z) body1 body2 ... )
+;;
+;;
+(constant (global 'defun)
+ (lambda-macro (_func-name _arguments)
+ (set _func-name (append '(lambda ) (list _arguments) (args)))))
+
+
+;; edits a function
+;;
+;; usage: (edit foo)
+;;
+;; this will open and edit window for editing
+;; a functioon called "foo". After saving and
+;; exiting the editor newLISP will reload the
+;; function, which is also available in a file
+;; with the same name. Only for unix like OSs
+;;
+
+(if (< (& 0xF (last (sys-info))) 5)
+ (begin
+ (define-macro (edit _func)
+ (save (string "/tmp/" _func) _func)
+ (! (string "/usr/bin/vi /tmp/" _func))
+ (load (string "/tmp/" _func)))
+ (global 'edit)))
+
+
+;; this needs an installation of lynx, a character based web browser
+;; loads very fast, quickly exit with Ctrl-C
+;;
+
+(define-macro (help func)
+ (if (primitive? (eval func))
+ (let (func-name (name func))
+ (if (ends-with func-name "?") (replace "?" func-name "p"))
+ (! (format "lynx /usr/share/newlisp/doc/newlisp_manual.html#%s" func-name)))
+ (format "%s is not a built-in function" (name func))))
+
+(constant (global '$HOME) (or (env "HOME") (env "USERPROFILE") (env "DOCUMENT_ROOT")))
+(if $HOME (catch (load (append $HOME "/.init.lsp")) 'error))
+
+;;;; end of file ;;;;
+
+
+
+
diff --git a/examples/newLISP-Excel-Import.xls b/examples/newLISP-Excel-Import.xls
new file mode 100755
index 0000000000000000000000000000000000000000..effd54b9631e099089eac3fa98082b95f9cb3969
GIT binary patch
literal 26624
zcwX&24R}=5mFK;gOeP@-LkKhwz()ueAPMsmLV`pm^AiFlB$BA8(PWZ&kda9y%uEop
z;smsdyU^l4w%THCcV#UK+Sb;s72N*lsw=Jft=evj)^>Hf+p2XxYpc$lbMJjKZzhw3
zM6}v+!kK&Dx#ynycka2r?{WN@X(#SFGW%sngR{W^AH;LOq@zg!8CU@F(UB29h{xj^
zIer>GRq#Gy9=4kS(TJFZNNt{tXhzII%tf3c+W9l+&O@BaRRE?T79vhZEJB=tI1{lL
zaS7rq#My`?h;tC`?-ZblnxC2=7lcj
z52XSkS~gg54P8cM+uY8=~VtMdMl!v33c)eu8JjiIL
zo<+*T(o{gJ)zKG-To?*(?g@o9-+_SzXl^J%A^V-qe(z@@zQ=y+nW>rwdsYmW)w1GC
zut9b*zP;?Xl>HXquLKXVI4?1Z4UO32=*F+vC#o+?YCy#efDeKnacHrW2$fSq=Nac<
z_d}ChT2{KCV!;Ay*W$A}%e9Bj#q*5w(U{Lk3BP2$>c2FVsT8gK+$2+#HB}Bi6W5uj
zYo+O2Y0?Di3N-y_l)H$&MA1?fkDcWrVU18)S;|74T^O|rE&gJPs*jf%DJ{l1I4-PA
zO^oL)H9eL!U6SXVlN3>d!;npvs1|=j*wQ-Xut^zEuLuSrgH`@uPzem6Q17;0HHhno@}-JRu`3RxT3NmrO~+s;
z5?~4R4uvBqf_y4Qa@Xmzf*Hdkdws#6>W||z)eP@ov(R*wrmTEuv!o1dQ)Eq(_|*0{
zIFEgjEoI2!=i#p(r?%vu#(JIwWxjXt&7ZdPw4Kw%=t~%VDf`{YD6ympz(Q(ah{G_3
z95ZSY;$4jUTK3xl=OTL_4yg)a1bWf6qxG@kpMuXSv+gST#sbMW-}!Us&o=xrmMw`z
znIGM3ct0+)XTzBBKMZKnQ*3j+ckia2ig-UmP+Gs-wYOv;)D0eu=G*-%sp-oH$2wCA29rO;Y57#KcEt
zL%3PCh*fnTPZZbHL^Cj&5G82F3^Y>)nmLX3K2F9cjTtO$dLrplSui~r*^@y$nb;Fe
zluS^@WD(~*V3PUX&WZO5U;zm#L(ZcvIS$!!7V+Db{|C;4pT>|jbot-eav^-%L>20U
zB+RAc%q$HFQ$U~md$#Af0%&J}?RoQg_~^69)UBQur+u6=$h+8vXP{E0&WrcVpLiR}N6tbAmY2x^&onIA6l#y^fly?Y&43KJ3;`**dAW3HNM1>pez#{=XV=dlf<}{j?`Cp3X
zyubL#HEFvH?akz;N@=$wd^d9+hOgp2E%y@Yq7~cL%Kq$#wb&!-u$NfHpWf#lLDT(my
zSUqt6X#Dittz{%JIwyJ4(;ACTy{s0J;1tt`{qlY}Q+z6w#B9%7|9OjBMh*H9@WH=P
z=1FL(W|NBrJA4=#qS0`mXDAA)a)GOBov$A~^-5_+ACB7M?8~ybG(R_YkINU4Wi9vJ;51gw1rjwKHA3x(;7bN
zL__@n)0IY#VWOibvp;X3=P5K2&k;rDrGFOPGgIu(-t8x6eC2VkKmKi|LuRx{eRXYr~CgYgwy?he0qAinfM4kDgEE^
zsq6pY^JBnwA~eK)zvHufgM#fe
}))
+
+(exit)
\ No newline at end of file
diff --git a/examples/upload.html b/examples/upload.html
new file mode 100644
index 0000000..5ddfa80
--- /dev/null
+++ b/examples/upload.html
@@ -0,0 +1,14 @@
+
+File Upload
+
+
+
+
Upload File
+
+
+
+
diff --git a/examples/xmlrpc.cgi b/examples/xmlrpc.cgi
new file mode 100755
index 0000000..be741ff
--- /dev/null
+++ b/examples/xmlrpc.cgi
@@ -0,0 +1,223 @@
+#!/usr/home/nuevatec/bin/newlisp
+#
+# xmlrpc.cgi - CGI script to handle XML-RPC requests
+#
+# This is similar to xmlrpc-server, but stateless as a new
+# newLISP process is invoked everytime this script is executed.
+# For a XML-RPC server maintaining state run xmlrpc-server.
+#
+# v.1.0 - 2005-01-14 Lutz Mueller
+#
+# v.1.1 - 2005-03-20
+# method name for newLISP.evalString was listed wrong
+#
+# supports the following methods:
+#
+# Method Return Parameter
+# ------ ------ ---------
+# system.listMethods string n/a
+# system.methodHelp string string
+# system.methodSignature array string
+# newLISP.evalString base64 base64
+#
+#
+
+(set 'version "1.0")
+
+# formatting templates for responses
+
+(set 'normal-response
+[text]
+
+
+
+ %s
+
+
+
+[/text])
+
+(set 'fault-response
+[text]
+
+
+
+
+
+ faultCode
+ %d
+
+
+ faultString
+ %s
+
+
+
+
+
+[/text])
+
+
+# event handler called when newLISP receives a request
+
+(define (process-post request)
+ (if (not (catch (handle request) 'page))
+ (set 'page (format fault-response 0 page)))
+ (print
+ "Content-type: text/xml\r\n"
+ "Content-length: " (length page) "\r\n\r\n"
+ page))
+
+
+(define (handle input, XML contentlength methodName params)
+ (set 'XML "")
+ (xml-type-tags nil nil nil nil)
+ (if (not (set 'XML (xml-parse input (+ 1 2 4 8 16))))
+ (begin
+ (if (not (xml-error))
+ (error 3 "No XML or XML is empty")
+ (error 4 (append "XML error: "
+ (first (xml-error))))))
+
+ (set 'XML (first XML)))
+
+ ; get methodName and parameter section
+ (set 'm (match '(methodCall (methodName *) *) XML))
+ (if (not m)
+ (error 5 "Invalid XML-RPC format"))
+
+ (set 'methodName (first (first m)))
+ (set 'params (last m))
+
+ (case methodName
+ ("newLISP.evalString" (newLISP.evalString params))
+ ("system.listMethods" (system.listMethods))
+ ("system.methodHelp" (system.methodHelp params))
+ ("system.methodSignature" (system.methodSignature params))
+ (true (error 6 "Method name not known")))
+)
+
+(define (error no msg)
+ (throw (format fault-response no
+ (append "newLISP XML-RPC v." version " - " msg))))
+
+
+######################### remote callable methods ##############################
+
+(define (system.listMethods)
+[text]
+
+
+
+ system.listMethods
+ system.methodHelp
+ system.methodSignature
+ newLISP.evalString
+
+
+
+[/text])
+
+
+(define (system.methodHelp params, methodName)
+ (set 'methodName (nth 0 1 1 1 1 params))
+ (case methodName
+ ("system.listMethods" (format normal-response "Lists all methods implemented."))
+ ("system.methodHelp" (format normal-response "Documents a method."))
+ ("system.methodSignature" (format normal-response "Shows the signatures of a method."))
+ ("newLISP.evalString" (format normal-response "Evaluate a base64 encoded string."))
+ (true (error 7 "Method name in system.methodHelp not known")))
+)
+
+(define (system.methodSignature params)
+ (set 'methodName (nth 0 1 1 1 1 params))
+ (case methodName
+ ("system.listMethods" (format normal-response
+"
+
+
+
+
+ array
+
+
+
+
+"))
+
+ ("system.methodHelp" (format normal-response
+"
+
+
+
+
+ string
+ string
+
+
+
+
+"))
+
+ ("system.methodSignature" (format normal-response
+"
+
+
+
+
+ array
+ string
+
+
+
+
+"))
+
+ ("newLISP.evalString" (format normal-response
+"
+
+
+
+
+ base64
+ base64
+
+
+
+
+"))
+
+ (true (error 7 "Method name in system.methodSignature not known")))
+)
+
+(define (newLISP.evalString params, m, result)
+ (set 'm (match '((params (param (value (base64 *))))) params))
+ (if (not m)
+ (error 8 "Invalid format for method newLISP.evalString")
+ (set 'result
+ (string (eval-string (base64-dec (first (first m))) (error-text))))
+;; "This function has been disabled in this demo for security reasons.")
+ (format normal-response
+ (append "" (base64-enc result) "")) )
+)
+
+
+########################### MAIN ENTRY POINT #######################
+
+(set 'input (read-line))
+
+(if (not input)
+ (print
+ "Content-type: text/html\r\n\r\n"
+ "
newLISP XML-RPC v." version
+ ": not a valid XML-RPC request
")
+ (begin
+ (while (read-line) (write-buffer input (current-line)))
+ (process-post input))
+)
+
+
+(exit)
+
+
+# eof
diff --git a/guiserver/CHANGES b/guiserver/CHANGES
new file mode 100644
index 0000000..7eaee2b
--- /dev/null
+++ b/guiserver/CHANGES
@@ -0,0 +1,802 @@
+0.2
+ documentation corrections regarding default layout of frame and dialog
+
+ switchable look-and-feel with (gs:set-look-and-feel )
+ now on Windows the Windows look and feel is chosen correctly by default
+
+ speedup of interpreter
+
+0.3
+ suppressed nullpointer error when using gs:set-look-and-feel
+
+ supppress Java error messages on Windows when shuttng down program
+
+ gs:label now can take optional width height has last parameters
+ before ann extra gs:set-size statement was necessary
+
+ width and height specified in gs:button did not work, does now
+ (note that for all other buttons/check-box an extra gs:set-size
+ must still be used to change the size, it will not be added as
+ optional parameters, as it is almost never used)
+
+ now image-button can take pressed icon path after the normal path
+ (gs:image-button 'TheButton "/local/run32.png" "/local/run32p.png")
+
+ now gs:set-color working on frames and dialogs too
+
+ font-demo.lsp showing the fonts built-in on all platforms
+
+ new gs:text-pane for HTML and RTF (future version) formatted text
+ see html-demo.lsp for a demo.
+
+0.4
+ allow multiple re-starts from same newlisp process, this works together
+ with (gs:listen true)
+
+ parenthesis matching in text-pane and tab-size working on text-pane,
+ will only work on "text/plain" flavore of text-pane
+
+ console.lsp now remembers last directory in file dialogs save/load
+
+ console.lsp now has list boxes for browsing contexts and variables
+
+ changed split-pane syntax adding divider size, leaving out width/height
+ which can be set with extra set-size if required
+
+ combo-box and list-box life update now works and updates the screen
+ correctly
+
+ new gs:clear-list empties out a combo-box or list-box
+ eliminated redundant 'action' parameter on message-dialog
+
+ new confirm-dialog similar to message-dialog but 'yes', 'no' and optional
+ 'cancel' button and fires an event.
+
+0.5
+ gs:set-size now works on frames
+
+ new gs:remove-from removes one or more components from a container
+
+ new gs:select-text, gs:cut-text, gs:copy-text and gs:paste-text
+ with suport for system clipboard, new gs:insert-text
+
+ gs:set-background/set-color now can take a list for the r g b
+ color components
+
+ list-box now also fires event on key-entering a selection, previously only
+ on mouse-double-click
+
+ avoid Java "index out of bound messages" in parenthesis matching
+
+ restructured text-area and text-pane event:
+ (define (action-handler id code dot mark) ...)
+
+ id = name of text widget
+ code = code of character
+ dot = caret position
+ mark = selection position
+
+ if there is no selection then dot and mark are equal
+ if only the caret was moved then code is 65535 (16bit -1)
+
+ working logic for highlighting of cut/copy save/saveAs buttons and
+ related menu items in console.lsp
+
+ working logic of maintaining directories and filenames in commonly
+ established fashion between file operations
+
+ NOTE, console.lsp has been little tested, do not use in production,
+ no confirmation dialogs yet for overwiting files, save before new, etc.
+
+ NOTE that console.lsp is broken on Windwos because iof filepath issues
+ and CR-LF issues in parenhesis matching
+
+ many documentain fixes
+
+0.6
+ gs:set-font working on combo-box and list-box
+
+ parenthesis matching in text-pane working now on Windows too
+
+ file operations working in console.lsp on Windows
+
+ confirm dialog for new button in console when edit buffer is touched
+
+ eliminated crashes with bigger results in output area of console
+
+ context stays selected in console
+
+ console new button action will not reset current directory for file operations
+
+ request-focus now works on text-area and text-pane
+
+ eliminate Java error messages on listboxes
+
+ new gs:select-list-item selects a list box or combo box item
+
+ documentation changes for border-layout and others
+ fixed many documantatin formatting problems
+
+0.7
+ because of a change in gs:listen in v. 0.6 all error messages from
+ guiserver where suppresses, which made debugging difficult. Some applications
+ running in guiserver v.0.6 may fail now because error messages are enabled
+ again. E.g. misspelled or missing action handlers would cause no harm
+ in v.0.6, but will let exit an application with an error message in v.0.7.
+
+ gs:window creates a wimndow without any border and system bar. On MacOX X
+ when setting the background in such a window to
+ (gs:set-background 'thewindow 0 0 0 0)
+ totally transparent, the window will be invisible and widgets ppaced on it
+ seem to float on the desktop (e.g. text from labels)
+
+ the second to- parameter in gs:select-text is now optional and the function
+ will select all text from the from- position to the end of the text.
+
+0.8
+ text-panes and text-areas did not scroll after ading to tab, fixed
+ added action event to gs:tabbed-pane
+ (gs:tabbed-pane
+ [ ...])
+ the event reports: tabbed-pane-id tab-id tab-title.
+
+ console.lsp project renamed to newlisp-console.lsp instead, which is a
+ multi tab lisp editor with run button and console window
+
+ in scrollable text-pane and text-area after gs:set-text will scroll
+ to the beginning, after gs:append-text will scroll to end
+
+ can use gs:set-text in the tabs of a gs:tabbed-pane
+
+ can use gs:set-icon in the tabs of a gs:tabbed-pane
+
+ more demos: frameless-demo.lsp and clipboard-demo.lsp
+
+0.9
+ Several functions to retrieve system properties:
+ gs:get-version - gets the GUI server version number
+ gs:get-screen - gets width, height and resolution of the screen
+ gs:get-fonts - gets all fonts on the current system
+
+ The following system variables can be used after a property function has
+ been call once:
+ gs:version - the version number
+ gs:screen - list of screen parameters
+ gs:fonts - list of all fonts
+ Once a function has been callled onlyt the variables should be used
+ for efficiency
+
+ two new demos: properties-demo.lsp, allfonts-demo.lsp
+
+ increased possible text size for events from 100K to 1000M
+ (mainly for editor)
+
+ for do-nothing buttons or or other widgets specify 'gs:no-action as
+ action-handler
+
+0.93 First 2D canvas and mouse stuff
+ gs:set-select now working for toggle-button, radio-butoon, check-box
+
+ gs:mouse-clicked, gs:mouse-dragged, gs:mouse-moved, gs:mouse-pressed
+ and gs:mouse-released
+
+ new demos mouse-demo.lsp shapes-demo.lsp animation-demo.lsp
+
+ gs:draw-line, gs:draw-rect, gs:draw-circle
+ gs:fill-rect, gs:fill-circle (raound-rect and ellipse in next version)
+
+ gs:paint (gs:stroke for line width in next version)
+
+ gs:delete-tag to delete a tagged group of shapes
+ gs:moce-tag to move a tagged group of shapes
+
+0.94
+ fixed message box in newlisp-edit.lsp when no c:\temp on Windows
+
+ gs:paint renamed to gs:set-paint
+
+ last gs:set-paint now gets correctly taken when now color is specified in
+ shapes or text
+
+ now different fonts on same canvas don't overwrite previous
+
+ documentation for draw-text had syntax in reverse
+ all graphics functions now sorted into all other Functions
+ spellchecked documentation
+
+ lines are now movable too
+
+ gs:set-canvas - onlye used for switching between muliple canvases
+ gs:set-translation - move coordinate origin
+ gs:set-scale - scales up or down
+ gs:set-stroke - sets drawing line width and optional cap, join and miter limit
+ gs:draw-arc - draw an arc outline
+ gs:fill-arc - paints a filled arc
+
+ new stroke-demo.lsp - shows lines and outlimes with different strokes and round
+ line ends
+
+ GUI-server signon message now contains version number. Note that in the future
+ newLISP binary installers for Mac OS X and Win32 icons will be placed in the
+ Mac OX X application folder and Win32 desktop for the newlisp-edit.lsp application.
+ Then the signon and connection messages will be unvisible. They are more thought
+ as a debugging aid duwing development.
+
+ On Mac OS X and UNIX applications can be started this way to close the terminal/shell
+ window:
+ newlisp newlisp-edit.lsp & exit
+ this places the GUI-server process into the background and closes the termonal/shell
+
+0.95
+ fixed newlisp-edit.lsp temporal directory detection (again, thanks Sleeper)
+
+ gs:move-tag did not distinguish between tags, fixed
+
+ gs:set-select can take multiple id, flag pairs, fixed
+
+ gs:split-pane divider width in split-pane did not work, fixed
+
+ new gs:draw-ellipse - draws an elllipse outline
+ new gs:fill-ellipse - fills an elllipse
+
+ new gs:set-translation of the canvas origin coordinates
+ new gs:set-rotation set the rotation of the canvas
+
+ all tag transforms below add to the affine transform matrix
+ already in the canvas
+
+ new gs:hide-tag - hides objects of a tag group
+ new gs:scale-tag - scales an object up or down
+ new gs:translate-tag - translates the coordinate origin of a tag group
+ new gs:show-tag - shows objects of a tag group
+ new gs:rotate-tag - function for rotating objects
+ new gs:shear-tag - function for shearing objects
+
+ like gs:move-tag all other functions work on any shape, text
+ or image.
+
+ shaped-demo.lsp modified to show funtioning of gs:hide-tag and gs:show-tag
+ via selecting or de-selecting shapes with check boxes
+
+ gs:mouse-wheel - register mouse wheel events
+
+ mouse-demo.lsp - modified to show mouse wheel events
+
+ animaton-demo.lsp - modified to show the mouse wheel move text up/down
+
+ new rotation-demo.lsp to show rotating objects
+ new image-demo - shows image zzomin, turning and squashing
+ new textrot-demo - shows text rotation
+
+ gs:draw-text has optional angle parameter (but can also be titled
+ using gs:rotate-tag, see sample program text-rotation.lsp)
+
+ all tag operations have optional flag to turn of screen update
+ this is recommended when using several tag commands in a batch
+ to do only one screen update at the end using gs:update
+ the default for this flag is 'true' for doing the update.
+
+ On all other systems except Mac OS X, double buffering is tried for
+ flicker free performance when animating graphics on systems other than
+ the Mac. The performance of this depends on the graphics cards used.
+ Performance was execellent on 2 Windows system I tried, one of them
+ 4 years old.
+
+0.96
+ gs:scale-tag, gs:translate-tag and gs:rotate-tag add to the affine transform matrix
+ already in the canvas (it was wrongly stated before that gs:translate-tag
+ if not accumulative, but it is like all others)
+
+ Corrections in the doc about the behaviour of gs:set-translation, gs:set-scale
+ and gs:set-rotation. Again: they are all absolute, while tag operations are
+ accumulative.
+
+ rotation-demo.lsp and image-demo.lsp have been changed using gs:translate-tag
+ instead the global canvas gs:set-translation. This makes it possible to
+ rotate or scale several tags at the same time, using gs:translate-tag
+ to supply each tag group its own center (set to 0,0). This leads also
+ to better readable code. All object cooridnates to rotate or zoom are
+ best defined in reference to a 0,0 center point and then moved to their
+ pace with gs:translate-tag. See also description of gs:scale-tag in documentation.
+
+ net gs:get-font-metrics - returns width and height of a string to display
+ new gs:draw-round-rect - draw a rectangle with round corners
+ new gs:full-round-rect - fill a rectangle with round corners
+ new gs:draw-polygon - draws a polygon with 3 to N points
+ new gs:fill-polygon - fill a polygon with 3 to N points
+ new gs:set-cursor - set one of 14 cursor shapes
+
+ new cursor-demo.lsp tot show different cursor shapes
+
+0.97
+ gs:mouse-dragged fired invalid events when not defined but gs:mouse-clicked
+ was defined.
+
+ gs:mouse-pressed, gs:mouse-released and gs:mouse-clicked now take an optional
+ 'true' parameter. This makes events carry a list of tags, which have been
+ affected by one of the above mouse actions. This can be used to implement
+ object dragging (see the new drag-demo.lsp) it also opens the possibility
+ of creating self-drawn custom controls on a canvas because clicks can be
+ detected on tags. The code mouse-demo.lsp has been simplified to detect
+ tags to delete by using the tag list in the mouse-clicked event.
+
+ events generated by gs:mouse-pressed, gs:mouse-released, gs:mouse-clicked
+ and gs:mouse-dragged besides the new tags spec also carry a number for
+ modifier keys, e.g. pressing ctrl or shift while clicking the mouse.
+ See the modified moused-demo.lsp.
+
+ gs:text-pane and gs:text-area now can register gs:mous-clicked events
+ in the newlisp-edit.lsp app a popup has been implemented as a right click
+ (or ctrl-click for one-button mouse) to popup an edit menu.
+
+ new drag-demo.lsp
+
+ Point detection is implemented for closed shapes, images and text. Precise
+ deletection is done for images, text, polygons and rectangles, but for
+ circles and ellipses the whole rectangle enclosing the shape is used
+ for calculations. A precise point detection limited only to the inside
+ of the circle or ellipse will be implemented at a later time.
+
+ Images must carry width and height parameters in the gs:draw-image statement.
+ Drawn text is detected by calculating the enclosing rectangle.
+
+ new gs:draw-path - similar to polygon but the path may stay unclosed.
+ new gs:export - exports to an image file in png in RGB + alpha channel
+ format.
+
+ Note that detection will fail if scaling or translation has been used to
+ for the canvas or drawn objects involved, because mouse coordinates do
+ not sync to object coordinates in a scaled or translated coordinate
+ system.
+
+ new gs:menu-pop and gs:show-popup implements popup menus for gs:text-area,
+ gs:text-pane and gs:canvas. For a demo see newlisp-edit.lsp and
+ drag-demo.lsp
+
+ bug fixes in newlisp-edit.lsp when closing other but the last tab.
+
+0.98
+ popup menus on canvas now also working on Win32
+
+ gs:open-file had problems with file masks (changed parameter format)
+
+ new gs:frame-closed - registers an event for a closing frame or dialog
+
+ new gs:find-text - finds and selects text in a text rea or text panel widget
+
+ new gs:mouse-event - registers a general mouse-event for any component
+ see allfonts-demo.lsp, button-demo.lsp and the Fontbook button in
+ newlisp-edit.lsp for demo
+
+ changed some shortcut keys in newlisp-edit.lsp to be more standard conform
+
+ newlisp-edit.lsp has now text search and replace implemented
+
+ newlisp-edit.lsp now has fontselection implemented
+
+ splash screen working, see doc for new gs:dispose-splash
+
+0.99
+ gs:find-text selection now positions and highlights correctly on Win32
+
+ now showing directories on Win32 even when file view is constrained to text files:
+ .lsp .c .h .txt .java .htm .html .css .php .pl .py .rb .lisp .el .cl .cpp
+ what are other essential text formats on Win32?
+
+ graceful error recovery on most errors in GUI-server: after the error
+ message box is closed, the app will try continue and not exit as before.
+
+ better parenthesis matching performance on larger files
+ (but minor flicker on Win32)
+
+ gs:get-font-metrics got stuck on last queried value
+
+ gs:set-tab-size when used on gs:text-pane, sets the tabsize in points
+
+ added ctrl-M to clear monitor area in newlisp-edit.lsp
+
+ find previous, undo and redo in newlisp-edit.lsp
+
+ new gs:undo-text and gs:redo-text, if no menus or code is used
+ ctrl-z and ctrl-shift-z and meta-z meta-shift-z (MacOS X) are
+ still hardwired into gs:text-pane
+
+ text widgets now also respond to the general gs:mouse-event
+
+0.991
+ Text selection was still broken on Win32 when starting out with a file containing
+ carriage returns or when entering new text. It only worked on files loded without
+ CRs even when etering new text. Now it seems to work in all situations, setting
+ a Java system property to LF only and converting text when it goes in/out.
+
+ Changed run button to auxiliary stateful newLISP process as used
+ previously in console.lsp. Now evaluation via the newLISP run button
+ is stateful unless the restart button is hit to restart the
+ other newLISP process. If the process exits, e.g. when closing a GUI-server
+ applications the small LED turns red. When hitting the run-newLISP button
+ and the newLISP process is down, it will get restarted automatically.
+
+ Only one GUI applocation should be started at the time from newlisp-edit.lsp
+ starting more than one is unreliable and blocked on MacOX X.
+
+ There are som unreliabilities running GUI-Server apps from newlisp-edit.lsp
+ on Win32, which have not been worked out. Text in the edit area should be saved
+ before running a GUI-server app, to be safe.
+
+
+0.992
+ File dialog file mask selection was broken again
+
+0.993
+
+ Eliminated flicker when matching parenthesis in bigger files.
+
+ A canvas now can be treated like any other container adding other
+ widgets to it (see demo textrot-demo.lsp).
+
+ Custom control for font coolors and size in newlisp-edit.lsp
+
+ Now newlisp-editor.lsp stays functional while a lengthy evaluation
+ process is running and outputing to the monitor area. In another tab
+ files can be edite/saved etc.
+
+ Auxiary newLISP process in newlisp-edit.lsp now starts with home directory as
+ current directory
+
+ Trying to start a second evaluation or trying to restart the newLISP process
+ will make the led blink in yellow for a second and output "busy" in the monitor
+ area.
+
+ Trying to quit newlisp-edit.lsp while an evaluating process is running will
+ leave the newlisp-edit.lsp application unfunctional on the screen until the
+ evaluating process finishes. On MacOS X the Quit option of the top screen menu
+ can be used to exit newlisp-edit.lsp in this case but on Win32 the task manager
+ must be used to shut down newlisp-edit.lsp or the other evaluating process.
+
+0.994
+ Many fixes for running programs from the editor. There should be no possibility
+ now to hang the editor, even if a pending newLISP evaluation cannot be finished,
+ the editor should be still functional to edit and save files.
+
+ The yellow led will now stay on when a newLISP evaluation is pending to exit and
+ an attempt has been make to start a second process. When the process has finished
+ the led goes red. Attempting to start another app will do a restart automatically.
+
+ Running GUI-Server apps from newlisp-edit.lsp seems to be reliable now on MacOX X
+ and Windows XP.
+
+ new menu 'File/Save Settings' saves all font, color and current directory when
+ loading file. The settimgs file contains many more settings, which can be changed
+ to give the editor a complete diferent appearance:
+
+ - The toolbar can be hidden completely or made floatable.
+ - The tabs can be relocated to the bottom, left or right side of the editor.
+ - The window size can be set to a desired X,Y width and height.
+
+ When newlisp-edit.lsp starts the first time and does not encounter a config file
+ it gets created in the current home directory.
+
+ File and settings saving is announced in the monitor area.
+
+ Note, the directory remembered when open the file dialog is the directory of
+ the currently open tab.
+
+ An optional icon can be added to gs:message-dialog when defining the type as "plain".
+ In this case a user supplied icon will be shown.
+
+0.995
+ newlisp-edit.lsp:
+
+ - Font size did not get saved by 'File/Save Settings'.
+
+ - settings file ion Win32 gets now written to APPDATA/newLISP/newlisp-edit.conf
+ where APPDATA is the Win32 environment variable for the applications data
+ directory. If APPDATA is not defined USERPOFILE or DOCUMENT_ROOT is assumed
+ On all other OS .newlisp-edit.conf is written to the users home directory
+ in UNIX like fashion. This may change in the future for the Mac OX X to:
+ ~/Libarary/Application Support/newLISP/newlisp-edit.conf
+
+ - The toolbar can now be detached/reattached from the View menu
+
+ - The Tool menu as a 'Save Settings' option.
+
+ - The Help menu has options to access newLISP and GUI-Server docs.
+
+ - When editing the settings file and leaving an error, the next startup
+ of newlisp-edit will give an error message box with the error.
+
+ - Ctrl-F (Win32) or meta-F (OS X) reenter the find dialog if not already
+ open (this was already in 0.994, but not mentioned).
+
+ - Pressing ESC while in find dialog text field will close the find dialog
+ this is consisten with behaviour of other Java-Swing built-in dialogs.
+ When in the edit area ctrl-D / meta-D, will still work to dispose of the
+ find-dialog
+
+ - on Mac OS X ctrl-up will select the tab, then keys left or right will
+ let select other tabs. This is Java-Swing built-in behaviour and assumed
+ to work like this on all platforms.
+
+ New gs:menu-item-check for checked menu items (behaves like a check box)
+
+ A new chapter about writing and debugging event handlers was added in the
+ guiserver.lsp.html documentation.
+
+ 0.996
+ newlisp-edit.lsp:
+
+ - settings will now remember loaction and size of newlisp-edit.lsp on the screen
+
+ - Edit/Find marked edit buffer as dirty, which was not correct (icon and red dot)
+
+ - new menu option Edit/Goto Line
+
+ - mew menu option Files/Recent Files remembers a list of recently saved files
+ the list is automatically updated each time a file is saved and maintained in
+ the file $APPDATA/newlisp-edit-recent on Win32 or in $HOME/.newlisp-edit-recent
+ on Mac OS X and Unix
+
+ popup menus now displayed in correct position on scrollable content
+
+ gs:get-bounds was broken, now displayes on-scrren coordinates for top level windows
+
+ new gs:goto-text - positions cursor in text at row columns position
+
+ new gs:load-text, gs:save-text to directlty load/save docs in to/from gs:text-pane
+ these should not be used from Win32 because they don't work correctly with
+ CR/LF line terminated files when using Edit/Find
+
+ documentation links in the Help menu have been taken out, because browser
+ blocks guiserver.jar from exiting on Win32
+
+ 0.997
+ When using gs:load-text it now correctly filters carriage returns when
+ loading files on Win32 or any other platforms. gs:save-text will always
+ write LF line terminations. If this is not desirable, gs:get-text should
+ be used instead.
+
+ ESC in find dialog also works when cursor in replace text field. ESC will close
+ the dialog without initiaiting search action, as it did wrongly before.
+
+ demo directory accessible from the Help menu
+
+ Many additions and corrections to the documentaion.
+
+0.998
+ new gs:set-syntax-selected for enabling newLISP syntax highlighting in gs:text-pane
+
+ new gs:set-caret-color for setting a caret color in in all text widgets
+
+ new gs:set-selection-color for setting a text selection color
+
+ new gs:set-syntax-colors for setting syntax colors for keywords, comments etc.
+
+ new gs:key-event to register key events for any component (except text widgets,
+ which already register keyevents by default)
+
+ syntax highlighting in newlisp-edit.lsp:
+ - 3 preconfigured themes to choose from for medium, low and high contrast
+ - alt-Y (Win32) or meta-Y (Mac OS X) toggle syntax highlighting on/off
+ - by default all files ending in .lsp are highlighted
+
+0.999
+ newlisp-edit.lsp:
+
+ - any number of syntax profiles can now be configured in the settings file and
+ loaded automatically into the View menu on startup.
+
+ - for the Tool menu scripts can be registered using the settings file. The
+ scripts are run over the content of the current edit tab. The contents of the
+ current edit tab is saved to a tmporary file, and the name of this file is passed
+ as an argument to the script. The output of the script is shown in the monitor
+ area.
+
+ - added tabulator size (in points) to settings file
+
+ - syntax on/off is remembered when switching tabs
+
+ - Edit/Get Position tells line and column positin of text cursor
+
+ - undo/redo was broken when in syntax highlighting mode. Undo/redo is now reset
+ whenever switching syntax highligthing on/off. Loading a file is not part of an
+ undoable operation anymore.
+
+ - eliminated foreground/background color options which are set as part of
+ the color theme. When syntax highlighting is tirned off, foreground and background
+ are still defined by the colors of the current theme.
+
+ - non-existing files in the recent files list are eliminated automatically
+
+ - now remembers correctly screen positions in settings file on all platforms
+
+ - eliminated black flash before splash screen display
+
+ - startup on Win32 w/o run.exe now shows hour glass cursor
+
+ - Clear Monitor disable/enable was faulty
+
+ - now highlights search text when returning to find/replace dialog
+
+ - message box when saving failed, e.g. becuase of wromg permissions
+
+ gs:set-cursor now works correctly in text widgets.
+
+ gs:get-bonds now works correctly for on-screen widgets
+
+1.0 feature complete for release August 15th
+
+ fixed unreliable gs:layout
+
+ fixed occasional text blur in monitor area of newlisp-edit.lsp
+
+ new gs:get-selected-text, works like gs:get-text but retrieves selected text only
+
+ added C, C++, Java and PHP syntax highlighting, automatically selected for .c, .cpp, .h,
+ .java and .php files. When a file does not have a known extension when loading, then no
+ syntax highlighing is selected. But when switching highlighting on via View/Syntax
+ or meta-Y (OS X) or alt-Y (Win32), a menu pops up for selecting a highlighting mode.
+
+ some small fixes for newLISP syntax highlighting
+
+ now 2 types of scripts in Tool menu and registered in currentScripts in settings file:
+
+ - Type "content" takes the contens of the edutor and passes it as a file to the script.
+ Anything printed in the script goes to the monitor area in the editor. See the
+ program word-count.lsp for an example
+
+ - Type "selection" takes the selection of the editor and passes it as a file to the
+ script. Anyting printed from thr script replaces the selectin. If nothing
+ was selected the output og the script gets inserted at the text caret.
+
+ The selection replace/insert type of script operation can be undone using Edit/Undo.
+ In the settings file: the menu string, the script path name, the type and an
+ optional shortcut key are specified. See the settings file for an example.
+
+ The settings file gets automatically created when not present on startup
+ and registers the two scripts word-count.lsp and uppercase.lsp. The settings file
+ can be edited using the option in the Tools menu.
+
+ before installing this version remove old settingfile on Win32:
+ $HOME/Application Data/newLISP/newlisp-edit.conf or on Mac OS X and Unix:
+ ~/.newlisp-edit.conf
+
+1.01 August 15th release
+
+ In newlis-edit.lsp: changed key assignments for fonts smaller/bigger:
+ meta-minus and shift-meta-equals on Mac OS X and ctrl-minus ctrl-equals on Win32.
+ For Mac OS X this is standard, for Win32 it mimics FireFox behaviour.
+
+ The items in gs:list-box and gs:combo-box can be either given individually
+ or in a list: (gs:list-box 'TheListBox 'list-action '("a" "b" "c))
+
+ New gs:play-sound plays/streams .wav and .aif sound files.
+
+
+1.03
+ The monitor area now works also as a newLISP shell, where expressions can
+ be typed in directly and evaluated. The red/green led is not necessary
+ anymore. The shell can be restarted at any time, even if a process is running.
+ The run button will only work if the shell is present. If the shell is exited
+ by a program, hit the restart button to restart. When restarting the shell
+ while a program in it is running, the program will quit and the shell restart.
+
+ When the monitor/shell area has focus:
+ Ctrl-l clears monitor and gives shell prompt (like Meta-m/Alt-m)
+ Ctrl-p copies previous command
+ Other common readline/editing commands usual in UNIX shells may be implemented
+ in the future.
+
+ On Win32 Ctrl-l used to be "goto line" now: Alt-l
+ On Win32 Ctrl-Shift-l used to "show current line/column" now: shift-Alt-l
+
+ newLISP-edit can be exited at any time, if a process is still running in the
+ shell window it keeps on running after newLISP-edit closed.
+
+ New gs:run-shell installs a shell process in the monitor area
+ New gs:eval-shell send a string for evaluation in the shell
+ New gs:destroy-shell destroys the shell
+
+ Note that newlis-edit.lsp uses newISP as a shell process, but other shells
+ can be started using gs:run-shell.
+
+ New gs:reorder-tags reorders the stacking order of tagged images.
+ See the file drag-demo.lsp for usage (comment in gs:reorder-tags statement
+ in line 47)
+
+1.04
+ Monitor background and foreground colors are now configuable in settings file
+ do a File/Save Settings first to have the new config variables registered, then
+ Tools/Edit Settings for editing: currentMonitorBackground and currentMonitorForeground.
+
+ Fix when evaluating in shell area after Ctrl-L, Meta-M (Alt-M).
+
+ Eliminated some quirks when copying/pasting between editor and monitor/shell area, and
+ when hitting enter in the middle of an edited command.
+
+ Now full commandline history in shell-commandline when using arrow-up/down.
+
+ meta-1, meta-2 (alt-1, alt-2 on Win32) for switching between editor and shell/monitor.
+
+ More bash-shell like key bindings on UNIX: Ctrl-A beginnining of line after the
+ shell prompt , Ctrl-E end of line (in gs:text-area with shell attached).
+
+ new gs:color-tag colors all shapes with the same tag
+
+1.05
+ gs:get-text now can be called without an action handler to return the text
+ immedeately. This new synchronous mnode of gs:get-text is not recommended when
+ receiving larger text areas, as the call is blocking until all text is returned,
+ but makes coding simple data forms a lot shorter.
+
+ gs:mouse-move now can take an additional boolean parameter to indicate that
+ a list of tags are to be returned in the mouse-move event handler. The flag
+ should not be used when large amount of tags are present as it can slow down
+ performance significantly calculating and transmitting tag lists on every
+ mouse movement.
+
+ gs:key-event now also can be registered as a second key listener on text widgets.
+ This is espacially interesting on gs:text-field, where individual key action
+ could not be captured before, as the normal handler registered with gs:text-area
+ only handles the ENTER and ESC key.
+
+ fix in gs:run-shell for shells without prompts
+
+ now uses patform independent:
+ (load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+ in all demo files to load guiserver.lsp
+
+1.06
+ edit buffer did not get marked as dirty when cutting/pasting into clean buffer
+
+ when file-recent-loading->saving->file-recent-reloading the same file editor crashed
+
+ make sure shell proccesses in monitor window are destroyed when closing newlisp-edit
+
+ because of new 'process' in newlisp core full java path is needed in process statement
+ in gs:init function. Assumes /usr/bin/java
+
+1.07
+ Tcp/Ip connection between Guiserver and newLISP now goes via 127.0.0.1, not localhost
+ to avoid loss of connection when computer sleeps, while an GS application was
+ running.
+
+ when runniung editor contents and shell is dow, the shell will be restarted
+ automatically
+
+ the editor now loads, saves and displays UTF-8 correctly
+
+1.08
+ Guiserver now adjusts automatically to set UTF-8 on/off depending on newLISP version
+
+ The Win32 is again shipped as not UTF-8 by default.
+
+ new gs:window-moved and gs:window-resized. See new demo file move-resize-demo.lsp
+
+1.09
+ reverse "meta N" and "shift meta N" on OS X to be standard with "meta N" new window/tab
+ on OS X
+
+ gs:mouse-event now can also be used on list boxes made with gs:list-box, this makes
+ it possible to process single clicks.
+
+1.10
+ the gs:list-box event now responds on any click-count, previously only on 2 for
+ double click. Addtionally the click-count is transmitted in the event as the last
+ parameter
+
+1.11
+ replace all can now be redone, double undo not required any more for replace
+
+ new gs:undo-enable undo is currently disabled in newlisp-edit for find/replace
+ because of instabilities
+
+1.12
+ newlisp-edit "Undo Previous" button in find dialog, this is used to undo replacements.
+ Replacements cannot be undone with normal undo when the find dialog is closed again,
+ but can only be undone from inside the find dialog
+
+1.12-13-14
+ in guiserver.lsp now checking JAVA_HOME when not Win32 or OS X
+
+1.15
+ fixed highlighing for 'pop-assoc'
diff --git a/guiserver/COPYING b/guiserver/COPYING
new file mode 100644
index 0000000..26f43a3
--- /dev/null
+++ b/guiserver/COPYING
@@ -0,0 +1,1046 @@
+Copyright information for guiserver.jar
+---------------------------------------
+
+Source code for this package copyright (c) Lutz Mueller is
+licensed under the "GNU GENERAL PUBLIC LICENSE Version 3, June 2007".
+The text of this license is contained in this file.
+
+Documentation found in this package is licensed under the
+"GNU Free Documentation License Version 1.2, November 2002".
+The text of this license is contained in this file.
+
+All icons and images are copyright (c) Michael Michaels
+under the "GNU GENERAL PUBLIC LICENSE Version 3, June 2007".
+
+Following:
+
+- GNU General Public License
+- GNU Free Documentation License
+
+---------------------------------------------------------------------
+
+
+ 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
+
+
+-----------------------------------------------------------------------------
+
+ GNU Free Documentation License
+ Version 1.2, November 2002
+
+
+ Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+0. PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+1. APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The "Document", below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as "you". You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section "Entitled XYZ" means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as "Acknowledgements",
+"Dedications", "Endorsements", or "History".) To "Preserve the Title"
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+2. VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+3. COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+4. MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.
+B. List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+D. Preserve all the copyright notices of the Document.
+E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+F. Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.
+G. Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.
+H. Include an unaltered copy of this License.
+I. Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.
+J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.
+K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+N. Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.
+O. Preserve any Warranty Disclaimers.
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+5. COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications". You must delete all sections
+Entitled "Endorsements".
+
+
+6. COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+8. TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+9. TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+10. FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+ Copyright (c) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+---------------------------------------------------------------------
diff --git a/guiserver/Makefile b/guiserver/Makefile
new file mode 100644
index 0000000..cd9b96a
--- /dev/null
+++ b/guiserver/Makefile
@@ -0,0 +1,18 @@
+# this make file is only used during development
+# the main makefile in the newlisp-x.x.x/ will
+# normally peform the installation below
+
+all:
+ javac java/*.java
+ mv java/*.class .
+ jar cmf Manifest guiserver.jar *.class images/*.png
+ rm *.class
+
+install:
+ -install -d /usr/share/newlisp/guiserver
+ -install -d /usr/share/doc/newlisp/guiserver
+ -install -m 644 guiserver.jar /usr/share/newlisp/
+ -install -m 644 guiserver.lsp /usr/share/newlisp/
+ -install -m 644 index.html /usr/share/doc/newlisp/guiserver/
+ -install -m 644 guiserver.lsp.html /usr/share/doc/newlisp/guiserver/
+ -install -m 755 newlisp-edit.lsp /usr/bin/newlisp-edit
diff --git a/guiserver/Manifest b/guiserver/Manifest
new file mode 100644
index 0000000..0ec706d
--- /dev/null
+++ b/guiserver/Manifest
@@ -0,0 +1 @@
+Main-Class: guiserver
diff --git a/guiserver/allfonts-demo.lsp b/guiserver/allfonts-demo.lsp
new file mode 100644
index 0000000..8e8305a
--- /dev/null
+++ b/guiserver/allfonts-demo.lsp
@@ -0,0 +1,43 @@
+#!/usr/bin/newlisp
+;;
+;; allfonts-demo.lsp - show all fonts on the system
+;; this program also demonstrates that strings can be used instead
+;; of symbols for widget names (label in this case)
+
+;;;; initialization
+(set-locale "C")
+
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+;(gs:set-trace true)
+;;;; describe the GUI
+(gs:frame 'AllFontsDemo 100 100 500 400)
+(gs:set-background 'AllFontsDemo 1 1 1)
+(gs:get-fonts)
+(gs:panel 'FontPanel)
+(gs:set-grid-layout 'FontPanel (length gs:fonts) 1 0 0)
+(gs:set-text 'AllFontsDemo (string "All " (length gs:fonts) " fonts on this system"))
+(dolist (font gs:fonts)
+ (set 'font-label (string "label-" $idx))
+ (gs:label font-label font)
+ (gs:set-size font-label 100 30)
+ (gs:set-font font-label font 24 "plain")
+ (gs:mouse-event font-label 'mouse-action)
+ (gs:add-to 'FontPanel font-label))
+
+(gs:scroll-pane 'Scroll 'FontPanel)
+(gs:add-to 'AllFontsDemo 'Scroll)
+(gs:set-visible 'AllFontsDemo true)
+
+
+(define (mouse-action id type x y button cnt mods)
+ (gs:set-text 'AllFontsDemo
+ (format "%s %s %d:%d button:%d count:%d mod-key:%d" id type x y button cnt mods))
+)
+;;;; listen for incoming action requests and dispatch
+
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/animation-demo.lsp b/guiserver/animation-demo.lsp
new file mode 100644
index 0000000..47065aa
--- /dev/null
+++ b/guiserver/animation-demo.lsp
@@ -0,0 +1,57 @@
+#!/usr/bin/newlisp
+;;
+;; animation-demo.lsp - demonstrate gs:move-tag for making animations
+;; and the mouse-wheel moving a text object
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+
+;;;; describe the GUI
+(gs:frame 'AnimationDemo 100 100 400 300 "Animation ~ 30 frames/sec, 5 pixel/step")
+(gs:set-resizable 'AnimationDemo nil)
+(gs:canvas 'MyCanvas)
+(gs:set-background 'MyCanvas gs:white)
+(gs:mouse-wheel 'MyCanvas 'mouse-wheel-action)
+(gs:add-to 'AnimationDemo 'MyCanvas)
+
+(set 'Ty 140)
+(gs:set-font 'MyCanvas "Lucida Sans Oblique" 16 "plain")
+(gs:draw-text 'T "turn the mouse wheel to move this text" 20 Ty)
+(gs:fill-circle 'C 50 40 25 gs:red)
+(gs:fill-circle 'C 30 20 15 gs:black)
+(gs:fill-circle 'C 70 20 15 gs:black)
+(gs:fill-circle 'C 50 48 6 gs:yellow)
+
+(gs:set-visible 'AnimationDemo true)
+
+
+(define (mouse-wheel-action x y wheel)
+ (if (= ostype "OSX")
+ (gs:move-tag 'T 0 (* wheel wheel (sgn wheel)))
+ (gs:move-tag 'T 0 (* 5 wheel)))
+)
+
+(set 'delay 33000) ;;
+
+(while (gs:check-event delay)
+ (dotimes (x 60)
+ (gs:check-event delay)
+ (gs:move-tag 'C 5 0))
+ (dotimes (x 40)
+ (gs:check-event delay)
+ (gs:move-tag 'C 0 5))
+ (dotimes (x 60)
+ (gs:check-event delay)
+ (gs:move-tag 'C -5 0))
+ (dotimes (x 40)
+ (gs:check-event delay)
+ (gs:move-tag 'C 0 -5))
+)
+
+(exit)
+
+;; eof
+
diff --git a/guiserver/border-layout-demo.lsp b/guiserver/border-layout-demo.lsp
new file mode 100644
index 0000000..89b42e6
--- /dev/null
+++ b/guiserver/border-layout-demo.lsp
@@ -0,0 +1,32 @@
+#!/usr/bin/newlisp
+;;
+;; border-demo.lsp - demonstrate the border layout
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+
+
+;;;; describe the GUI
+(gs:frame 'BorderDemo 100 100 400 300 "Border layout demo")
+(gs:set-border-layout 'BorderDemo 0 0)
+(gs:panel 'NorthPanel 50 50)
+(gs:set-color 'NorthPanel 0.5 0 0)
+(gs:panel 'WestPanel 50 50)
+(gs:set-color 'WestPanel 0.5 0.5 0)
+(gs:panel 'CenterPanel 50 50)
+(gs:set-color 'CenterPanel 0.0 0.5 0)
+(gs:panel 'EastPanel 50 50)
+(gs:set-color 'EastPanel 0.0 0.5 0.5)
+(gs:panel 'SouthPanel 50 50)
+(gs:set-color 'SouthPanel 0.0 0 0.5)
+(gs:add-to 'BorderDemo 'NorthPanel "north" 'WestPanel "west" 'CenterPanel "center"
+ 'EastPanel "east" 'SouthPanel "south")
+(gs:set-visible 'BorderDemo true)
+
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/button-demo.lsp b/guiserver/button-demo.lsp
new file mode 100644
index 0000000..7244dad
--- /dev/null
+++ b/guiserver/button-demo.lsp
@@ -0,0 +1,36 @@
+#!/usr/bin/newlisp
+;;
+; button-demo.lsp - demonstrate the button control
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+(gs:set-trace true)
+
+;;;; describe the GUI
+(gs:frame 'ButtonDemo 100 100 400 300 "Click on button or color panel")
+(gs:set-resizable 'ButtonDemo nil)
+(gs:panel 'ColorPanel 360 200)
+(gs:set-background 'ColorPanel '(0 1 0) 0.2)
+(gs:button 'aButton 'button-action "color")
+(gs:set-flow-layout 'ButtonDemo "center" 2 15)
+(gs:add-to 'ButtonDemo 'ColorPanel 'aButton)
+(gs:set-visible 'ButtonDemo true)
+
+(gs:mouse-event 'ColorPanel 'mouse-action)
+
+;;;; define actions
+(define (button-action id)
+ (gs:set-color 'ColorPanel (random) (random) (random)))
+
+(define (mouse-action id type x y button cnt mods)
+ (gs:set-text 'ButtonDemo (format "%8s %3d:%3d %d %d %2d" type x y button cnt mods))
+)
+
+;;;; listen for incoming action requests and dispatch
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/clipboard-demo.lsp b/guiserver/clipboard-demo.lsp
new file mode 100644
index 0000000..6e3c9f8
--- /dev/null
+++ b/guiserver/clipboard-demo.lsp
@@ -0,0 +1,27 @@
+#!/usr/bin/newlisp
+;;
+;; clipboard-demo.lsp - demonstrate the gs:paste-text function
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+
+(gs:frame 'Frame 200 200 400 300)
+(gs:set-border-layout 'Frame)
+(gs:text-area 'TheText 'text-handler)
+(gs:button 'TheButton 'button-handler "get clipboard")
+(gs:add-to 'Frame 'TheText "center" 'TheButton "south")
+(gs:set-visible 'Frame true)
+
+(define (button-handler)
+ (gs:paste-text 'TheText))
+
+(define (text-handler))
+
+;;;; listen for incoming action requests and dispatch
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/cursor-demo.lsp b/guiserver/cursor-demo.lsp
new file mode 100644
index 0000000..44a3fcb
--- /dev/null
+++ b/guiserver/cursor-demo.lsp
@@ -0,0 +1,47 @@
+#!/usr/bin/newlisp
+;;
+;; cursor-demo - demonstrate cursor shapes with gs:set-cursor
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+;(gs:set-trace true)
+
+(set 'cursor-shapes '(
+ "default"
+ "crosshair"
+ "text"
+ "wait"
+ "sw-resize"
+ "se-resize"
+ "nw-resize"
+ "ne-resize"
+ "n-resize"
+ "s-resize"
+ "w-resize"
+ "e-resize"
+ "hand"
+ "move"
+))
+
+;; describe the GUI
+(gs:frame 'CursorDemo 100 100 500 200 "Cursor shapes - move the cursor over the panels")
+(gs:set-grid-layout 'CursorDemo 2 7)
+
+(dolist (c cursor-shapes)
+ (set 'id (sym c))
+ (gs:panel id)
+ (gs:set-background id (list (random) (random) (random)))
+ (gs:set-cursor id c)
+ (gs:add-to 'CursorDemo id))
+
+;(gs:set-resizable 'CursorDemo nil)
+
+(gs:set-visible 'CursorDemo true)
+
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/drag-demo.lsp b/guiserver/drag-demo.lsp
new file mode 100644
index 0000000..d366b1e
--- /dev/null
+++ b/guiserver/drag-demo.lsp
@@ -0,0 +1,83 @@
+#!/usr/bin/newlisp
+;;
+;; drag-demo.lsp - demonstrate dragging of objects with the mouse
+;;
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+;(gs:set-trace true)
+
+;;;; describe the GUI
+(gs:frame 'DragDemo 100 100 600 500 "Drag demo")
+;(gs:set-resizable 'DragDemo nil)
+(gs:canvas 'MyCanvas)
+(gs:set-background 'MyCanvas gs:white)
+(gs:add-to 'DragDemo 'MyCanvas)
+(gs:mouse-clicked 'MyCanvas 'mouse-clicked-action true)
+(gs:mouse-pressed 'MyCanvas 'mouse-pressed-action true)
+(gs:mouse-released 'MyCanvas 'mouse-released-action true)
+(gs:mouse-dragged 'MyCanvas 'mouse-dragged-action)
+
+;(gs:set-scale 0.5 0.5) ; only for testing, dragging would fail
+
+(gs:set-font 'MyCanvas "Lucida Sans Oblique" 18 "plain")
+(gs:draw-text 'T "Drag objects with the mouse, click right for popup menu" 20 250 gs:darkGray)
+(gs:fill-circle 'C 100 100 50 gs:red)
+(gs:fill-circle 'C 60 60 30 gs:black)
+(gs:fill-circle 'C 140 60 30 gs:black)
+(gs:fill-circle 'C 100 110 8 gs:yellow)
+
+
+(gs:draw-polygon 'P '(300 200 400 50 500 200) gs:blue)
+
+(gs:draw-image 'I "/local/newLISP128.png" 300 300 128 128)
+
+(gs:menu-popup 'EditMenuPopup "Edit")
+(gs:menu-item 'EditCut 'gs:no-action "Cut")
+(gs:menu-item 'EditCopy 'gs:no-action "Copy")
+(gs:menu-item 'EditPaste 'gs:no-action "Paste")
+(gs:disable 'EditCut 'EditCopy 'EditPaste)
+(gs:add-to 'EditMenuPopup 'EditCut 'EditCopy 'EditPaste)
+
+; comment out to test reorder
+;(gs:reorder-tags '(I P C T))
+
+(gs:set-visible 'DragDemo true)
+
+;(gs:update)
+
+;; actions
+(set 'mouse-down-tags '())
+
+(define (mouse-clicked-action x y button cnt modifiers tags)
+ (gs:set-text 'DragDemo (string x ":" y " " button " " cnt " " tags))
+ (if (or (= 3 button) (= modifiers 18)) ; check for ctrl-button1-click on Mac
+ (gs:show-popup 'EditMenuPopup 'MyCanvas x y))
+)
+
+(define (mouse-pressed-action x y button modifiers tags)
+ (gs:set-text 'DragDemo (string x ":" y " " button " " modifiers " " tags))
+ (set 'mouse-down-tags tags)
+ (set 'mouse-old-x x)
+ (set 'mouse-old-y y)
+)
+
+(define (mouse-released-action x y button modifiers tags)
+ (gs:set-text 'DragDemo (string x ":" y " " button " " modifiers " " tags))
+ (set 'mouse-down-tags '())
+)
+
+(define (mouse-dragged-action x y)
+ (dolist (t mouse-down-tags)
+ (gs:move-tag t (- x mouse-old-x) (- y mouse-old-y)))
+ (set 'mouse-old-x x)
+ (set 'mouse-old-y y)
+)
+
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/editor.txt b/guiserver/editor.txt
new file mode 100644
index 0000000..89b42e6
--- /dev/null
+++ b/guiserver/editor.txt
@@ -0,0 +1,32 @@
+#!/usr/bin/newlisp
+;;
+;; border-demo.lsp - demonstrate the border layout
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+
+
+;;;; describe the GUI
+(gs:frame 'BorderDemo 100 100 400 300 "Border layout demo")
+(gs:set-border-layout 'BorderDemo 0 0)
+(gs:panel 'NorthPanel 50 50)
+(gs:set-color 'NorthPanel 0.5 0 0)
+(gs:panel 'WestPanel 50 50)
+(gs:set-color 'WestPanel 0.5 0.5 0)
+(gs:panel 'CenterPanel 50 50)
+(gs:set-color 'CenterPanel 0.0 0.5 0)
+(gs:panel 'EastPanel 50 50)
+(gs:set-color 'EastPanel 0.0 0.5 0.5)
+(gs:panel 'SouthPanel 50 50)
+(gs:set-color 'SouthPanel 0.0 0 0.5)
+(gs:add-to 'BorderDemo 'NorthPanel "north" 'WestPanel "west" 'CenterPanel "center"
+ 'EastPanel "east" 'SouthPanel "south")
+(gs:set-visible 'BorderDemo true)
+
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/font-demo.lsp b/guiserver/font-demo.lsp
new file mode 100644
index 0000000..042958c
--- /dev/null
+++ b/guiserver/font-demo.lsp
@@ -0,0 +1,61 @@
+#!/usr/bin/newlisp
+;;
+;; font-demo.lsp - show all built-in Java fonts (available on all platforms)
+
+;;;; initialization
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+
+;;;; describe the GUI
+(gs:frame 'TestFrame 100 100 480 320 "newLISP-GS built-in Font Families")
+(gs:set-background 'TestFrame 1 1 1)
+(gs:set-grid-layout 'TestFrame 12 1)
+(gs:label 'L1 "Lucida Sans Regular")
+(gs:set-font 'L1 "Lucida Sans" 20 "plain")
+(gs:label 'L2 "Lucida Sans Bold")
+(gs:set-font 'L2 "Lucida Sans" 20 "bold")
+(gs:label 'L3 "Lucida Sans Oblique")
+(gs:set-font 'L3 "Lucida Sans" 20 "italic")
+
+(gs:label 'L4 "Lucida Bright Regular")
+(gs:set-font 'L4 "Lucida Bright" 20 "plain")
+(gs:label 'L5 "Lucida Bright Bold")
+(gs:set-font 'L5 "Lucida Bright" 20 "bold")
+(gs:label 'L6 "Lucida Bright Oblique")
+(gs:set-font 'L6 "Lucida Bright" 20 "italic")
+
+(gs:label 'L7 "Lucida Sans Typewriter Regular")
+(gs:set-font 'L7 "Lucida Sans Typewriter" 20 "plain")
+(gs:label 'L8 "Lucida Sans Typewriter Bold")
+(gs:set-font 'L8 "Lucida Sans Typewriter" 20 "bold")
+(gs:label 'L9 "Lucida Sans Typewriter Oblique")
+(gs:set-font 'L9 "Lucida Sans Typewriter" 20 "italic")
+
+(gs:label 'L10 "Monospaced Regular")
+(gs:set-font 'L10 "Monospaced" 20 "plain")
+(gs:label 'L11 "Monospaced Bold")
+(gs:set-font 'L11 "Monospaced" 20 "bold")
+(gs:label 'L12 "Monospaced Oblique")
+(gs:set-font 'L12 "Monospaced" 20 "italic")
+
+(dolist (i '(L1 L2 L3 L4 L5 L6 L7 L8 L9 L10 L11 L12))
+ (gs:set-foreground i 0 0 0.4))
+
+(gs:add-to 'TestFrame 'L1 'L2 'L3 'L4 'L5 'L6 'L7 'L8 'L9 'L10 'L11 'L12)
+(gs:set-visible 'TestFrame true)
+
+;; actions
+
+(define (toggle-action id flag)
+ (if flag
+ (gs:set-icon 'aImage "/local/newLISP32.png")
+ (gs:set-icon 'aImage "/local/newLISP128.png"))
+)
+
+;;;; listen for incoming action requests and dispatch
+(gs:listen)
+
+;; eof
+
diff --git a/guiserver/frameless-demo.lsp b/guiserver/frameless-demo.lsp
new file mode 100644
index 0000000..c28a64a
--- /dev/null
+++ b/guiserver/frameless-demo.lsp
@@ -0,0 +1,28 @@
+#!/usr/bin/newlisp
+
+;; frameless-demo.lsp - frameless and transparent (on MacOS X)
+
+(set-locale "C")
+(load (append (env "NEWLISPDIR") "/guiserver.lsp"))
+
+(gs:init)
+
+(gs:window 'Window 100 100 400 100)
+(gs:set-background 'Window 0 0 0.5 0.2)
+(gs:set-border-layout 'Window)
+(gs:label 'Time " ")
+(gs:set-font 'Time "Mono Spaced" 40 "bold")
+(gs:set-foreground 'Time 1 1 0 )
+(gs:add-to 'Window 'Time "center")
+(gs:button 'Button 'button-handler "close")
+(gs:add-to 'Window 'Button "south")
+(gs:set-visible 'Window true)
+
+(define (button-handler) (exit))
+
+(while (gs:check-event 10000)
+ (sleep 200)
+ (gs:set-text 'Time (date (date-value) 0 "%b %d %H:%M:%S"))
+)
+
+;; eof
diff --git a/guiserver/guiserver.jar b/guiserver/guiserver.jar
new file mode 100644
index 0000000000000000000000000000000000000000..f95563e8d12b1a8e3484938ec420aeff1cab80f8
GIT binary patch
literal 281685
zcwU5iW0WRc)@9nZ%_nW!wr$(CZQIVQv~9c6R#iH)(wO({?wK|H&6@6rbyncUU2%V$
zeeT{7`zp$Sf}sIH{k5Yii*N${UmG+K7?7Npst}!&yg0+x6c7+7kfIDE)Za}Y|9V96
z|JxbuulPTm<%Hy=#Klxp>E*;9D~(2h$1o~Pu$t?r#)Da=nVxX;KiFmqo2XbCIhxU%*c!RG_^DdCtcWA|-8XHbn;gYB;-WZTBHLa9
z0mC88Ih#f?A@ngGM*
z^@h^>)dOrzaxqU?A-^-7Zn>sFIKb>TJ5Kf)?O}b5N{o-n%DYqf68MZDqulMf5RM5eiov;5*>Fvw%lzjy2bpHBhbie7hk3jctsf3Wg?Pvl9CCgZVXfnK{XLM)wT50zwME_%)ciVPJrRob~^A_Lmc%Z
zyock+&o|oHg}r;s@uRrtW<}TxFd&}hYkoWxoLi38II*Bq*@qWRgO6Dk1-Rezyig)M
zY(7rK3uGmNQ&;fV=5&yulBYnHqKCA)nCp4XUwAixUns`fG_L%e#1ri`U
z@g8H#9ao9wv;V-w=-ngDKUnWSKZO0z_C=`C{8d;JXHRNSSP{3YI$K(uSG}P+TUIS{
zHQ;d0kghM-y7;=e
z(Z_nEb`UROd60)XjaX&QX2KW;v`2T|D4c~bY5NHSGtr1EC?(+F_SbGD$^%zCp1|VZ
zqJaCb8C6iu2#6VG^f&0=0BtLTAvOaA0z!xQPXI;!D};?)%-C5)98Are|A|pMRUJiK
zHLS06Q-%%O2^4PtQsadfOqC$@#TtlJCmIZT)zqlfZ_A8EVQWc7TYxHDrDqlQQK16<
ziqgWtWK)}ok@kqkp0Cr`MYlrUolwE(H(60BHN#o|_u1a}``p*l-i{nl+<6kRD)D|~
zG@oa-jhk+b$Kqn)KGicTfO9NQZX4?Eh?4^zn-Yz;q!^15o%JCa10Al8d5Bpa+EG3;
zB@QH--p%}viS7+jq1K(G@d{33%Hm6A;IHgHnp3rAV)Lb^lmHnzfG0BS+d!!PYfu`)Sa>@$jYDf15_o83uLiMkk<%uW23(ivA3l`>kku-g#-(W{Q*x#a3B!p(XB+(Iq7bGl>VXYM=3vDnFeRIKAqC
z0$4rSZ$`XQ;9Vaida#>9OZ<2?PKRU}LG(Ojifu_TFx`4f!qyXgF05_c2+hpxTqy+8
zl&~Ymr6ZuP$LXU(Gir>d2NePVwN_$w9{ligMly=Gj3xrp!(b}bG(#G@32Y6id>i!C
z+RJNqCaqjHRSFp^uWai3%bo-C=xe!{<(V=WQ)@DX3V4Oi6e-wbM_3dU5fQI+9vh}A
zXKWk~%ObT%Z_miX1PET9pw+tk`yRc#kc2swmP7jUa|)ojr6nKBjb5+`u9YLL=*I&y
z-U#GJ(x3;)Bd?wW%v*5%k#?*BJ-9mj(pSbnc@Ghqu&CVE0p6
z+>^JV7ACyw$}XL$D~_4cOG8Pb0Dw84_3V>T_$TRJGFMD1b*JRQb7aaU7dl+ounEfP
zlTP)6BdlZ;GtZ_!tjke2wsWaRXXIpwcP&Y@^vk8J^s>$Ky+j(OZ)4FJ5SWwppO0-F
zg6bF$>g~OLxu@e$o(GcEIl+`QUZj;NM$|mU?vgQ9IDxQ09pNY)(-jZUl6dBjSdk3k
z^$qd%jq|(!-yB->L>M#%?nRM2-vNIOMZ91VA{(!RqZ7iSzlc^2SAcPUhB_;1oD^b&
z*id~|0iDf9=0p&d?^XbF8K^(D!QZiyNyO~#{#s|KH$+74H3kk2n7HZr@cR904Roh;
zqE(Mng4)@+U2?975PNeCCtRAbzi2yreoaaB^LPK|H}Kzead|C)b^{Cu
z=nV3|u_<9US62sn4J%U%GgmUEf0afR9R*Y&w6Aiy9e2H=RFd65ZKZZGDmCP^9J`>A
zQUJ8*;ZYm@=Ac>IM&9U1K-plj5)w}x44aU9`$jsv5V_ip*+Rf3ALP|Ehs{+ri`
zo>@ja4uo9Nic4QrGyjn?fJRBGT%CmBX*}i|T^~8?z`0kwm!4E%&W{uCpv1g&UANx0
zpm7XmPh;X3raC%p&uDVcd0O6a*zl;xMK{xmo)X{cny?`|mx7=TjP#}nA93Ff;yKbD!pM%_l1JmciH73}%b^;(
z<#?@UuwtG#73)XI>C6@eU;uqb_;T?uCLuBEle{-<=ciFyY25D6^ucqh>9VJBhLW;(
z_^WQC1+jd6x9~AunDoi>oh6fmMS%#XdwtS6!M3N&vW*7AGSm@%5eD;M(`0$Wykoa*
ztYZ)4gnJI@al`S*?~y4?vObgZPv~T=l7tl^L2dTWb=Fp|Fi}EvLXE1@gaejxS`@Mx
z#*4CA~*_tn2)Zue*mW51I25e9
z#+Eqkw$nL=oQ9_ABd|v5d^M(XKJjLlm{ap*cD>2+%zYC`a%r&1MQkP;_u_7BlzHGu
zG)ZCw3>tYoxoxRS{Az!Ce)O86M=#+j#p3yO%q&zrG01tuMb2&jjWR`1$D`Fd>W;FG
zv&~pay38DMOF+2bain%c>EPJAY!CK?gU5Gk9%~Nq!E438dk!odoYAlGK18S^@QX}R)?B;y$~g;0a$77Q!<
zEJ-xh-&qcDC|&B$B6~0kQ&uX{e7#zg+sfo4#ns
zmD^EDJ;t|69d-I1ee;ImJOvd|QYC@PZX?C)e*K(V7G=|_-qxEQ%A?^~qICXr-?p&K
zLaFEV5a+|-j>0s}cNbzDRx+VEY8!vP+Lrp&LDLIf9a!YU!{3!cFH9>v-h5xos`VrK
zsd{g=GD&^+sh`PeD@82L(nXB3UUrKosT><8u7z+{{J0(ORhB!Rc1A@4+dFn<4f5P#
zN!QikRNYjcFPH5bT&aRvq+m1FG2={>{FSG!G09uIO8Homvm}tda}{OJnnalt)xXbQ
z{;F6p^O1qcq%;4~U{SCV?@{F5U;#y8TOCK-`ua=gcVS=(*>WRCCeYVTDNQ^SJl|~*xIKYTT
zi+*hb>Qrx3o9*`(e9QX69d@2+G`aP;_NJ&u`uzqf80Rk1FS;d9g$F<|=m<7(
zK3N@i-pZ8+O#eTSSlXb*xt3>YKC)
z>*5-!6?Fxxi&xtJ*tNE;Y1Fi}@>ko{F>t%w>|EMwCO#qdfA)2{oX*T-J>>j#;C~y{
zdj`s+o0ANQci}r9Yh(2#6u4cu<)t`d=?t7i^g0w)?~IJVr0EFl&nQ1&*1ZXnv$dG&N6L(x3B&Y
zJZT4GuOI?_ZTKS(-Q6?to!o`TYn2CGl$UCp9plEhZijdKXi)Fx^maq$c3!-XBSZJ@
z*`QxX!KDB0aRWN<{ve30%aPC*|MA%HhhHcgf!RG)%DC1OE@J*b%H=UNNB-$(fz)`j
z=Um*`>$}dH*I*px&I`Ux-^lTE?H42k1IsIEibiJ7)G-@H1B+M4WI^V~MhM3pM#_8E
zrN(U=q|F^BMS$8Z2jbcRKH^ur2YS!h*t@;&{-D5ZQE&pVKkm!Nvc!FtY+AMWEmj9o|q
zS=GT8{VbVzZM#tkd!d?T&TMp