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. Also, these docs are incomplete and
not even up to date! I will update them soon, I promise.

======================================================================
_java.ss_: 
======================================================================

> (current-classpath [cp]) :: (parameterof (listof path))

> (current-sourcepath [sp]) :: (parameterof (listof path))

======================================================================
_syntax/class-file.ss_: 
======================================================================

TODO: info struct hierarchy

> (define-struct class-file (pool flags this super interfaces fields methods attributes))

> (extract-access-flags bits) :: exact-integer -> (listof access-flag)

> (utf8-info->string ui) :: utf8-info -> string

> (read-class-file [in]) :: [input-port] -> class-file

> access-flag/c :: contract

======================================================================
_syntax/ast.ss_:
======================================================================

TODO: src struct
TODO: ast struct hierarchy

======================================================================
_syntax/lexer.ss_:
======================================================================

======================================================================
_syntax/parser.ss_:
======================================================================

> parse : [input-port (optional (union path string))] -> ast

> parse-string : string -> ast

> parse-file : (union path string) -> ast

======================================================================
_semantics/semantic-object.ss_:
======================================================================

> (define-struct type-name (package type)) :: (listof symbol) symbol?

> (build-type-name path) :: (listof symbol) -> type-name

> (dot-notation path) :: (listof symbol) -> string

> (type-name->string tn) :: (optional type-name) -> string

> byte, char, double, float, int, long, short, boolean :: primitive-type%

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.

The mzscheme interfaces defined in this library are organized according to the
following graph:

    semantic-object<%>   resolvable<%>
          |                   |
          +---------+---------+
                    |
                 type<%>

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%

++ 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.

++ class package% implements semantic-object<%>

> (new package% (name pn)) :: (listof symbol) -> package%

> (to-string) :: -> string

Returns the package name in dot-notation.

++ 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-name) :: -> type-name

> (resolve-all) :: -> any

> (to-string) :: -> string

++ class unknown-type% extends ground-type%

> (new unknown-type% (package pn) (name tn)) :: (listof symbol) type-name -> unknown-type%

++ class primitive-type% extends ground-type%

> (new primitive-type% (name tn)) :: type-name -> primitive-type%

++ class declared-type% extends ground-type%

;; TODO: left off here updating docs....

> (new declared-type% (package-name pn)
                      (type-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 array-type% implements type<%>

> (new array-type% (base-type bt)) :: (union type-name type<%>) -> array-type%

> (get-base-type) :: -> type<%>

> (get-dimension) :: -> natural-number

> (resolve-all) :: -> any

> (to-string) :: -> string

++ class class% extends declared-type%

> (new class% (package-name pn)
              (type-name tn)
              (modifiers mods)
              (interfaces ifs)
              (elements elts)
              (superclass sup)) :: (listof symbol)
                                   type-name
                                   (listof access-flag)
                                   (listof type-name)
                                   (listof type-element%)
                                   (optional class%)
                                -> class%

> (get-superclass) :: -> class%

++ class interface% extends declared-type%

> (new interface% (package-name pn)
                  (type-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)

> (resolve-all) :: -> any

> (to-string) :: -> string

++ class field% extends type-element%

> (new field% (name n)
              (modifiers mods)
              (type t)) :: string
                           (listof access-flag)
                           (union type-name type<%>)
                        -> field%

> (get-modifiers) :: -> (listof access-flag)

> (get-type) :: -> type<%>

++ class initializer% extends type-element%

> (new initializer%)

++ class behavior% extends type-element%

> (new behavior% (name n)
                 (formals fs)
                 (exceptions es)) :: string
                                     (listof (union type-name type<%>))
                                     (listof (union type-name type<%>))
                                  -> behavior%

> (get-formals) :: -> (listof type<%>)

> (get-exceptions) :: -> (listof type<%>)

++ 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 (union type-name type<%>))
                                    (listof (union type-name type<%>))
                                    (listof access-flag)
                                    (option (union type-name type<%>))
                                 -> method%

> (get-modifiers) :: -> (listof access-flag)

> (get-return-type) :: -> (option type<%>)

++ class inner-type% extends type-element%

> (new inner-type% (name n) (type t)) :: string (union type-name type<%>) -> inner-type%

> (get-type) :: -> type<%>

======================================================================
_semantics/class-resolver.ss_:
======================================================================

> (current-class-resolver [cr]) :: (parameterof class-resolver<%>)

TODO: need to solidify what happens when a type/package isn't there

> (lookup-package pkg) :: (listof symbol) -> (optional package%)

> (lookup-type tn) :: type-name -> (option type<%>)

> (resolve-all t) :: (union type-name semantic-object<%>) -> any

++ interface class-resolver<%>

> (resolve-package path) :: (listof symbol) -> (optional package%)

> (resolve-type tn) :: type-name -> (option 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 -> ?

======================================================================
_semantics/resolve-binary.ss_:
======================================================================

> (resolve-binary cf) :: class-file -> declared-type%