Mercurial > lasercutter

diff src/clojure/asm/package.html @ 10:ef7dbbd6452c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added clojure source goodness
author Robert McIntyre <rlm@mit.edu>
date Sat, 21 Aug 2010 06:25:44 -0400
parents
children
line wrap: on
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/src/clojure/asm/package.html	Sat Aug 21 06:25:44 2010 -0400
     1.3 @@ -0,0 +1,87 @@
     1.4 +<html>
     1.5 +<!--
     1.6 + * ASM: a very small and fast Java bytecode manipulation framework
     1.7 + * Copyright (c) 2000-2005 INRIA, France Telecom
     1.8 + * All rights reserved.
     1.9 + *
    1.10 + * Redistribution and use in source and binary forms, with or without
    1.11 + * modification, are permitted provided that the following conditions
    1.12 + * are met:
    1.13 + * 1. Redistributions of source code must retain the above copyright
    1.14 + *    notice, this list of conditions and the following disclaimer.
    1.15 + * 2. Redistributions in binary form must reproduce the above copyright
    1.16 + *    notice, this list of conditions and the following disclaimer in the
    1.17 + *    documentation and/or other materials provided with the distribution.
    1.18 + * 3. Neither the name of the copyright holders nor the names of its
    1.19 + *    contributors may be used to endorse or promote products derived from
    1.20 + *    this software without specific prior written permission.
    1.21 + *
    1.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    1.23 + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    1.24 + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    1.25 + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
    1.26 + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    1.27 + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    1.28 + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    1.29 + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    1.30 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    1.31 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
    1.32 + * THE POSSIBILITY OF SUCH DAMAGE.
    1.33 +-->
    1.34 +<body>
    1.35 +Provides a small and fast bytecode manipulation framework.
    1.36 +
    1.37 +<p>
    1.38 +	The <a href="http://www.objectweb.org/asm">ASM</a> framework is organized
    1.39 +	around the {@link clojure.asm.ClassVisitor ClassVisitor},
    1.40 +	{@link clojure.asm.FieldVisitor FieldVisitor} and
    1.41 +	{@link clojure.asm.MethodVisitor MethodVisitor} interfaces, which allow
    1.42 +	one to visit the fields and methods of a class, including the bytecode
    1.43 +	instructions of each method.
    1.44 +
    1.45 +<p>
    1.46 +	In addition to these main interfaces, ASM provides a {@link
    1.47 +	clojure.asm.ClassReader ClassReader} class, that can parse an
    1.48 +	existing class and make a given visitor visit it. ASM also provides
    1.49 +	a {@link clojure.asm.ClassWriter ClassWriter} class, which is
    1.50 +	a visitor that generates Java class files.
    1.51 +
    1.52 +<p>
    1.53 +	In order to generate a class from scratch, only the {@link
    1.54 +	clojure.asm.ClassWriter ClassWriter} class is necessary. Indeed,
    1.55 +	in order to generate a class, one must just call its visit<i>XXX</i>
    1.56 +	methods with the appropriate arguments to generate the desired fields
    1.57 +	and methods. See the "helloworld" example in the ASM distribution for
    1.58 +	more details about class generation.
    1.59 +
    1.60 +<p>
    1.61 +	In order to modify existing classes, one must use a {@link
    1.62 +	clojure.asm.ClassReader ClassReader} class to analyze
    1.63 +	the original class, a class modifier, and a {@link clojure.asm.ClassWriter
    1.64 +	ClassWriter} to construct the modified class. The class modifier
    1.65 +	is just a {@link clojure.asm.ClassVisitor ClassVisitor}
    1.66 +	that delegates most of the work to another {@link clojure.asm.ClassVisitor
    1.67 +	ClassVisitor}, but that sometimes changes some parameter values,
    1.68 +	or call additional methods, in order to implement the desired
    1.69 +	modification process. In order to make it easier to implement such
    1.70 +	class modifiers, ASM provides the {@link clojure.asm.ClassAdapter
    1.71 +	ClassAdapter} and {@link clojure.asm.MethodAdapter MethodAdapter}
    1.72 +	classes, which implement the {@link clojure.asm.ClassVisitor ClassVisitor}
    1.73 +	and {@link clojure.asm.MethodVisitor MethodVisitor} interfaces by
    1.74 +	delegating all work to other visitors. See the "adapt" example in the ASM
    1.75 +	distribution for more details about class modification.
    1.76 +
    1.77 +<p>
    1.78 +	The size of the core ASM library, <tt>asm.jar</tt>, is only 42KB, which is much
    1.79 +	smaller than the size of the
    1.80 +	<a href="http://jakarta.apache.org/bcel">BCEL</a> library (504KB), and than the
    1.81 +	size of the
    1.82 +	<a href="http://serp.sourceforge.net">SERP</a> library (150KB). ASM is also
    1.83 +	much faster than these tools. Indeed the overhead of a load time class
    1.84 +	transformation process is of the order of 60% with ASM, 700% or more with BCEL,
    1.85 +	and 1100% or more with SERP (see the <tt>test/perf</tt> directory in the ASM
    1.86 +	distribution)!
    1.87 +
    1.88 +	@since ASM 1.3
    1.89 +</body>
    1.90 +</html>