SlateGenerator2.au3

#cs
This is the main script

The script goal is to read .lua file, extract the documentation in comment blocks, and write .md files to be converted to html by Slate : https://github.com/lord/slate
It works in 5 steps :

First, it reads the .lua files one bt one, indentifying the comment blocks. for each comment block, it determines the kind of content the comment block describes (module, class/type or function),
find some usefull stuff (for exemple in the declaration...) and writes all of this info in the creatively named TreeHierarchy.csv, with this format :
@K=kind, @M=ParentModule, @N=Name, @P=Parent, @F=FileWhereTheCommentBlockIsLocated, @C=CarretPositionOfTheCommentBlock
The functions used to do this step are mostly found in Parser.au3

Then the second step is the longest : we sort the TreeHiearchy.csv, and put the result into TreeHierarchySorted.csv
The idea is to have the data in this order :
Module A
Class A (belongs to Module A)
Function A (belongs to Class A)
Function B (belongs to Class A)
Class B Class A (belongs to Module A)
Function C (belongs to Class B)
Function D (belongs to Class B)
Module B ...
The functions used to do this step are found in DataStorer.au3

Then, step 3 : We read each line of TreeHierarchySorted.csv, read the appropriate comment block in the .lua source files,
and write the appropriate Markdown documentation for it in a temporary folder
This is where the markdown documentation is actually written for the first time.
The functions used to do this step are found in Writer.au3

Step 4 ! We read the newly created Markdown files, trying to find hyperlinks/picture paths... and we replace them with the new ones.
We copy each processed file into it's final destination.
The functions used to do this step are mostly found in Parser.au3

And finally Step 5 : We add the new markdown files to Slate's index and delete temporary files and folder
#ce





#AutoIt3Wrapper_Change2CUI=y

#include <FileConstants.au3>
#include <StringConstants.au3>
#include <Array.au3>
#include <File.au3>

; Those are the arguments that need to be passed at the start
Global $SourceFolder = $CmdLine[1] ;"./Results"
Global $OutputFolder = $CmdLine[2] ;"@ScriptDir&"/source/index.html.md"

Global $Log = FileOpen(@ScriptDir & "\SlateGenerator2.log", 2)
Global $DataFile = FileOpen(@ScriptDir & "\TreeHierarchy.csv", 2)
Global $FunctionList = FileOpen(@ScriptDir & "\FuctionList.txt", 2)

#include "Parser.au3"
#include "DataStorer.au3"
#include "Writer.au3"


Func ExitCleanly()
	FileClose($DataFile)
	FileClose($FunctionList)
	FileWrite($Log, "SlateGenerator2 exited cleanly")
	FileClose($Log)
EndFunc


; Small function to determine if a comment block is describing a module, a type or a function
Func IdentifyBlock($Block, $Declaration)
	Local $Kind
	Local $KindFunction

	$Kind = ParseForOneTag($Block, "@module")
	If $Kind Then
		Return "module"
	EndIf

	$Kind = ParseForOneTag($Block, "@type")
	If $Kind Then
		Return "type"
	EndIf


	$KindFunction = ParseFunctionName($Block, $Declaration)
	If $KindFunction[0] Then
		Return "function"
	EndIf

	Return ""
EndFunc




; -----------------------------------------------------------------
; Main
; -----------------------------------------------------------------

; Step 1 !
; -----------------------------------------------------------------

Local $SourceList = _FileListToArrayRec($SourceFolder, "*", $FLTAR_FILES, $FLTAR_RECUR, $FLTAR_NOSORT, $FLTAR_FULLPATH)
Local $CurrentFile
Local $CarretPos = 0
Local $CommentBlock
Local $CommentKind
Local $CommentInfo[2]
Local $CurrentModule

ConsoleWrite("1. Parsing Source Files... ")
FileWrite($Log, @CRLF&@CRLF&@TAB&"INFO : Building Hierarchy" & @CRLF)
For $i=1 To $SourceList[0] ; for each .lua source file


	FileWrite($Log, "DEBUG : "&$SourceList[$i])

	; let's read the next .lua source file
	$CurrentFile = FileOpen($SourceList[$i], $FO_READ)
	FileWrite($Log, @CRLF&"INFO : Reading File "&$SourceList[$i] & @CRLF)
	While True ; for each comment block in the current .lua source file

		; We read the next comment block. If we could not, it's probably eof, time to open the next .lua file
		$CommentBlock = ReadNextBlock($CurrentFile, $CarretPos)
		If Not $CommentBlock[1] Then
			ExitLoop
		EndIf

		$CarretPos = $CommentBlock[0]
		$CommentKind = IdentifyBlock($CommentBlock[1], $CommentBlock[2])
		; Depending on the kind of comment block it is, we write the appropriate line in TreeHierarchy.csv
		Switch $CommentKind
			Case "function"
				$CommentInfo = ParseFunctionName($CommentBlock[1], $CommentBlock[2])
				AddNode("function", $CurrentModule, $CommentInfo[0], $CommentInfo[1], $SourceList[$i], $CommentBlock[3])
				FileWrite($Log, "INFO : Added function "&$CommentInfo[0]&" to hierarchy" & @CRLF)
			Case "type"
				$CommentInfo[0] = ParseForOneTag($CommentBlock[1], "@type")
				$CommentInfo[1] = ParseForOneTag($CommentBlock[1], "@extends")
				$CommentInfo[1] = StringRegExpReplace($CommentInfo[1], "(.*#)", "")
				AddNode("type", $CurrentModule, $CommentInfo[0], $CommentInfo[1], $SourceList[$i], $CommentBlock[3])
			FileWrite($Log, "INFO : Added type "&$CommentInfo[0]&" to hierarchy" & @CRLF)
			Case "module"
				$CurrentModule = ParseForOneTag($CommentBlock[1], "@module")
				AddNode("module", "", $CurrentModule, "", $SourceList[$i], $CommentBlock[3])
				FileWrite($Log, "INFO : Added module "&$CurrentModule&" to hierarchy" & @CRLF)
		EndSwitch

	WEnd
	$CarretPos = 0
	FileClose($CurrentFile)

Next
ConsoleWrite("Done"&@CRLF)


; Step 2 !
; -----------------------------------------------------------------
ConsoleWrite("2. Sorting Hierarchy")
FileWrite($Log, @CRLF&@CRLF&@TAB&"INFO : Sorting Hierarchy" & @CRLF)
; The magic happens in DataStorer.au3
DataSort()
ConsoleWrite("Done"&@CRLF)



; Step 3 !
; -----------------------------------------------------------------
ConsoleWrite("3. Writing Markdown Documentation")
FileWrite($Log, @CRLF&@CRLF&@TAB&"INFO : Writing Markdown Documentation" & @CRLF)

Local $CurrentOutput
Local $CurrentFolder
Local $RegexResult
Local $Line
Local $CarretPos = 0
Local $Results
Local $Output
Local $Declaration

FileSetPos($DataFile, 0, $FILE_BEGIN)
While True ; For each line in TreeHierarchySorted.csv

	; read the next line until eof
	FileSetPos($DataFile, $CarretPos, $FILE_BEGIN)
	$Line = FileReadLine($DataFile)
	If @error Then ; eof
		ExitLoop
	Endif

	$CarretPos = FileGetPos($DataFile)

	; find the file/position of the next comment block referenced in the line
	$RegexResult = StringRegExp($Line, "\@F=(.+?),", $STR_REGEXPARRAYMATCH)
	$CurrentFile = FileOpen($RegexResult[0], $FO_READ)

	$RegexResult = StringRegExp($Line, "\@C=(.+?),", $STR_REGEXPARRAYMATCH)
	$DataPos = $RegexResult[0]

	; get the comment block itself
	$Results = ReadNextBlock($CurrentFile, $DataPos)
	$Block = $Results[1]
	$Declaration = $Results[2]


	; choose the right function to write mardown depending on the type of comment block
	$RegexResult = StringRegExp($Line, "\@K=(.+?),", $STR_REGEXPARRAYMATCH)

	If $RegexResult[0] == "module" Then
		ConsoleWrite(".")
		; We need the name of the folder containing this particular source file
		$RegexResult = StringRegExp($Line, "\@F=(.+?),", $STR_REGEXPARRAYMATCH)
		$RegexResult = StringRegExp($RegexResult[0], "\\(.*)\\.*\.lua", $STR_REGEXPARRAYMATCH)
		If @error Then
			$CurrentFolder = ""
		Else
			$CurrentFolder = $RegexResult[0]
		Endif

		; Now we can write the markdown for this module
		$CurrentOutput = WriteModule($Block, $CurrentFolder)
	EndIf

	If $RegexResult[0] == "type" Then
		; We need the name of the Module containing the type
		$RegexResult = StringRegExp($Line, "\@M=(.+?),", $STR_REGEXPARRAYMATCH)

		; Now we can write the markdown for this type
		WriteType($Block, $RegexResult[0], $CurrentOutput)
	EndIf

	If $RegexResult[0] == "function" Then
		; We can write the markdown for this function
		WriteFunction($Block, $Declaration, $CurrentOutput)
	EndIf

	FileClose($CurrentFile)
Wend
ConsoleWrite("Done"&@CRLF)


; Step 4 !
; -----------------------------------------------------------------
ConsoleWrite("4. Processing Hyperlinks...")
FileWrite($Log, @CRLF&@CRLF&@TAB&"INFO : Processing Hyperlinks" & @CRLF)
Local $i=1
Local $TempFilesArray = _FileListToArray(@ScriptDir & "/TEMP")
Local $CurrentFile
Local $FinalFile
While $i <= $TempFilesArray[0] ; For each markdown file in the temporary folder

	;read the file
	$CurrentFile = FileOpen(@ScriptDir & "/TEMP/" & $TempFilesArray[$i], 0)
	; The magic happens in Parser.au3
	$FinalString = ReplaceHyperlinks($CurrentFile)

	; copy the result to the final file location
	$FinalFile = FileOpen($OutputFolder & "/includes/" & $TempFilesArray[$i], 2)
	FileWrite($FinalFile, $FinalString)

	FileClose($FinalFile)
	FileClose($CurrentFile)
	$i += 1
WEnd
ConsoleWrite("Done"&@CRLF)


; Step 5 !
; -----------------------------------------------------------------
ConsoleWrite("5. Adding new documentation to index...")
FileWrite($Log, @CRLF&@CRLF&@TAB&"INFO : Adding new documentation to index" & @CRLF)

; Now this is a bit annoying : there is no way to insert a line in a document.
; So we need to read the first half of it, read the second half, and the wipe the whole document
; This way, in the new doc, we can write the first half, what we wanted to insert, and then the second half !

; Let's store the index file in $IndexString
Local $IndexFile = $OutputFolder&"/index.html.md"
Local $IndexFileHandle = FileOpen($IndexFile, 0)
Local $IndexString = FileRead($IndexFileHandle)
$IndexString = StringRegExpReplace($IndexString, "-\h[A-Z][a-z]+\.[A-Z][a-z]+\s", "")

; Now we slpit it into and store the results in $BeforeString and $AfterString
Local $SearchPos = StringInStr($IndexString, "search:")
local $BeforeString = StringTrimRight($IndexString, StringLen($IndexString) - $SearchPos + 5)
local $AfterString = StringTrimLeft($IndexString, $SearchPos - 1)

; reopening the index file wiping everything
FileClose($IndexFileHandle)
$IndexFileHandle = FileOpen($IndexFile, 2)

; write the first half
FileWrite($IndexFileHandle, $BeforeString)
Local $IncludePos = StringInStr($IndexString, "includes:")
FileSetPos($IndexFileHandle, $IncludePos + 10, $FILE_BEGIN)

; add the new markdown files to the index
$i = 1
While $i <= $TempFilesArray[0]
	FileWrite($Log, StringTrimRight($TempFilesArray[$i], 3)&@CRLF)

	FileWrite($IndexFileHandle, "  - "&StringTrimRight($TempFilesArray[$i], 3)&@CRLF)
	$i+=1
WEnd
FileWrite($IndexFileHandle, @CRLF)

; append the second half of the file
FileWrite($IndexFileHandle, $AfterString)
FileClose($IndexFileHandle)
ConsoleWrite("Done"&@CRLF)

; WE ARE DONE !
ExitCleanly()