diff --git a/README.md b/README.md index 268735e..5a86a7a 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,17 @@ where: and options are: * -? prints usage to stdout; exits (optional) -* -d output directory (required) +* -d <f> output directory (required) +* -ext <s> the output file extension, defaults to '.html' (optional) * -h prints usage to stdout; exits (optional) * -help displays verbose help information (optional) -* -tpl alternative templates to use (optional) +* -tpl <f> alternative templates to use (optional) ## Maven dependencies -You'll need to install `jcmdline-1.0.1.jar` manually (Available from [here](http://jcmdline.sourceforge.net/)): +You'll need to install `jcmdline-2.0.0.jar` manually (Available from [here](http://jcmdline.sourceforge.net/)): -`mvn install:install-file -Dfile=jcmdline-1.0.1.jar -DgroupId=jcmdline -DartifactId=jcmdline -Dversion=1.0.1 -Dpackaging=jar` +`mvn install:install-file -Dfile=jcmdline-2.0.0.jar -DgroupId=jcmdline -DartifactId=jcmdline -Dversion=2.0.0 -Dpackaging=jar` ## Comment syntax @@ -44,9 +45,9 @@ Example: ``` <#--- Does fancy stuff. - +

And does it well !

- + @param fist The first parameter. @param second The second parameter, a boolean. --> @@ -91,4 +92,4 @@ To do so, use the `-tpl jcmdline jcmdline - 1.0.1 + 2.0.0 jar @@ -57,4 +57,4 @@ - \ No newline at end of file + diff --git a/src/main/java/freemarker/tools/ftldoc/FtlDoc.java b/src/main/java/freemarker/tools/ftldoc/FtlDoc.java index f2583e6..c93e9a3 100644 --- a/src/main/java/freemarker/tools/ftldoc/FtlDoc.java +++ b/src/main/java/freemarker/tools/ftldoc/FtlDoc.java @@ -21,7 +21,7 @@ * Alternately, this acknowledgement may appear in the software itself, * if and wherever such third-party acknowledgements normally appear. * - * 4. Neither the name "FreeMarker", "Visigoth", nor any of the names of the + * 4. Neither the name "FreeMarker", "Visigoth", nor any of the names of the * project contributors may be used to endorse or promote products derived * from this software without prior written permission. For written * permission, please contact visigoths@visigoths.org. @@ -48,7 +48,7 @@ * individuals on behalf of the Visigoth Software Society. For more * information on the Visigoth Software Society, please see * http://www.visigoths.org/ - */ + */ package freemarker.tools.ftldoc; @@ -61,6 +61,7 @@ import java.util.regex.Pattern; import jcmdline.CmdLineHandler; +import jcmdline.StringParam; import jcmdline.FileParam; import jcmdline.HelpCmdLineHandler; import jcmdline.Parameter; @@ -74,18 +75,18 @@ /** * Main ftldoc class (includes command line tool). - * + * * @author Stephan Mueller */ public class FtlDoc { - + private static final String EXT_FTL = ".ftl"; - + private static final FilenameFilter FTL_FILENAME_FILTER = new FilenameFilter() { public boolean accept(File dir, String name) { return name.endsWith(EXT_FTL); } }; - + private static final Comparator MACRO_COMPARATOR = new Comparator() { public int compare(Object o1, Object o2) { return ((Map)o1).get("name").toString().toLowerCase().compareTo(((Map)o2).get("name").toString().toLowerCase()); @@ -100,12 +101,12 @@ public int compare(Object o1, Object o2) { private static enum Templates { file("file"),index("index"),indexAllCat("index-all-cat"), indexAllAlpha("index-all-alpha"), overview("overview"), filelist("filelist"); - + private final String fileName; private Templates(String fileName) { this.fileName = fileName; } - + public String fileName() { return fileName + EXT_FTL; } @@ -120,20 +121,21 @@ public String fileName() { private List fParsedFiles; private Set fAllDirectories; private File fAltTemplatesFolder; - + private static String extDocs = ".html"; + List regions = new LinkedList(); - + private Configuration cfg = null; - - + + public FtlDoc(List files, File outputDir, File altTemplatesFolder) { cfg = new Configuration(); cfg.setWhitespaceStripping(false); - + fOutDir = outputDir; fFiles = files; fAltTemplatesFolder = altTemplatesFolder; - + // extracting parent directories of all files fAllDirectories = new HashSet(); Iterator iter = files.iterator(); @@ -142,27 +144,29 @@ public FtlDoc(List files, File outputDir, File altTemplatesFolder) { File f = (File)iter.next(); fAllDirectories.add(f.getParentFile()); } - + } - + public static void main(String[] args) { // parse command line args - FileParam outDirParam = new FileParam("d","output directory",FileParam.NO_ATTRIBUTES, FileParam.REQUIRED); - FileParam altTplParam = new FileParam("tpl","alternative templates to use", FileParam.NO_ATTRIBUTES, FileParam.OPTIONAL); - FileParam filesArg = - new FileParam("file", - "the templates",FileParam.NO_ATTRIBUTES, - FileParam.REQUIRED, - FileParam.MULTI_VALUED); + FileParam outDirParam = new FileParam("d","output directory",FileParam.NO_ATTRIBUTES, FileParam.REQUIRED,FileParam.SINGLE_VALUED); + FileParam altTplParam = new FileParam("tpl","alternative templates to use", FileParam.NO_ATTRIBUTES, FileParam.OPTIONAL,FileParam.SINGLE_VALUED); + FileParam filesArg = new FileParam("file","the templates",FileParam.NO_ATTRIBUTES, FileParam.REQUIRED,FileParam.MULTI_VALUED); + StringParam outExtParam = new StringParam("ext", "The output file extension. Defaults to '.html' ", StringParam.OPTIONAL); CmdLineHandler cl = new HelpCmdLineHandler("ftldoc help","ftldoc","generates ftldocs", - new Parameter[]{outDirParam, altTplParam}, + new Parameter[]{outDirParam, altTplParam, outExtParam}, new Parameter[]{filesArg}); cl.parse(args); - File outDir = outDirParam.getFile(); - + File outDir = outDirParam.getValue(); + + // override doc file ext is set. + if(outExtParam.getValue() != null){ + extDocs = outExtParam.getValue(); + } + // collect all files List files = new ArrayList(); - Iterator iter = filesArg.getFiles().iterator(); + Iterator iter = filesArg.getValues().iterator(); while (iter.hasNext()) { Object element = iter.next(); @@ -177,7 +181,7 @@ public static void main(String[] args) { } } } - + // create output directory if(!outDir.exists()) { if(!outDir.mkdirs()) { @@ -185,10 +189,10 @@ public static void main(String[] args) { return; }; } - + File altTpl = null; if (altTplParam.isSet()) { - altTpl = altTplParam.getFile(); + altTpl = altTplParam.getValue(); if (altTpl.isDirectory() && altTpl.canRead()) { // Ensure all the required templates are there for (Templates t: Templates.values()) { @@ -204,12 +208,12 @@ public static void main(String[] args) { return; } } - + FtlDoc ftl = new FtlDoc(files, outDir, altTpl); ftl.run(); } - - + + private void addCategory(String name) { if(!categories.containsKey(name)) { categories.put(name,new ArrayList()); @@ -218,19 +222,19 @@ private void addCategory(String name) { allCategories.put(name,new ArrayList()); } } - + private void createCategoryRegions(Template t) { regions = new LinkedList(); - + TemplateElement te = t.getRootTreeNode(); Map pc; Comment c; Comment regionStart = null; - + String name = null; int begincol = 0; int beginline = 0; - + Stack nodes = new Stack(); nodes.push(te); while(!nodes.isEmpty()) { @@ -238,11 +242,11 @@ private void createCategoryRegions(Template t) { for(int i = te.getChildCount()-1;i>=0;i--) { nodes.push(te.getChildAt(i)); } - + if(te instanceof Comment) { c = (Comment)te; pc = parse(c); - + if(pc.get("@begin")!=null) { if(regionStart!=null) { System.err.println("WARNING: nested @begin-s"); @@ -253,8 +257,8 @@ private void createCategoryRegions(Template t) { name = pc.get("@begin").toString().trim(); begincol = c.getBeginColumn(); beginline = c.getBeginLine(); - - + + regionStart = c; } if(pc.get("@end")!=null) { @@ -267,8 +271,8 @@ private void createCategoryRegions(Template t) { regionStart = null; } } - - + + } } if(regionStart!=null) { @@ -278,7 +282,7 @@ private void createCategoryRegions(Template t) { regions.add(cc); } } - + private void addMacro(Map macro) { macros.add(macro); allMacros.add(macro); @@ -297,12 +301,12 @@ private void addMacro(Map macro) { } allCat.add(macro); } - + private void createFilePage(File file) { try { - File htmlFile = new File(fOutDir,file.getName()+".html"); + File htmlFile = new File(fOutDir,file.getName()+ extDocs); System.out.println("Generating " + htmlFile.getCanonicalFile() + "..."); - + Template t_out = cfg.getTemplate(Templates.file.fileName()); categories = new TreeMap(); TemplateElement te = null; @@ -311,9 +315,9 @@ private void createFilePage(File file) { macros = new ArrayList(); Set comments = new HashSet(); Map ms = t.getMacros(); - + createCategoryRegions(t); - + Iterator macroIter = ms.values().iterator(); while(macroIter.hasNext()) { Macro macro = (Macro)macroIter.next(); @@ -340,8 +344,8 @@ private void createFilePage(File file) { } } } - - + + te = t.getRootTreeNode(); if(te.getClass().getName().endsWith("MixedContent")) { Enumeration children = te.children(); @@ -359,7 +363,7 @@ private void createFilePage(File file) { } } } - + Collections.sort(macros, MACRO_COMPARATOR); List l; Iterator iter = categories.values().iterator(); @@ -369,11 +373,11 @@ private void createFilePage(File file) { l = (List)element; Collections.sort(l,MACRO_COMPARATOR); } - - - - - + + + + + SimpleHash root = new SimpleHash(); root.put("macros",macros); if(null!=globalComment) { @@ -392,22 +396,22 @@ private void createFilePage(File file) { e.printStackTrace(); } } - + /** * Starts the ftldoc generation. * */ public void run() { - + try { - + // init global collections allCategories = new TreeMap(); allMacros = new ArrayList(); fParsedFiles = new ArrayList(); - - + + TemplateLoader[] loaders = new TemplateLoader[fAllDirectories.size()+1]; // loader for ftldoc templates @@ -416,25 +420,25 @@ public void run() { } else { loaders[0] = new ClassTemplateLoader(this.getClass(), "/default"); } - - + + // add loader for every directory int i = 1; for (Iterator it = fAllDirectories.iterator(); it.hasNext(); i++) { loaders[i] = new FileTemplateLoader((File) it.next()); } - + TemplateLoader loader = new MultiTemplateLoader(loaders); cfg.setTemplateLoader(loader); - + // create template for file page - - + + // create file pages for(int n=0;n