--@Version v. 1.1.0
--@LastUpdate: 1/11/3
--@Author: Luke Wigley

--@DESCRIPTION
-- Utility script for creating script documentation. 'Script documentation' is created using the following 
-- very basic rules which generate a list of 'announcements' (version, history, general description etc) 
-- and a list of 'public methods'
--
--(1) comments that begin with a "@" are assumed to be "announcements" (headings for special comments). 
-- Typically these headings would include @Version, @Author etc. The text after the announcement (on the same line)
-- is paired to that announcement. If there is no text following the announcement, the the following lines are checked  
-- for comments. Comments immediately after an announcement are joined together (this assumes that the 
-- comments have 'hard-wraps' which will be removed when formatted into HTML). A comment line that begins with more 
-- than two hyphens (eg "---") is ignored.
-- 
--
--(2) All method names are treated as public unless they begin with an underscore. Any comments immediately after the
-- method name are assumed to be method descriptions. Any comments immediately after the description (or methodname)
-- that begin with an asterix character are assumed to be 'parameter descriptions'
-- 

--@HISTORY
-- v.1.1.0: Added the GetVersion function

on XInterface (scriptthing) 
  -- Return a description of the method or functions of the
  -- specified script thing (instance, script object, script
  -- name or member reference)
  return script("XInterfaceLib").__InterfaceBuilder__GetInfo(scriptthing)
end

on GetVersion(scriptthing)
  -- Return a version string (based an on the assumption that the version
  -- will be a comment in the form --@version <version number>
  return script("XInterfaceLib").__InterfaceBuilder__GetVersion(scriptthing)
end

























--------------------------------------------------------------------------------
-- PRIVATE
-- named to prevent scope/colllisions
--------------------------------------------------------------------------------

on __InterfaceBuilder__GetVersion(me, scriptthing)
  case (scriptthing.ilk) of
    #instance: 
      scriptName = me.__InterfaceBuilder__GetScriptName(scriptthing.script)
    #script: 
      scriptName = me.__InterfaceBuilder__GetScriptName(scriptthing)
    #string: 
      if script(scriptthing).ilk = #script then
        scriptName = scriptthing
      end if
    #member:
      if script(scriptthing.name).ilk = #script then
        scriptName = scriptthing.name
      end if
  end case
  -- check for error with parameter parse
  if voidP(scriptName) then return "parameter error - don't know to handle a '"& scriptthing.ilk & "'"
  
  -- now get the script text
  str = member(scriptName).scriptText
  mx = str.line.count 
  scanMode = false
  
  repeat with i = 1 to mx
    
    thisLine= me.__InterfaceBuilder__Trim(str.line[i])
    if (thisLine starts "--@" OR thisLine starts "-- @") then
      -- $$ Announcement Start
      thisLine = me.__InterfaceBuilder__Trim(thisLine, [SPACE,TAB,"-", "@"] )
      tag = thisLine.word[1]
      if tag = "version" then
        return me.__InterfaceBuilder__Trim(thisLine.char[8..thisLine.length], [SPACE,TAB,"-", ":","v", "V", "."] )
      end if
      
    end if
    
    
  end repeat
  
end



on __InterfaceBuilder__GetInfo (me,  scriptthing)
  
  case (scriptthing.ilk) of
    #instance: 
      scriptName = me.__InterfaceBuilder__GetScriptName(scriptthing.script)
    #script: 
      scriptName = me.__InterfaceBuilder__GetScriptName(scriptthing)
    #string: 
      if script(scriptthing).ilk = #script then
        scriptName = scriptthing
      end if
    #member:
      if script(scriptthing.name).ilk = #script then
        scriptName = scriptthing.name
      end if
  end case
  -- check for error with parameter parse
  if voidP(scriptName) then return "parameter error - don't know to handle a '"& scriptthing.ilk & "'"
  
  -- now get the script text
  str = member(scriptName).scriptText
  
  -- look for comments immediately following a function name
  mx = str.line.count 
  scanMode = false
  
  repeat with i = 1 to mx
    
    thisLine= me.__InterfaceBuilder__Trim(str.line[i])
    if thisLine starts "---" then next repeat
    
    if thisLine starts "on" then
      -- $$ Method Start
      delete word 1 of thisLine
      methodName = thisLine.word[1]
      if methodName starts "_" then 
        -- assume it is private and exclude
      else
        thisLine = me.__InterfaceBuilder__Trim(thisLine)
        out = out & return & thisLine & " -- " 
        scanMode = #methodBlock 
      end if
      
      
    else if (thisLine starts "--@" OR thisLine starts "-- @") then
      -- $$ Announcement Start
      thisLine = me.__InterfaceBuilder__Trim(thisLine, [SPACE,TAB,"-", "@"] )
      header = header & thisLine & return
      scanMode = #announcementBlock
      
    else 
      
      case (scanMode) of 
          
        #methodBlock: 
          
          if thisLine starts "--" then
            thisLine = me.__InterfaceBuilder__Trim(thisLine, [SPACE,TAB,"-"] )
            out = out  & " " & thisLine
          else
            -- finished getting first comments
            scanMode = false
          end if
          
        #announcementBlock: 
          
          if thisLine starts "--" then
            thisLine = me.__InterfaceBuilder__Trim(thisLine, [SPACE,TAB,"-"] )
            header = header & " " & thisLine
          else
            -- finished getting first comments
            scanMode = false
          end if
          
        otherwise
          
          scanMode = false
      end case
    end if
  end repeat
  decoration = return & "------------------------------------------------"& return
  out = decoration & "Script " & scriptName & return & header & decoration  & out
  return out
end

-- Supporting / Private methods

on __InterfaceBuilder__GetScriptName (me, aScriptObj)
  the itemDelimiter = QUOTE
  scriptName = string(aScriptObj).item[2]
  return scriptName
end

on __InterfaceBuilder__Trim (me, aString, whitespace)
  if voidP(whitespace) then whiteSpace = [SPACE,TAB]
  if ListP(aString) then 
    repeat with i = 1 to aString.count
      aString[i] = me.__InterfaceBuilder__Trim(aString[i], whitespace)
    end repeat
  else
    if aString.ilk <> #string then aString = string(aString)
    -- Trim left
    repeat while whitespace.getPos(aString.char[1])
      delete char 1 of aString
    end repeat
    -- Trim right
    repeat while whitespace.getPos(the last char of aString)
      delete the last char of aString
    end repeat
    return aString
  end if
end