MacroBazaar: javadoc.py

# Copyright 2004 Matthew Good
# "THE BEER-WARE LICENSE" (Revision 42):
# Matthew Good <matt-good.net> wrote this file.  As long as you retain
# this notice you can do whatever you want with this stuff. If we meet some
# day, and you think this stuff is worth it, you can buy me a beer in return.
# Matthew Good

# BEER-WARE LICENSE courtesy of Poul-Henning Kamp <phk@login.dknet.dk>

# Author Matthew Good <trac@matt-good.net>

# Trac WikiMacro for rendering links to Javadoc urls
# Accepts one or two arguments separated by a comma.

# The first argument is the fully qualified Java class or package.
# Classes are assumed to begin with an uppercase letter and packages
# with a lowercase letter according to standard Java naming conventions.

# The second optional argument is the link text.
# If the second argument is ommitted the class name is used,
# or in the case of a package the full package name is used.

#-------------------------------------------------------------------------------
# This block can be edited to change the urls used for the Javadocs
# Note: all Javadoc urls should end with a '/' or index.html

j2se_url = 'http://java.sun.com/j2se/1.4.2/docs/api/index.html'
j2ee_url = 'http://java.sun.com/j2ee/1.4/docs/api/index.html'
xerces_url = 'http://xml.apache.org/xerces2-j/javadocs/api/index.html'

urls = {
    # The URL for the standard Java API
    '': j2se_url,

    # Mappings from package names to Javadoc URLs
    'javax.activation': j2ee_url,
    'javax.ejb': j2ee_url,
    'javax.enterprise': j2ee_url,
    'javax.jms': j2ee_url,
    'javax.mail': j2ee_url,
    'javax.management': j2ee_url,
    'javax.resource': j2ee_url,
    'javax.security.jacc': j2ee_url,
    'javax.servlet': j2ee_url,
    'javax.transaction': j2ee_url,
    'javax.xml': j2ee_url,

    'org.apache.commmons.beanutils':
        'http://jakarta.apache.org/commons/beanutils/commons-beanutils-1.7.0/docs/api/',
    'org.apache.commons.collections':
        'http://jakarta.apache.org/commons/collections/apidocs-COLLECTIONS_3_1/index.html',
    'org.apache.commons.lang':
        'http://jakarta.apache.org/commons/lang/api/index.html',

    'org.w3c.dom': xerces_url,
    'org.xml.sax': xerces_url
    }
#-------------------------------------------------------------------------------

from urlparse import urljoin
from string import uppercase

def best_match(value, items):
    match = ''
    for i in items:
        if len(i) > len(match) and value.startswith(i):
            match = i
            
    return match

def base_url(package):
    return urls[best_match(package, urls.keys())]
    
def package_path(package):
    return package.replace('.', '/') + '/'
    
def type_path(package, clss):
    return package_path(package) + (clss and (clss + '.html') or 'package-summary.html')
    
def javadoc_url(package, clss):
    return urljoin(base_url(package), type_path(package, clss))
    
def split_at(a, index):
    return (a[:index], a[index + 1:])
    
def split_type(value):
    package, clss = split_at(value, value.rfind('.'))
    if clss[0] in uppercase:
        return (package, clss)
    else:
        return (value, None)
    
def link(href, text):
    return '<a href="%s" class="javadoc">%s</a>' % (href, text)
    
def javadoc_link(value, linktext):
    package, clss = split_type(value)
    return link(javadoc_url(package, clss), linktext or clss or package)

def execute(hdf, txt, env):
    args = txt.split(',', 1)
    javatype = args[0].strip()
    linktext = len(args) > 1 and args[1].strip() or None
    return javadoc_link(javatype, linktext)