- armedbear-devel - mailman3.common-lisp.net

[armedbear-devel] DocString (lazy version)
by Matt Seddon 16 Jul '10

16 Jul '10

To address Allesio's concern, I've now moved the processing of DocStrings into LispObject.getDocumentation. When no FUNCTION documentation has been set for a symbol, it checks to see if there is an annotation it can pull out of the symbol's function in the function slot, and attach and return it if found. Diff from trunk follows: # doc-string.diff Index: org/armedbear/lisp/DocString.java --- org/armedbear/lisp/DocString.java Locally New +++ org/armedbear/lisp/DocString.java Locally New @@ -0,0 +1,44 @@ +/* + * DocString.java + * + * Copyright (C) 2010 Matt Seddon + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * + * As a special exception, the copyright holders of this library give you + * permission to link this library with independent modules to produce an + * executable, regardless of the license terms of these independent + * modules, and to copy and distribute the resulting executable under + * terms of your choice, provided that you also meet, for each linked + * independent module, the terms and conditions of the license of that + * module. An independent module is a module which is not derived from + * or based on this library. If you modify this library, you may extend + * this exception to your version of the library, but you are not + * obligated to do so. If you do not wish to do so, delete this + * exception statement from your version. + */ +package org.armedbear.lisp; + +import java.lang.annotation.*; + +/** + * An annotation type to expose documentation to ABCL. + */ +(a)Retention(RetentionPolicy.RUNTIME) +public @interface DocString { + public String name() default ""; + public String doc() default ""; + public String args() default ""; +} Index: org/armedbear/lisp/Function.java --- org/armedbear/lisp/Function.java Base (BASE) +++ org/armedbear/lisp/Function.java Locally Modified (Based On LOCAL) @@ -46,6 +46,11 @@ */ private final LispObject loadedFrom; + /** + * Examine this object's class to determine if there is a DocString annotation, and if so, + * add the documentation. + */ + protected Function() { LispObject loadTruename = Symbol.LOAD_TRUENAME.symbolValueNoThrow(); loadedFrom = loadTruename != null ? loadTruename : NIL; @@ -53,7 +58,14 @@ public Function(String name) { + this(name, (String)null); + } + + public Function(String name, String arglist) + { this(); + if(arglist != null) + setLambdaList(new SimpleString(arglist)); if (name != null) { Symbol symbol = Symbol.addFunction(name.toUpperCase(), this); if (cold) @@ -62,14 +74,14 @@ } } + public Function(Symbol symbol) + { + this(symbol, null, null); + } + public Function(Symbol symbol, String arglist) { - this(); - symbol.setSymbolFunction(this); - if (cold) - symbol.setBuiltInFunction(true); - setLambdaName(symbol); - setLambdaList(new SimpleString(arglist)); + this(symbol, arglist, null); } public Function(Symbol symbol, String arglist, String docstring) @@ -79,19 +91,13 @@ if (cold) symbol.setBuiltInFunction(true); setLambdaName(symbol); + if(arglist != null) setLambdaList(new SimpleString(arglist)); - if (docstring != null) { + if (docstring != null) symbol.setDocumentation(Symbol.FUNCTION, new SimpleString(docstring)); } - } - public Function(String name, String arglist) - { - this(name); - setLambdaList(new SimpleString(arglist)); - } - public Function(String name, Package pkg) { this(name, pkg, false); Index: org/armedbear/lisp/Java.java --- org/armedbear/lisp/Java.java Base (BASE) +++ org/armedbear/lisp/Java.java Locally Modified (Based On LOCAL) @@ -60,11 +60,12 @@ } private static final Primitive ENSURE_JAVA_OBJECT = new pf_ensure_java_object(); + @DocString(args="obj", doc="Ensures OBJ is wrapped in a JAVA-OBJECT, wrapping it if necessary.") private static final class pf_ensure_java_object extends Primitive { pf_ensure_java_object() { - super("ensure-java-object", PACKAGE_JAVA, true, "obj"); + super("ensure-java-object", PACKAGE_JAVA, true); } @Override @@ -131,13 +132,13 @@ // ### jclass name-or-class-ref &optional class-loader => class-ref private static final Primitive JCLASS = new pf_jclass(); + @DocString(args="name-or-class-ref &optional class-loader", doc="Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader.") private static final class pf_jclass extends Primitive { pf_jclass() { - super(Symbol.JCLASS, "name-or-class-ref &optional class-loader", - "Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader."); + super(Symbol.JCLASS); } @Override @@ -294,12 +295,12 @@ // ### jconstructor class-ref &rest parameter-class-refs private static final Primitive JCONSTRUCTOR = new pf_jconstructor(); + @DocString(args="class-ref &rest parameter-class-refs", doc="Returns a reference to the Java constructor of CLASS-REF with the given PARAMETER-CLASS-REFS.") private static final class pf_jconstructor extends Primitive { pf_jconstructor() { - super("jconstructor", PACKAGE_JAVA, true, - "class-ref &rest parameter-class-refs"); + super("jconstructor", PACKAGE_JAVA, true); } @Override @@ -344,12 +345,13 @@ // ### jmethod class-ref name &rest parameter-class-refs private static final Primitive JMETHOD = new pf_jmethod(); + + @DocString(args="class-ref name &rest parameter-class-refs", doc="Returns a reference to the Java method NAME of CLASS-REF with the given PARAMETER-CLASS-REFS.") private static final class pf_jmethod extends Primitive { pf_jmethod() { - super("jmethod", PACKAGE_JAVA, true, - "class-ref name &rest parameter-class-refs"); + super("jmethod", PACKAGE_JAVA, true); } @Override Index: org/armedbear/lisp/LispObject.java --- org/armedbear/lisp/LispObject.java Base (BASE) +++ org/armedbear/lisp/LispObject.java Locally Modified (Based On LOCAL) @@ -657,6 +657,23 @@ if (entry instanceof Cons) return ((Cons)entry).cdr; } + if(docType == Symbol.FUNCTION && this instanceof Symbol) { + Object fn = ((Symbol)this).getSymbolFunction(); + if(fn instanceof Function) { + DocString ds = fn.getClass().getAnnotation(DocString.class); + if(ds != null) { + String arglist = ds.args(); + String docstring = ds.doc(); + if(arglist.length() != 0) + ((Function)fn).setLambdaList(new SimpleString(arglist)); + if(docstring.length() != 0) { + SimpleString doc = new SimpleString(docstring); + ((Symbol)this).setDocumentation(Symbol.FUNCTION, doc); + return doc; + } + } + } + } return NIL; } Index: org/armedbear/lisp/Primitive.java --- org/armedbear/lisp/Primitive.java Base (BASE) +++ org/armedbear/lisp/Primitive.java Locally Modified (Based On LOCAL) @@ -45,6 +45,11 @@ super(name); } + public Primitive(Symbol symbol) + { + super(symbol); + } + public Primitive(Symbol symbol, String arglist) { super(symbol, arglist);

2 1

[armedbear-devel] DocString annotation patch.
by Matt Seddon 15 Jul '10

15 Jul '10

Hi folks, Here's the first go at the DocString annotation. Changes: Added org/armedbear/lisp/DocString.java, defining the @DocString annotation. Modified Function.java. Now it will check to see if there is an annotation, and set its data from there (overriding the arglist and docstring constructor arguments if provided). Also removed some (but not all) existing code duplication in the constructors. Added a constructor to Primitive, Primitive(Symbol), since it wasn't there, and becomes relevant when moving documentation out of a constructor and into a @DocString annotation. Added/replaced a bit of documentation in Java.java using the new annotation syntax, to give a flavour of what it does. (More actual documentation patches in progress). Conformance with ansi.interpreted and ansi.compiled has not been affected, but confirmation would be prudent since this is new to me. Regards, Matt # doc-string.diff Index: org/armedbear/lisp/DocString.java --- org/armedbear/lisp/DocString.java Locally New +++ org/armedbear/lisp/DocString.java Locally New @@ -0,0 +1,44 @@ +/* + * DocString.java + * + * Copyright (C) 2010 Matt Seddon + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * + * As a special exception, the copyright holders of this library give you + * permission to link this library with independent modules to produce an + * executable, regardless of the license terms of these independent + * modules, and to copy and distribute the resulting executable under + * terms of your choice, provided that you also meet, for each linked + * independent module, the terms and conditions of the license of that + * module. An independent module is a module which is not derived from + * or based on this library. If you modify this library, you may extend + * this exception to your version of the library, but you are not + * obligated to do so. If you do not wish to do so, delete this + * exception statement from your version. + */ +package org.armedbear.lisp; + +import java.lang.annotation.*; + +/** + * An annotation type to expose documentation to ABCL. + */ +(a)Retention(RetentionPolicy.RUNTIME) +public @interface DocString { + public String name() default ""; + public String doc() default ""; + public String args() default ""; +} Index: org/armedbear/lisp/Function.java --- org/armedbear/lisp/Function.java Base (BASE) +++ org/armedbear/lisp/Function.java Locally Modified (Based On LOCAL) @@ -46,6 +46,23 @@ */ private final LispObject loadedFrom; + /** + * Examine this object's class to determine if there is a DocString annotation, and if so, + * add the documentation. + */ + private void installDocString() { + DocString ds = getClass().getAnnotation(DocString.class); + if(ds != null) { + LispObject name = getLambdaName(); + String arglist = ds.args(); + String docstring = ds.doc(); + if(arglist.length() != 0) + setLambdaList(new SimpleString(arglist)); + if(name instanceof Symbol && docstring.length() != 0) + ((Symbol)name).setDocumentation(Symbol.FUNCTION, new SimpleString(docstring)); + } + } + protected Function() { LispObject loadTruename = Symbol.LOAD_TRUENAME.symbolValueNoThrow(); loadedFrom = loadTruename != null ? loadTruename : NIL; @@ -53,23 +70,31 @@ public Function(String name) { + this(name, (String)null); + } + + public Function(String name, String arglist) + { this(); + if(arglist != null) + setLambdaList(new SimpleString(arglist)); if (name != null) { Symbol symbol = Symbol.addFunction(name.toUpperCase(), this); if (cold) symbol.setBuiltInFunction(true); setLambdaName(symbol); + installDocString(); } } + public Function(Symbol symbol) + { + this(symbol, null, null); + } + public Function(Symbol symbol, String arglist) { - this(); - symbol.setSymbolFunction(this); - if (cold) - symbol.setBuiltInFunction(true); - setLambdaName(symbol); - setLambdaList(new SimpleString(arglist)); + this(symbol, arglist, null); } public Function(Symbol symbol, String arglist, String docstring) @@ -79,19 +104,14 @@ if (cold) symbol.setBuiltInFunction(true); setLambdaName(symbol); + if(arglist != null) setLambdaList(new SimpleString(arglist)); - if (docstring != null) { + if (docstring != null) symbol.setDocumentation(Symbol.FUNCTION, new SimpleString(docstring)); + installDocString(); } - } - public Function(String name, String arglist) - { - this(name); - setLambdaList(new SimpleString(arglist)); - } - public Function(String name, Package pkg) { this(name, pkg, false); @@ -127,6 +147,7 @@ if (docstring != null) symbol.setDocumentation(Symbol.FUNCTION, new SimpleString(docstring)); + installDocString(); } } Index: org/armedbear/lisp/Java.java --- org/armedbear/lisp/Java.java Base (BASE) +++ org/armedbear/lisp/Java.java Locally Modified (Based On LOCAL) @@ -60,6 +60,7 @@ } private static final Primitive ENSURE_JAVA_OBJECT = new pf_ensure_java_object(); + @DocString(args="obj", doc="Ensures OBJ is wrapped in a JAVA-OBJECT, wrapping it if necessary.") private static final class pf_ensure_java_object extends Primitive { pf_ensure_java_object() @@ -131,13 +132,13 @@ // ### jclass name-or-class-ref &optional class-loader => class-ref private static final Primitive JCLASS = new pf_jclass(); + @DocString(args="name-or-class-ref &optional class-loader", doc="Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader.") private static final class pf_jclass extends Primitive { pf_jclass() { - super(Symbol.JCLASS, "name-or-class-ref &optional class-loader", - "Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader."); + super(Symbol.JCLASS); } @Override @@ -294,12 +295,12 @@ // ### jconstructor class-ref &rest parameter-class-refs private static final Primitive JCONSTRUCTOR = new pf_jconstructor(); + @DocString(args="class-ref &rest parameter-class-refs", doc="Returns a reference to the constructor of CLASS-REF with the given PARAMETER-CLASS-REFS.") private static final class pf_jconstructor extends Primitive { pf_jconstructor() { - super("jconstructor", PACKAGE_JAVA, true, - "class-ref &rest parameter-class-refs"); + super("jconstructor", PACKAGE_JAVA, true); } @Override @@ -344,12 +345,13 @@ // ### jmethod class-ref name &rest parameter-class-refs private static final Primitive JMETHOD = new pf_jmethod(); + + @DocString(args="class-ref name &rest parameter-class-refs", doc="Returns a reference to the method NAME of CLASS-REF with the given PARAMETER-CLASS-REFS.") private static final class pf_jmethod extends Primitive { pf_jmethod() { - super("jmethod", PACKAGE_JAVA, true, - "class-ref name &rest parameter-class-refs"); + super("jmethod", PACKAGE_JAVA, true); } @Override Index: org/armedbear/lisp/Primitive.java --- org/armedbear/lisp/Primitive.java Base (BASE) +++ org/armedbear/lisp/Primitive.java Locally Modified (Based On LOCAL) @@ -45,6 +45,11 @@ super(name); } + public Primitive(Symbol symbol) + { + super(symbol); + } + public Primitive(Symbol symbol, String arglist) { super(symbol, arglist);

1 0

[armedbear-devel] Better Java interop
by Alessio Stalla 02 Jul '10

02 Jul '10

Tonight I committed two changes that will hopefully enhance Java interoperability on ABCL: 1) extensible classpath: two new primitives, java:add-to-classpath and java:dump-classpath, allow respectively to add a path/URL (or a list of them) to the classpath at runtime, and to inspect the classpath for debugging purposes. 2) proxying more than one interface: jmake-proxy now can also accept a list of interfaces to implement in Lisp. I also plan to add some other features, but I'd like to hear feedback about them first: 1) generified <T> T LispObject.javaInstance(Class<T>) to typecheck and avoid casts in user code converting Lisp objects to Java objects. 2) a configurable lists of Java packages to search for classes, so that users might write non-fully-qualified class names, e.g. (jclass "String"). 3) JSS-like syntax for easy method invocation (#methodName args), disabled by default 4) capability of jmethod, jfield, jconstructor to access private members (setAccessible(true)) depending on a special variable (or a function parameter). This was proposed by someone else some time ago but never implemented. Bye, Alessio

3 5

[armedbear-devel] FLET incorrectly optimized away
by William Wadsworth 28 Jun '10

28 Jun '10

Hi, It appears that the compiler mistakenly optimizes out local functions in, say, definer macros. Below is a transcript of a sample session that clarifies the problem: CL-USER(1): (defmacro define-fn (name &body body) `(defun ,name () (flet ((%one () 1)) ,@body))) DEFINE-FN CL-USER(2): (defmacro do-add1 () `(%one)) DO-ADD1 CL-USER(3): (define-fn fn1 (do-add1)) ; Note: deleting unused local function FLET %ONE FN1 CL-USER(4): (fn1) #<THREAD "interpreter" {6DDDCF}>: Debugger invoked on condition of type UNDEFINED-FUNCTION The function %ONE is undefined. Restarts: 0: CONTINUE Try again. 1: USE-VALUE Specify a function to call instead. 2: RETURN-VALUE Return one or more values from the call to %ONE. 3: TOP-LEVEL Return to top level. [1] CL-USER(5): :res Thanks. Martin.

2 2

[armedbear-devel] FLET incorrectly optimized away
by William Wadsworth 26 Jun '10

26 Jun '10

Hi, (It seems that the original message has disappeared, so I repost it.) The attached transcript demonstrates the problem. (I can't seem to be able to put the contents of the REPL transcript inline without the message being labelled as SPAM). Regards, Martin.

1 0

[armedbear-devel] FLET incorrectly optimized away
by William Wadsworth 26 Jun '10

26 Jun '10

I forgot to indicate that this happens on the current [as of 26/6/2010] trunk version). I can also confirm that MACROLET and SLOT-VALUE are now working as expected. Thanks Erik and Alessio for your efforts. Martin.

1 0

[armedbear-devel] strange asdf behavior with 0.20.0
by Kevin Raison 25 Jun '10

25 Jun '10

I just installed 0.20.0 and am now unable to load usocket, yet I can still load cl-ppcre and other Edi-ware. Upon rolling back to 0.19.1, the same usocket package compiles and loads just fine. I have tried using the binary distribution of 0.20.0 as well as building my own, with the same result. There does not seem to be anything wrong with the usocket package definition itself. Has anyone else seen this or know what is going on? Here is the output of 0.20.0: raison@mercury:~/.abcl/lib$ abcl Armed Bear Common Lisp 0.20.0 Java 1.6.0_20 Sun Microsystems Inc. Java HotSpot(TM) Server VM Low-level initialization completed in 0.614 seconds. Startup completed in 1.739 seconds. Type ":help" for a list of available commands. CL-USER(1): (asdf:oos 'asdf:load-op 'usocket) ; loading system definition from /home/raison/.abcl/systems/usocket.asd into #<PACKAGE "ASDF0"> Error loading /home/raison/.abcl/site/usocket-svn/usocket.asd at line 38 (offset 1255) #<THREAD "interpreter" {373E38}>: Debugger invoked on condition of type LOAD-SYSTEM-DEFINITION-ERROR Error while trying to load definition for system usocket from pathname /home/raison/.abcl/systems/usocket.asd: Unrecognized keyword argument :NAME Restarts: 0: TOP-LEVEL Return to top level. [1] USOCKET-SYSTEM(2): -Kevin

4 4

[armedbear-devel] ASDF 2.003
by Faré 25 Jun '10

25 Jun '10

Can ABCL upgrade its ASDF to 2.003 or whichever is latest in the release branch (if possible NOT the master branch)? That would be great. It should fix several bugs that may have hit ABCL users since then. Xach at least reported that upgrading ASDF on ABCL made his software work. As usual, please test on your specific implementation with a few systems before you commit, and please report any bug. [ François-René ÐVB Rideau | Reflection&Cybernethics | http://fare.tunes.org ] One good Husband is worth two good Wives; for the scarcer things are, the more they're valued. — Benjamin Franklin

2 1

[armedbear-devel] compiled MACROLET fails to expand in DEFUN/DEFMETHOD forms
by Mark Evenson 22 Jun '10

22 Jun '10

The following form fails to compile correctly: (macrolet ((output-var (var) `(format t "var = ~A~%" ,var))) (defun baz (bat) (output-var bat))) When the above form has been compiled and loaded CL-USER> (baz 3) errors by complaining. The function OUTPUT-VAR is undefined. Interestingly abcl-0.12.0 behaves correctly, but abcl-0.15.0 fails (For some reason, I don't currently have abcl-0.{13,14} handy to test). I distilled this bug down from trying to compile CXML, so this is a "real-world" problem. CXML bombs on compiling its "xml/xml-parse.lisp" at this point: … (macrolet ((with-context ((validator) &body body) `(let ((*ctx* (context ,validator)) (*validate* t)) (with-scratch-pads () ;nicht schoen ,@body)))) (defmethod sax:start-element ((handler validator) uri lname qname attributes) uri lname (with-context (handler) (validate-start-element *ctx* qname) (process-attributes *ctx* qname attributes))) … with Wrong number of arguments for CXML::HANDLER. [Condition of type PROGRAM-ERROR] I assume that my "distilled" version has the same cause, namely that the precompiler is not expanding macros properly for function/method definitions in top-level MACROLET forms, but I explicitly mention my root problem here if the slightly different error turns out to provide a clue that I have missed. -- "A screaming comes across the sky. It has happened before, but there is nothing to compare to it now."

2 3

[armedbear-devel] New branch: generic-class-file
by Erik Huelsmann 21 Jun '10

21 Jun '10

Some of you know that I have been working on writing a new class file generator. The new class file generator will be replacing the current version which is strictly written for the current compiler. Due to some of the limitations in the class file generator, I'm not even able to change some patterns I'd like to change in it. The new class file generator will allow much more general class file content. It's the explicit intent to support any method type and argument pattern. This goal will allow us to rewrite runtime-class to use our own class writer. The other purpose is to be able to generate more than two methods in a class file: currently we only support 2 (<init> and one of 8 execute(...) methods). I'd like to be able to have many more; for example I want to move initialization of 'final static' fields to <clinit> to make 100% sure they are only initialized once. But that's just one purpose. Another would be to support multiple &optional parameters (but less than 8) without a need to call fastProcessArgs(), but do it in a much more Java-like fashion by generating multiple execute(...) methods. Each method calls the one with more parameters, until all optionals (which were not provided) have been filled, like this; public LispObject execute() { return execute(default1); } public LispObject execute(LispObject arg1) { return execute(arg1, default2); } public LispObject execute(LispObject arg1, LispObject arg2) { .... do actual processing ...; } I'm creating a README on the branch to say the same, for anybody who comes along but did not read this e-mail. Bye, Erik.

1 0