Java
_Java_
_java_
The libraries of the "java" collection provide utilities for manipulating Java
programs in both source and binary format.
*** CAVEAT: This library is still in its rather early stages. Expect significant
changes to the API to occur in the future.
======================================================================
_java.ss_:
======================================================================
> (current-classpath [cp]) :: (parameterof (listof path))
A parameter containing a list of paths that point to either directories where
.class files reside or .zip/.jar files containing .class files. This is used by
the standard class resolver in _semantics/standard-resolver.ss_.
> (current-sourcepath [sp]) :: (parameterof (listof path))
A parameter containing a list of paths that point to directories where .java
files reside. This is used by the standard class resolver in
_semantics/standard-resolver.ss_.
======================================================================
_syntax/class-file.ss_:
======================================================================
This module provides procedures for reading compiled Java .class files according
to the Java class file format, as specified by Chapter 4 of the Java Virtual
Machine Specification, 2nd Ed.
http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html
http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html
> (struct class-file (pool flags this super interfaces fields methods attributes))
This structure encapsulates all the information read in from a class file.
> (extract-access-flags bits) :: exact-integer [(union 'super 'synchronized)] -> (listof access-flag)
A utility for converting access flags packed in the bits of an exact integer
into a list of their corresponding symbolic names. The possible access flags
occurring in a bit field can be enumerated by taking the union of tables 4.1,
4.4, 4.5, and 4.7 of the JVM specification.
Unfortunately, there is a single overlap amongst these tables: both
ACC_SUPER and ACC_SYNCHRONIZED have the value 0x0020. The second optional
argument allows clients to specify which way to interpret the value; by default
the procedure produces the symbol 'super/synchronized.
Flag name Bit Symbolic value
--------- --- --------------
ACC_PUBLIC 0x0001 'public
ACC_PRIVATE 0x0002 'private
ACC_PROTECTED 0x0004 'protected
ACC_STATIC 0x0008 'static
ACC_FINAL 0x0010 'final
ACC_SUPER 0x0020 'super
ACC_SYNCHRONIZED 0x0020 'synchronized
ACC_VOLATILE 0x0040 'volatile
ACC_TRANSIENT 0x0080 'transient
ACC_NATIVE 0x0100 'native
ACC_INTERFACE 0x0200 'interface
ACC_ABSTRACT 0x0400 'abstract
ACC_STRICT 0x0800 'strictfp
> (utf8-info->string ui) :: utf8-info -> string
Converts a utf8-info struct into a Unicode string.
> (read-class-file [in]) :: [input-port] -> class-file
Reads a class file from an input port.
> access-flag/c :: contract
The _class-file.ss_ library defines a hierarchy of structures representing the
elements of a class file. The structures are organized according to the
following hierarchy:
info
|
+-- class-info
| o name-index :: natural-number
|
+-- ref-info
| o class-index :: natural-number
| o name-and-type-index :: natural-number
| |
| +-- field-ref-info
| |
| +-- method-ref-info
| |
| +-- interface-method-ref-info
|
+-- string-info
| o string-index :: natural-number
|
+-- integer-info
| o value :: integer
|
+-- float-info
| o bytes :: bytes
|
+-- long-info
| o high-bytes :: bytes
| o low-bytes :: bytes
|
+-- double-info
| o high-bytes :: bytes
| o low-bytes :: bytes
|
+-- name-and-type-info
| o name-index :: natural-number
| o descriptor-index :: natural-number
|
+-- utf8-info
| o length :: natural-number
| o bytes :: bytes
|
+-- inner-class-entry
| o inner-class-info-index :: natural-number
| o outer-class-info-index :: natural-number
| o inner-name-index :: natural-number
| o inner-class-access-flags :: integer
|
+-- element-info
| o access-flags :: integer
| o name-index :: natural-number
| o descriptor-index :: natural-number
| o attributes-count :: natural-number
| o attributes :: (listof attribute-info)
| |
| +-- field-info
| |
| +-- method-info
|
+-- attribute-info
|
+-- unsupported-attribute-info
| o length :: natural-number
| o bytes :: bytes
|
+-- constant-value-attribute-info
| o value-index :: natural-number
|
+-- code-attribute-info
|
+-- exceptions-attribute-info
| o count :: natural-number
| o exceptions :: (listof natural-number)
|
+-- inner-classes-attribute-info
|
+-- synthetic-attribute-info
|
+-- source-file-attribute-info
|
+-- line-number-table-attribute-info
|
+-- local-variable-table-attribute-info
|
+-- deprecated-attribute-info
======================================================================
_syntax/ast.ss_:
======================================================================
The _ast.ss_ module defines a hierarchy of structures representing nodes in the
abstract syntax tree of a Java program. The structures are organized according
to the following hierarchy:
ast
o src :: (optional src)
|
+-- id
| o name :: symbol
|
+-- name
| o path :: (listof id)
| o id :: id
|
+-- import
| o name :: name
| o star? :: boolean
|
+-- type-spec
| o base-type :: type-name
| o dimension :: natural-number
|
+-- modifier
| o modifier :: symbol
|
+-- initializer
| o static? :: boolean
| o body :: block-stmt
|
+-- compilation-unit
| o package :: (optional name)
| o imports :: (listof import)
| o classes :: (listof (optional type-decl))
|
+-- decl
| o modifiers :: (listof modifier)
| o name :: id
| |
| +-- type-decl
| | o interfaces :: (listof name)
| | o body :: (listof class-element)
| | |
| | +-- class-decl
| | | o super :: (optional name)
| | |
| | +-- interface-decl
| |
| +-- variable-decl
| | o type :: type-spec
| | o init :: (optional expr)
| |
| +-- behavior-decl
| o formals :: (listof variable-decl)
| o throws :: (listof name)
| o body :: block-stmt
| |
| +-- constructor-decl
| |
| +-- method-decl
| o return-type :: type-spec
|
+-- stmt
| |
| +-- expr-stmt
| | o expr :: expr
| |
| +-- labeled-stmt
| | o label :: id
| | o stmt :: (optional stmt)
| |
| +-- block-stmt
| | o body :: (listof block-element)
| |
| +-- switch-stmt
| | o expr :: expr
| | o clauses :: (listof (union case-stmt block-element))
| |
| +-- case-stmt
| | o test :: (optional expr)
| |
| +-- if-stmt
| | o test :: expr
| | o con :: (optional stmt)
| | o alt :: (optional stmt)
| |
| +-- for-stmt
| | o init :: (union (listof variable-decl) (listof expr))
| | o test :: (optional expr)
| | o update :: (listof expr)
| | o body :: (optional stmt)
| |
| +-- while-stmt
| | o test :: expr
| | o body :: (optional stmt)
| |
| +-- do-stmt
| | o body :: stmt
| | o test :: expr
| |
| +-- break-stmt
| | o label :: (optional id)
| |
| +-- continue-stmt
| | o label :: (optional id)
| |
| +-- return-stmt
| | o value :: (optional expr)
| |
| +-- throw-stmt
| | o expr :: expr
| |
| +-- synchronized-stmt
| | o expr :: expr
| | o body :: stmt
| |
| +-- try-stmt
| | o body :: block-stmt
| | o catches :: (listof catch-stmt)
| | o finally :: (optional block-stmt)
| |
| +-- catch-stmt
| | o exception :: variable-decl
| | o body :: block-stmt
| |
| +-- assert-stmt
| o predicate :: expr
| o message :: expr
|
+-- expr
|
+-- conditional-expr
| o test :: expr
| o con :: expr
| o alt :: expr
|
+-- prefix-expr
| o op-src :: src
| o operator :: symbol
| o operand :: expr
|
+-- postfix-expr
| o op-src :: src
| o operator :: symbol
| o operand :: expr
|
+-- unary-expr
| o op-src :: src
| o operator :: symbol
| o operand :: expr
|
+-- binary-expr
| o op-src :: src
| o operator :: symbol
| o left :: expr
| o right :: expr
|
+-- instanceof-expr
| o op-src :: src
| o expr :: expr
| o type :: type-spec
|
+-- literal
| o value :: any
| |
| +-- boolean-literal
| |
| +-- char-literal
| |
| +-- integer-literal
| |
| +-- long-literal
| |
| +-- float-literal
| |
| +-- double-literal
| |
| +-- string-literal
| |
| +-- null-literal
|
+-- class-expr
| o type :: type-spec
|
+-- new-object-expr
| o container :: (optional expr)
| o name :: name
| o args :: (listof expr)
| o class-body :: (optional (listof class-element))
|
+-- new-array-expr
| o type :: type-spec
| o dim-exprs :: (listof expr)
| o dim :: natural-number
| o init :: (optional array-initializer)
|
+-- array-initializer
| o contents :: (listof expr)
|
+-- call-expr
| o object :: (optional expr)
| o name :: name
| o args :: (listof expr)
|
+-- assign-expr
| o operator :: symbol
| o left :: access
| o right :: expr
|
+-- cast-expr
| o type :: type-spec
| o expr :: expr
|
+-- access
|
+-- field-access
| o object :: expr
| o name :: id
|
+-- array-access
| o array :: expr
| o index :: expr
|
+-- var-access
o var :: name
Every AST node can contain a field of type `src', which represents the source
location information of the item.
> (struct src (file line col span)) :: (optional path) * (optional natural-number) * (optional natural-number) * (optional natural-number)
> (name->access name) :: name -> access
Converts a name to a variable reference.
> (access->name acc) :: (union field-access var-access) -> name
Converts a field or local variable reference to a name.
> (increase-type-dimension ts n) :: type-spec natural-number -> type-spec
Constructs a new type-spec which is equivalent to `ts' except with type
dimension increased by `n'.
======================================================================
_syntax/lexer.ss_:
======================================================================
The _lexer.ss_ module provides a lexer for Java.
> Operators :: empty-tokens
> Separators :: empty-tokens
> EmptyLiterals :: empty-tokens
> Keywords :: empty-tokens
> BasicTokens :: tokens
> (struct string-error (string error-token)) :: string position-token
> (java-lexer in) :: input-port -> position-token
======================================================================
_syntax/parser.ss_:
======================================================================
The _parser.ss_ module provides a parser for Java.
> (parse in path) :: [input-port (optional (union path string))] -> ast
Parses a Java compilation unit (i.e., the contents of a .java file) from an
input port, with the given file name (used for error reporting).
> (parse-string str) :: string -> ast
Parses a Java compilation unit from a string.
> (parse-file path) :: (union path string) -> ast
Parses a Java comilation unit from a file.
======================================================================
_semantics/semantic-object.ss_:
======================================================================
The _semantic-object.ss_ library defines a hierarchy of mzscheme classes and
interfaces for the representation of the (static) semantic elements of a Java
program, e.g., classes, interfaces, methods, fields, etc.
> (struct type-name (package type [dimension])) :: (listof symbol) symbol? natural-number
The `type-name' structure contains enough information to identify a type
uniquely and can be used to look up a type with a class resolver (see
_class-resolver.ss). The `package' field contains the name of the type's package
(primitive types and members of the default package use the empty list). The
`type' field contains the symbolic name of the type. The optional `dimension'
field contains the array dimension and defaults to 0, representing a ground
(i.e., non-array) type.
> (build-type-name path) :: (listof symbol) -> type-name
Given a fully qualified type name as a list of symbols, this procedure builds a
`type-name' structure representing that name.
> (dot-notation path) :: (listof symbol) -> string
Given a fully qualified type name as a list of symbols, this procedure
constructs the string representation of the fully qualified name in Java
``dot-notation''.
> (type-name->string tn) :: (optional type-name) -> string
Given a `type-name' struct (or #f, representing the ``void'' type), this
procedure constructs the string representation of the fully qualified name in
Java ``dot-notation''.
> byte, char, double, float, int, long, short, boolean :: primitive-type%
Objects of class primitive-type% representing the Java primitive types of the
same respective name.
Interfaces
----------
The mzscheme interfaces defined in this library are organized according to the
following graph:
semantic-object<%> resolvable<%>
| |
+---------+---------+
|
type<%>
++ interface semantic-object<%>
> (to-string) :: -> string
Returns a string representation of the semantic object.
++ interface resolvable<%>
> (get-related-types) :: -> (listof type-name)
Returns the list of type-names that are referenced in the definition of the
semantic object.
++ interface type<%> extends semantic-object<%>, resolvable<%>
> (get-type-name) :: -> type-name
Returns the type-name representing the type object.
Classes
-------
The mzscheme classes defined in this library are organized according to the
following hierarchy (classes without parent classes extend the standard mzscheme
object% class):
package% (semantic-object<%>, resolvable<%>)
array-type% (type<%>)
ground-type% (type<%>)
|
+-- primitive-type%
|
+-- declared-type%
|
+-- class%
|
+-- interface%
type-element% (semantic-object<%>, resolvable<%>)
|
+-- field%
|
+-- behavior%
| |
| +-- constructor%
| |
| +-- method%
|
+-- initializer%
|
+-- inner-type%
++ class package% implements semantic-object<%>
> (new package% (name pn)) :: (listof symbol) -> package%
> (to-string) :: -> string
Returns the package name in dot-notation.
++ class array-type% implements type<%>
> (new array-type% (base-type bt)) :: type-name -> array-type%
> (get-type-name) :: -> type-name
> (get-base-type) :: -> type-name
> (get-dimension) :: -> natural-number
> (get-related-types) :: -> (listof type-name)
> (to-string) :: -> string
++ class ground-type% implements semantic-object<%>, type<%>
> (new ground-type% (package pn) (name tn)) :: (listof symbol) type-name -> ground-type%
> (get-package) :: -> (optional package%)
> (get-type-name) :: -> type-name
> (get-related-types) :: (listof type-name)
> (to-string) :: -> string
++ class primitive-type% extends ground-type%
> (new primitive-type% (name tn)) :: type-name -> primitive-type%
++ class declared-type% extends ground-type%
> (new declared-type% (package-name pn)
(name tn)
(modifiers mods)
(interfaces ifs)
(elements elts)) :: (listof symbol)
type-name
(listof access-flag)
(listof type-name)
(listof type-element%)
-> declared-type%
> (get-modifiers) :: -> (listof access-flag)
> (get-interfaces) :: -> (listof type-name)
> (get-elements) :: -> (listof type-element%)
++ class class% extends declared-type%
> (new class% (package pn)
(name tn)
(modifiers mods)
(interfaces ifs)
(elements elts)
(superclass sup)) :: (listof symbol)
type-name
(listof access-flag)
(listof type-name)
(listof type-element%)
(optional type-name)
-> class%
> (get-superclass) :: -> type-name
++ class interface% extends declared-type%
> (new interface% (package pn)
(name tn)
(modifiers mods)
(interfaces ifs)
(elements elts) :: (listof symbol)
type-name
(listof access-flag)
(listof type-name)
(listof type-element%)
-> interface%
++ class type-element% implements semantic-object<%>, resolvable<%>
> (new type-element% (name n)) :: string -> type-element%
> (get-name) :: -> (option string)
> (get-related-types) :: (listof type-name)
> (to-string) :: -> string
++ class field% extends type-element%
> (new field% (name n)
(modifiers mods)
(type t)) :: string
(listof access-flag)
type-name
-> field%
> (get-modifiers) :: -> (listof access-flag)
> (get-type) :: -> type-name
++ class initializer% extends type-element%
> (new initializer%)
++ class behavior% extends type-element%
> (new behavior% (name n)
(formals fs)
(exceptions es)) :: string
(listof type-name)
(listof type-name)
-> behavior%
> (get-formals) :: -> (listof type-name)
> (get-exceptions) :: -> (listof type-name)
++ class constructor% extends behavior%
> (new constructor% (name n)
(formals fs)
(exceptions es)) :: string
(listof (union type-name type<%>))
(listof (union type-name type<%>))
-> constructor%
++ class method% extends behavior%
> (new method% (name n)
(formals fs)
(exceptions es)
(modifiers mods)
(return-type rt)) :: string
(listof type-name)
(listof type-name)
(listof access-flag)
(optional type-name)
-> method%
> (get-modifiers) :: -> (listof access-flag)
> (get-return-type) :: -> (optional type-name)
++ class inner-type% extends type-element%
> (new inner-type% (name n) (type t)) :: string type-name -> inner-type%
> (get-type) :: -> type-name
======================================================================
_semantics/class-resolver.ss_:
======================================================================
;; TODO: this should not be starting out #f
> (current-class-resolver [cr]) :: (parameterof class-resolver<%>)
> (lookup-package pkg) :: (listof symbol) -> (optional package%)
> (lookup-type tn) :: type-name -> (optional type<%>)
> (resolve-all t) :: (union type-name semantic-object<%>) -> any
Forces the resolution (via the current class resolver) of the transitive closure
of the `get-related-types' relation on either a semantic object or the type
associated with a type-name.
++ interface class-resolver<%>
> (resolve-package path) :: (listof symbol) -> (optional package%)
> (resolve-type tn) :: type-name -> (optional type<%>)
======================================================================
_semantics/standard-resolver.ss_:
======================================================================
++ class class-resolver% implements class-resolver<%>
> (resolve-package path) :: (listof symbol) -> (optional package%)
> (resolve-type tn) :: type-name -> (option type<%>)
======================================================================
_semantics/resolve-source.ss_:
======================================================================
TODO: (resolve-source ast) :: ast -> (listof declared-type%)
======================================================================
_semantics/resolve-binary.ss_:
======================================================================
> (resolve-binary cf) :: class-file -> declared-type%