libfalcon-engine1 0.9.6.9-git20120606-2 / usr / lib / falcon / apps / faldoc / faldoc.fal

#!/usr/bin/falcon
/*
   FALCON - Documentation tool

   FILE: faldoc.fal

   Autodocumentation tool - main file
   -------------------------------------------------------------------
   Author: Giancarlo Niccolai
   Begin: Thu, 10 Jan 2008 08:12:57 -0800

   -------------------------------------------------------------------
   (C) Copyright 2008: the FALCON developers (see list in AUTHORS file)

   See LICENSE file for licensing details.
*/

load compiler
load self.version
load self.config
load self.document

import from parser.faldoc.txt

resources: "resources/*"


//================================================
// Application class
//================================================

class Application
   version = "3.0"
   
   fdfile = nil
   errorCount = 0
   warnCount = 0

   config = nil

   document = nil

   //# file currently parsed
   currentFile = ""

   //# Txt parser used by many users.
   txtParser = parser.faldoc.txt.Parser()


   //# Application process
   function go()
      try
         self.processParams()
         self.banner()
         self.readConfig()
         self.processInput()
         self.processOutput()
         
      catch in e
         self.fatal( e.toString() )
      end
   end

   //=================================================================
   // Process steps
   //=================================================================
   
   function processParams()
      // get minimal parameters
      self.fdfile = args.len() == 0 ? "faldoc.fd" : args[0]
   end
   
   function banner()
      > i"faldoc - Falcon documentation tool."
      > i"Part of the Falcon Programming language."
      > i"Version ", version.name()
      > "----------------------------------------"
   end

   function readConfig()
      self.config = Config()
      if not self.config.read( self.fdfile )
         self.fatal( i"Errors in configuration" )
      end

      if not self.config.inputDirs
         self.fatal( i"Sorry, no input dirs" )
      end
   end

   function processInput()
      self.initDocument()
      
      cfg = self.config
      doc = self.document
      basedir = cfg.basedir
      
      for dir in cfg.inputDirs
         // open the directory
         drel = self.relativize( basedir, dir )
         try
            hdir = Directory( drel ).descend( {=>}, {fname =>
               for wildcard in cfg.inputWild
                  if strWildcardMatch( fname, wildcard )
                     doc.addFile( fname )
                  end
               end
               })
         catch IoError in err       
            raise "can't read directory \""+basedir + "/"+dir+"\" in input dirs."
         end
      end

      // parse extra files
      for extra in cfg.inputExtra
         p = Path(extra)
         if not p.fulloc.startsWith("/")
            doc.addFile( basedir + "/" + extra )
         else
            doc.addFile( extra )
         end
      end

      // ok, time to cleanup: resolve links
      doc.resolveLinks()

      // and check for undefined entities
      doc.checkUndefined()
   end

   
   function processOutput()
      self.info( "=" * 60 )
      
      // create the compiler
      compiler = Compiler()

      conf = self.config.cfile
      self.info( "Start processing output" )

      for mod in self.config.outMods
         try
            modData = compiler.loadByName( "self.output." + mod )
            faldoc_output = modData.get( "faldoc_output" )
            if not isCallable( faldoc_output )
               raise "module '"+ mod + "' doesn't define 'falcon_output' entry point"
            end

            // perform call
            faldoc_output( self.document, firstOf(conf.getCategory("Output."+mod+".*"),[=>]) )

            // unload the module
            modData.unload()

         catch IoError in error
            // signal an abnormal exit
            raise "Cannot find or load module (faldoc_output_)"+mod
         end
         // let any other error through to be catched by the main try.
      end
   end
   

   function initDocument()
      cfg = self.config
      
      doc = Document()
      doc.title = cfg.title
      doc.author = cfg.author
      doc.version = cfg.version

      self.document = doc
   end

   //=================================================================
   // Utilities
   //=================================================================

   //# function to generate a fatal error
   function fatal( error, line, file )      
      self.display( 0, "FATAL - " + error, line, file )
      exit(0)
   end

   //# function to generate an error
   function error( e, line, file )
      self.display( 1, "ERROR - " + e, line, file )
      self.errorCount++
   end

   //# function to generate a warning
   function warn( e, line, file )
      self.display( 2, "WARN - " + e, line, file )
      self.warnCount++
   end

   //# function to send an info
   function info( i, line, file )
      self.display( 3, i, line, file )
   end

   //# function to send an info
   function verbose( i, line, file )
      self.display( 4, i, line, file )
   end

   //# funciton to display an information message
   function display( level, msg, line, file )
      if level <= self.config.loglevel
         if file
            fmarker = file
         elif self.currentFile
            fmarker = self.currentFile
         else
            fmarker = ""
         end

         if line
            fmarker += ":" + line
         end
         > "faldoc: ", fmarker, " ", msg
      end
   end

   function result()
      if self.warnCount or self.errorCount
         self.info( "="*60 )

         self.info( i"Detected " + self.warnCount + " warnings." )
         
         if self.errorCount
            self.info( i"Terminating with " + self.errorCount + " errors." )
            return 1
         else
            self.info( i"== Done ==" )
         end
      else
         self.info( i"== Done ==" )
         return 0
      end
   end

   //# Eventually relativize a filename or directory name to basedir
   function relativize( basedir, dir )
      dpath = Path( dir )
      if dpath.fulloc.startsWith("/")
         return dir
      else
         return basedir + "/" + dir
      end
   end

   /*# Determine module name based on base directory and root module directories.
      @param file A full filename of a module, already relativized to basedir.
   */
   function calcModName( file )
      cfg = self.config
      basedir = cfg.basedir

      // find a base directory that may be the root of our module
      rootDir = self.findRootDir( basedir, cfg.moduleRoots, file ) 
      // no luck? try with input dirs
      if not rootDir: rootDir = self.findRootDir( basedir, cfg.inputDirs, file )

      if rootDir: file = file[rootDir.len()+1:]
      if file.endsWith( ".fal" ) or file.endsWith( ".ftd" )
         file = file[0:-4]
      end
      return file.replace("/",".")
   end

   function findRootDir( basedir, roots, file )
      for dir in roots
         dr = self.relativize( basedir, dir )
         if file.startsWith( dr )
            return dr
         end
      end
   end

   function copyResource( resName, dest )
      p = Path( vmModulePath() )
      loc = p.fulloc +"/resources/" + resName
      fileCopy( loc, dest + "/" + resName )
   end
   
end


//================================================
// Main code
//================================================

faldoc = Application()
faldoc.go()
return faldoc.result()


// Export the global faldoc entity
export faldoc

/* end of faldoc */