script "revDocsParser"

/*

Tests the features of the inline documentation parser & display

Synonyms: none

Associations: stack, revIdeDocsLibrary

pArrayParam (array): An array parameter

{ key : "key1"

value: "value1"

key : "key2"

value (array) : A sub-array

{ key (integer) : an integer key

value (string) : the description of the value at this index }

optional key : an optional key

value (string): the value associated with this optional key }

pEnumParam (enum): An enum parameter

-"option 1" : description of option 1

- option 2 : description of option 2

- option 3 : description of option 3

pOptionalParam (optional integer): An integer parameter

pParam: A param afterward with no space

The result: Sets the result to empty

Returns (string): Description of string

Example:

// Some inline docs for myHandler...

on myHandler pParam

// do something

end myHandler

// Some inline docs for myOtherHandler...

on myOtherHandler

// do something other

end myOtherHandler

Description:

Should have examples of *every* type of docs element in order to **make sure** they display correctly.

Can have some *markdown* in it:

* List

* Of

* Things

References:

myFavourite.command,ANOther.function

Tags: documentation, meta

*/

function revDocsInlineDocsParsingTest pArrayParam, pEnumParam, pOptionalParam, pParam

return empty

end revDocsInlineDocsParsingTest

function revDocsGetBuiltinModuleList pModuleInterfacePath, pRepoPath

local tModulePath, tEngine, tScript, tListA

put pModuleInterfacePath into tModulePath

put pRepoPath & slash & "engine" & slash & "src" into tEngine

put pRepoPath & slash & "libscript" & slash & "src" into tScript

local tInstalled

set the defaultFolder to tModulePath

put the files into tInstalled

filter tInstalled with "*.lci"

local tSourcePaths

put tScript into tSourcePaths[1]

put tEngine into tSourcePaths[2]

local tCount

put 1 into tCount

set the itemdelimiter to "."

local tFiles

repeat for each element tElement in tSourcePaths

set the defaultfolder to tElement

local tDocsA

put the files into tFiles

filter tFiles with regex pattern ".*(\.(mlc|lcb))+"

# Check to see if the corresponding interface file exists so that we

# don't add anything to the dictionary that isn't actually there.

repeat for each line tFile in tFiles

local tInterfaceFile

put "com.livecode." & tFile into tInterfaceFile

put "lci" into item -1 of tInterfaceFile

if replaceText(tInterfaceFile, "-", "") is not among the lines of tInstalled then next repeat

put true into tListA[tElement & slash & tFile]

end repeat

end repeat

set the defaultfolder to (pRepoPath & slash & "docs" & slash & "builder")

put the files into tFiles

filter tFiles with "*.lcdoc"

repeat for each line tFile in tFiles

put true into tListA[pRepoPath & slash & "docs" & slash & "builder" & slash & tFile]

end repeat

return the keys of tListA

end revDocsGetBuiltinModuleList

function revDocsGenerateDocsFilesFromBuiltIn pModuleInterfacePath, pRepoPath

local tModulePath, tEngine, tScript

put pModuleInterfacePath into tModulePath

put pRepoPath & slash & "engine" & slash & "src" into tEngine

put pRepoPath & slash & "libscript" & slash & "src" into tScript

local tInstalled

set the defaultFolder to tModulePath

put the files into tInstalled

filter tInstalled with "*.lci"

local tSourcePaths

put tScript into tSourcePaths[1]

put tEngine into tSourcePaths[2]

local tCount

put 1 into tCount

set the itemdelimiter to "."

local tFiles

repeat for each element tElement in tSourcePaths

set the defaultfolder to tElement

local tDocsA

put the files into tFiles

filter tFiles with regex pattern ".*(\.(mlc|lcb))+"

# Check to see if the corresponding interface file exists so that we

# don't add anything to the dictionary that isn't actually there.

repeat for each line tFile in tFiles

local tInterfaceFile

put "com.livecode." & tFile into tInterfaceFile

put "lci" into item -1 of tInterfaceFile

if replaceText(tInterfaceFile, "-", "") is not among the lines of tInstalled then next repeat

get revDocsGenerateDocsFileFromModularFile(tFile)

if it is not empty then

put it into tDocsA[tCount]

add 1 to tCount

end if

end repeat

end repeat

set the defaultfolder to (pRepoPath & slash & "docs" & slash & "builder")

put the files into tFiles

filter tFiles with "*.lcdoc"

repeat for each line tFile in tFiles

get url("file:" & tFile)

if it is not empty then

put it into tDocsA[tCount]

add 1 to tCount

end if

end repeat

return tDocsA

end revDocsGenerateDocsFilesFromBuiltIn

/*

Summary: Formats a libraries array as JSON.

pLibrariesA (array): A libraries array is a numerically keyed array of library arrays.

Description:

Each element of the numerically keyed <pLibrariesA> is a library array.

The latter consists of three keys, "name", "author", and "doc". The first two of these are strings.

The third is an array. The "doc" subarray is numerically keyed.

Each element of it represents the documentation for a handler contained in the library.

There are a number of ways of creating a library array:

* <revDocsParseDirectoryToLibraryArray> creates a library array from all of the (non-inline) docs entries of a given type in a directory

* <revDocsParseScriptToLibraryArray> creates a library array from the inline docs of a script

* <revDocsParseDictionaryToLibraryArray> creates the dictionary library array

*/

function revDocsFormatLibrariesArrayAsJSON pLibrariesA

local tJSON

repeat for each element tLibraryA in pLibrariesA

get revDocsFormatLibraryArrayAsJSON(tLibraryA)

if it is not empty then

put it & comma after tJSON

end if

end repeat

delete the last char of tJSON

return tJSON

end revDocsFormatLibrariesArrayAsJSON

/*

Summary: Create a library array with all the docs data from the specified directory

Parameters:

pLibraryName (string): The name of the library

pAuthor(string): The author of the library

pRootDir(string): The root directory to search for files

pType (enum): The type of docs to parse

- "modular": This will take any inline docs in .lcb files as well as all standard .lcdoc files in the directory

- "script": This will take any inline docs in .livecode files as well as all standard .lcdoc files in the directory

- "dictionary": This will take the standard .lcdoc files in the directory and parse as dicitonary entries

Returns(array): An array consisting of all the parsed docs data

{ key: "name"

value(string): the name of the library

key: "author"

value(string): the author of the library

key: "doc"

value(array): an array, with one key per handler or syntax element

{ key(string): the name of the handler or syntax element

value(array): an array of all the docs elements for this handler or piece of syntax

}

}

*/

function revDocsParseDirectoryToLibraryArray pLibraryName, pAuthor, pRootDir, pType, pRecursive

local tLibraryA

if there is a folder pRootDir then

put pLibraryName into tLibraryA["name"]

put pAuthor into tLibraryA["author"]

put pType into tLibraryA["type"]

if pType is "dictionary" then

put revDocsParseDictionaryToLibraryArray(pRootDir) into tLibraryA["doc"]

else

put __revDocsParseDirectoryToLibraryArray(pType, pRootDir, pRecursive) into tLibraryA["doc"]

end if

end if

if tLibraryA["doc"] is not empty then

return tLibraryA

end if

return empty

end revDocsParseDirectoryToLibraryArray

/*

Summary : Creates a library array from the given script

pObjName: The name of the object whose script is being parsed

pText: The script to be parsed

pAuthor: The author name

*/

function revDocsParseScriptToLibraryArray pObjName, pText, pAuthor

local tLibraryA

put pObjName into tLibraryA["name"]

put pAuthor into tLibraryA["author"]

local tBlocksA, tParsedA

put revDocsParseScriptDocs(pText) into tBlocksA

put revDocsParseDocBlocks(tBlocksA) into tParsedA

local tCount

put 1 into tCount

repeat for each key tEntry in tParsedA

put tParsedA[tEntry] into tLibraryA["doc"][tCount]

put tEntry into tLibraryA["doc"][tCount]["name"]

add 1 to tCount

end repeat

return tLibraryA

end revDocsParseScriptToLibraryArray

/*

Summary: Parses the current directory into a library array.

pRootDir (string): The path to the root directory of the dictionary

*/

function revDocsParseDictionaryToLibraryArray pRootDir

if there is not a folder pRootDir then

return empty

end if

# Get the list of canonical glossary entries

local tGlossaryA

put revDocsCollectGlossarySynonyms(pRootDir) into tGlossaryA

local tDictionaryRoot, tGlossaryRoot

put pRootDir & slash & "dictionary" into tDictionaryRoot

put pRootDir & slash & "glossary" into tGlossaryRoot

local tCount

put 1 into tCount

local tText, tLibraryA, tParsedA

repeat for each item tRoot in (tDictionaryRoot & "," & tGlossaryRoot)

set the defaultfolder to tRoot

repeat for each line tLine in the folders

if tLine is ".." then next repeat

set the defaultfolder to tRoot & slash & tLine

get the files

filter it with "*.lcdoc"

repeat for each line tFile in it

wait 0 with messages

put textDecode(url ("binfile:" & tRoot & slash & tLine & slash & tFile), "utf-8") into tText

put revDocsParseDocText(tText, tRoot & slash & tLine & slash & tFile) into tParsedA

put tParsedA["doc"][1] into tLibraryA[tCount]

add 1 to tCount

end repeat

end repeat

end repeat

return tLibraryA

end revDocsParseDictionaryToLibraryArray

/*

Summary: Takes a .lcdoc file and formats it as a JSON array.

*/

function revDocsFormatAPIAsJSON pLibraryName, pAuthor, pAPIFile

# Get the data

local tText, tData

put url ("binfile:" & pAPIFile) into tData

put textDecode(tData, "utf-8") into tText

return revDocsFormatDocTextAsJSON(pAPIFile, tText, pLibraryName, pAuthor)

end revDocsFormatAPIAsJSON

/*

Summary: Takes a .lcdoc file and parses it into a library array.

*/

function revDocsParseFileToArray pFile, pType, @xCount, @xLibraryA

# Get the data

local tText, tData

put url ("binfile:" & pFile) into tData

put textDecode(tData, "utf-8") into tText

return revDocsParseFileContentsToArray(pFile, tText, pType, xCount, xLibraryA)

end revDocsParseFileToArray

function revDocsParseFileContentsToArray pFile, pText, pType, @xCount, @xLibraryA

# Extract and parse the comment blocks

local tParsedA

switch pType

case "modular"

put revDocsParseDocText(pText, pFile) into tParsedA

break

case "script"

local tBlocksA

put revDocsParseScriptDocs(pText) into tBlocksA

put revDocsParseDocBlocks(tBlocksA, pFIle) into tParsedA

break

end switch

# Add to the library array

repeat for each key tEntry in tParsedA

put tParsedA[tEntry] into xLibraryA[xCount]

put tEntry into xLibraryA[xCount]["name"]

add 1 to xCount

end repeat

return empty

end revDocsParseFileContentsToArray

function revDocsGenerateDocsFilesFromModularDirectory pDir

set the defaultfolder to pDir

local tFiles

put the files into tFiles

filter tFiles with regex pattern ".*(\.(mlc|lcb))+"

local tDocsA, tCount

put 1 into tCount

repeat for each line tFile in tFiles

get revDocsGenerateDocsFileFromModularFile(tFile)

if it is not empty then

put it into tDocsA[tCount]

add 1 to tCount

end if

end repeat

return tDocsA

end revDocsGenerateDocsFilesFromModularDirectory

/*

Summary: Extracts the inline docs from a .lcb file

pFile: The path to the .lcb file to extract docs from

Returns (string): A string consisting of all the docs for the syntax and handlers present in the .lcb file

Description:

<revDocsGenerateDocsFileFromModularFile> is used when packaging a widget to create its API documentation.

It generates the Library and Type elements from the declaration in the <pFile> (either widget or library), and extracts

the comment block that precedes any initial declaration for use as the library-level Description element.

It then extracts the comment blocks that precede syntax and handler definitions in <pFile>, and generates the

Name, Type, Syntax, and Associated elements for each entry, as well as the parameter types.

Tags: Package building

*/

function revDocsGenerateDocsFileFromModularFile pFile

return revDocsGenerateDocsFileFromModular(url ("file:" & pFile), pFile)

end revDocsGenerateDocsFileFromModularFile

/*

Convert inline docs to the standard format (that can be parsed without code blocks)

*/

function revDocsGenerateDocsFileFromModular pText, pFilename

local tEntryType

put empty into tEntryType

local tInComment, tInEntry, tEntryEnded

put false into tInComment

put false into tInEntry

local tFirstWord, tEntryData

local tComment, tData

local tHandlerData, tPhraseData

local tLibraryData, tAPIData

repeat for each line tLine in pText

# Check to see if this is the start of a handler / syntax or a block of comments

put word 1 of tLine into tFirstWord

# By default, the entry doesn't end on this line

put false into tEntryEnded

# If we are neither in a comment block or in handler / syntax then

if not tInComment and not tInEntry then

# In almost all cases, we will be in a new entry

put true into tInEntry

switch tFirstWord

case "module"

case "library"

put "library" into tEntryData["type"]

put word 2 to -1 of tLine into tEntryData["name"]

put true into tEntryEnded

put true into tEntryData["need_docs"]

break

case "widget"

put "widget" into tEntryData["type"]

put word 2 to -1 of tLine into tEntryData["name"]

put true into tEntryEnded

put true into tEntryData["need_docs"]

break

case "handler"

put "handler" into tEntryData["type"]

# Handler is private by default, so don't document

put true into tEntryData["private"]

break

case "private"

if word 2 of tLine is "handler" then

# Don't document private handler

put true into tEntryData["private"]

# eat the word 'private'

put word 2 to -1 of tLine into tLine

else

put false into tInEntry

end if

break

case "public"

if word 2 of tLine is "handler" then

put "handler" into tEntryData["type"]

# eat the word 'public'

put word 2 to -1 of tLine into tLine

put token 2 of tLine into tEntryData["name"]

put true into tEntryData["need_docs"]

else

put true into tEntryData["private"]

if word 2 of tLine is "foreign" then

if word 3 of tLine is "handler" then

put "handler" into tEntryData["type"]

else if word 3 of tLine is "type" then

put "type" into tEntryData["type"]

end if

# eat the words 'public foreign'

put word 3 to -1 of tLine into tLine

put true into tEntryEnded

end if

end if

break

case "syntax"

put word 2 of tLine into tEntryData["name"]

if word 4 of tLine is "phrase" then

put "phrase" into tEntryData["type"]

else

put "syntax" into tEntryData["type"]

put true into tEntryData["need_docs"]

end if

break

case "property"

put word 2 of tLine into tEntryData["name"]

put "property" into tEntryData["type"]

# Properties are one-liners

put true into tEntryEnded

put true into tEntryData["need_docs"]

break

default

# This is not a new entry

put false into tInEntry

# Check if this is a new comment block

if tFirstWord begins with "/*" then

# Discard any previous comments

put empty into tComment

local tCommentOffset

put true into tInComment

put offset("/*", tLine) into tCommentOffset

put char tCommentOffset + 2 to -1 of tLine into tLine

# If there's nothing else on this line, don't add it.

if word 1 of tLine is empty then next repeat

end if

break

end switch

end if

# If we're in comments check to see if this is the end of a block of comments

if tInComment then

if word -1 of tLine ends with "*/" then

put false into tInComment

put offset("*/", tLine) into tCommentOffset

put char 1 to tCommentOffset - 1 of tLine into tLine

# If there's nothing else on this line, don't add it.

if word 1 of tLine is empty then

next repeat

end if

else if tComment is empty and tFirstWord is empty then

next repeat

end if

put tLine & return after tComment

next repeat

end if

# If we are in an entry, add the line to the current data

if tInEntry then

# ignore empty lines

if tFirstWord is empty then

next repeat

else if tFirstWord is "end" then

put true into tEntryEnded

end if

put tLine & return after tData

end if

# If the entry is ended, convert all the collected data to a structured array

if tEntryEnded then

# Extract data from the syntax / handler if comments are not empty

if tComment is not empty then

switch tEntryData["type"]

case "library"

case "widget"

put tComment into tEntryData["comments"]

put tEntryData into tLibraryData

break

case "handler"

revDocsParseHandler line 1 of tData, tHandlerData

revDocsUpdateDocBlocks true, "handler", line 1 of tData, tComment, tAPIData

break

case "type"

break

case "phrase"

put tData into tPhraseData[word 2 of tData]

break

case "syntax"

revDocsUpdateModularSyntaxDocBlocks tData, tComment, tHandlerData, tPhraseData, tAPIData

break

case "property"

revDocsUpdateDocBlocksForProperty tData, tComment, tAPIData

break

end switch

else

if tEntryData["need_docs"] then

logError "Required documentation not found for" && tEntryData["type"] && tEntryData["name"], pFilename

end if

end if

put empty into tEntryData

put empty into tComment

put empty into tData

put false into tInEntry

end if

end repeat

# Allow inline module description as valid docs

if tAPIData is empty then

logWarning "No handlers documented", pFilename

end if

if tLibraryData["name"] is empty then

logError "No extension name found", pFilename

end if

local tOutput

put revDocsFormatInlineComments(tLibraryData, true) into tOutput

if tOutput is empty then

logWarning "Invalid library-level docs", pFilename

end if

repeat for each key tKey in tAPIData

local tFormatted

put revDocsFormatInlineComments(tAPIData[tKey], false) into tFormatted

if tFormatted is empty then

logWarning "No docs for element" && tKey, pFilename

else

put tFormatted & return & return after tOutput

end if

end repeat

return tOutput

end revDocsGenerateDocsFileFromModular

##################################################

#

# PARSING UTILITIES

#

##################################################

private command log pOutput

write pOutput & return to stdout

end log

private command logError pError, pFilename

log pFilename & ":" && "error:" && pError

end logError

private command logWarning pWarning, pFilename

log pFilename & ":" && "warning:" && pWarning

end logWarning

private function extensionsFromType pType

switch pType

case "module"

return ".*\.(lcb|lcdoc)"

case "script"

return ".*\.(livecode|lcdoc)"

case "dictionary"

return ".*\.lcdoc"

end switch

end extensionsFromType

private function __revDocsParseDirectoryToLibraryArray pType, pRootDir, pRecursive

if there is not a folder pRootDir then

return empty

end if

local tFiles, tExtensionRegex

put extensionsFromType(pType) into tExtensionRegex

set the defaultfolder to pRootDir

put the files into tFiles

filter tFiles with regex pattern tExtensionRegex

local tCount

put 1 into tCount

local tLibraryA

if tFiles is not empty then

repeat for each line tFile in tFiles

revDocsParseFileToArray(tFile, pType, tCount, tLibraryA)

end repeat

end if

if pRecursive then

local tSubDirA

repeat for each line tLine in the folders

if tLine is ".." then

next repeat

end if

put __revDocsParseDirectoryToLibraryArray(pType, pRootDir & slash & tLine, pRecursive) into tSubDirA

repeat for each key tEntry in tSubDirA

put tSubDirA[tEntry] into tLibraryA[tCount]

add 1 to tCount

end repeat

end repeat

end if

return tLibraryA

end __revDocsParseDirectoryToLibraryArray

function revDocsFormatInlineComments pDataA, pIsLibrary

local tComment

if pIsLibrary then

put "Description:" & return & pDataA["comments"] after tComment

else

put pDataA["comments"] into tComment

end if

local tElementsA

put revDocsExtractElements(tComment) into tElementsA

local tEntriesA

put revDocsGroupElements(tElementsA) into tEntriesA

# If tEntries is empty, there was an error (docs empty, or no Name element)

if tEntriesA is empty then

return empty

end if

local tEntryA, tElementA, tElement

local tHasA

local tParamsFound

put false into tParamsFound

local tDocData

local tStart, tEnd

put 1 into tStart

put the number of elements in tEntriesA into tEnd

if tEntriesA[0] is not empty then

subtract 1 from tStart

subtract 1 from tEnd

end if

local tName, tType, tSyntax, tEntryDoc

repeat with x = tStart to tEnd

put empty into tHasA

put empty into tEntryDoc

put tEntriesA[x] into tEntryA

repeat with y = 1 to the number of elements in tEntryA["elements"]

put tEntryA["elements"][y] into tElementA

put tElementA["name"] into tElement

put true into tHasA[tElement]

if tElement is "Name" then

put tElementA["content"] into tName

next repeat

else if tElement is "Type" then

put tElementA["content"] into tType

next repeat

else if tElement is "Syntax" then

put tElementA["content"] into tSyntax[the number of elements of tSyntax + 1]

next repeat

end if

if tElement is "References" then

repeat for each element tPhrase in pDataA["phrases"]

put comma & tPhrase & "(phrase)" after tElementA["content"]

end repeat

end if

if tElement is "output" then

put "Returns" into tElementA["name"]

end if

if tElementA["name"] is "Returns" then

if tElementA["type"] is empty then

get pDataA["variants"][1]["return value"]["type"]

if it is not empty then

put it into tElementA["type"]

end if

end if

else if tElement is "The result" then

if tElementA["type"] is empty then

get pDataA["variants"][1]["the result"]["type"]

if it is not empty then

put it into tElementA["type"]

end if

end if

else

repeat for each element tVariant in pDataA["variants"]

repeat for each element tParam in tVariant

if tParam["name"] is tElement then

if not tParamsFound then

put "Parameters:" & return after tEntryDoc

put true into tParamsFound

end if

if tElementA["type"] is empty then

# add the param details if they were not included

if pDataA["phrases"][tElement] is not empty then

put "<" & word 1 to -1 of pDataA["phrases"][tElement] & ">" into tElementA["type"]

else if tParam["type"] is not empty then

put tParam["type"] into tElementA["type"]

end if

end if

if tParam["mode"] is not "in" then

put tParam["mode"] & " " before tElementA["type"]

end if

end if

end repeat

end repeat

end if

# Now output back to the doc data

put tElementA["name"] into tElement

if tElementA["type"] is not empty then

put tElement & "(" & tElementA["type"] & "):" && tElementA["content"] & return after tEntryDoc

else

if the number of lines in tElementA["content"] > 1 then

local tDeleteTab

put false into tDeleteTab

put tElement & ":" & return after tEntryDoc

repeat for each line tLine in tElementA["content"]

if line 1 of tElementA["content"] begins with tab then

put true into tDeleteTab

end if

if tDeleteTab and tLine begins with tab then

delete char 1 of tLine

end if

put tLine & return after tEntryDoc

end repeat

else

put tElement & ":" && tElementA["content"] & return after tEntryDoc

end if

end if

put return after tEntryDoc

end repeat

if tHasA["Syntax"] is not true then

put pDataA["syntax"] into tSyntax

end if

repeat with x = 1 to the number of elements in tSyntax

put "Syntax:" && tSyntax[x] & return & return before tEntryDoc

end repeat

if tHasA["Type"] is not true then

put pDataA["type"] into tType

end if

put "Type:" && tType & return & return before tEntryDoc

if tHasA["Name"] is not true then

put pDataA["name"] into tName

end if

if pIsLibrary and x = 0 then

put "Library:" && tName & return & return before tEntryDoc

else

put "Name:" && tName & return & return before tEntryDoc

end if

if tHasA["References"] is not true then

if pDataA["phrases"] is not empty then

put "References: " after tEntryDoc

repeat for each element tElement in pDataA["phrases"]

put tElement & "(phrase)" & comma after tEntryDoc

end repeat

delete the last char of tEntryDoc

put return & return after tEntryDoc

end if

end if

put tEntryDoc after tDocData

end repeat

return tDocData

end revDocsFormatInlineComments

function revDocsParseScriptDocs pText

return revDocsExtractDocBlocksFromScript(pText)

end revDocsParseScriptDocs

function revDocsCollectGlossarySynonyms pRoot

local tGlossaryA, tText, tName, tSynonyms

set the defaultfolder to pRoot & slash & "glossary"

local tFolders

put the folders into tFolders

repeat for each line tLine in tFolders

if tLine is ".." then next repeat

set the defaultfolder to pRoot & slash & "glossary" & slash & tLine

get the files

filter it with "*.lcdoc"

if it is not empty then

repeat for each line tFile in it

if tFile begins with "." then next repeat

put url ("file:" & pRoot & slash & "glossary" & slash & tLine & slash & tFile) into tText

get lineOffset("Name:", tText)

put word 2 to -1 of line it of tText into tName

if tName is empty then

next repeat

end if

get lineOffset("Synonyms:", tText)

put word 2 to -1 of line it of tText into tSynonyms

if tSynonyms is empty then

next repeat

end if

repeat for each item tItem in tSynonyms

put tName into tGlossaryA[tItem]

end repeat

end repeat

end if

end repeat

return tGlossaryA

end revDocsCollectGlossarySynonyms

private function __elementRegex

# Regex used to determine if this line starts a new element

# Matched substrings are element name, (optional) param type, same line element content

return "^ *([tT]he [rR]esult|\w*) *(?:\(( *(?:optional |in |out |inout )?<?\w*>?) *\))? *: *(.*)"

end __elementRegex

/*

Utility function to extract any elements matching the docs element style

*/

function revDocsExtractElements pText

# Get the element-matching regex

local tElementRegex

put __elementRegex() into tElementRegex

# Array to store the elements

local tElementsA

local tElementCount

put 0 into tElementCount

# Store the content that belongs to this element

local tElementA, tAccumulatedContent

# Flush the previous accumulation of content when we see a new element

local tFlushAccumulated

put false into tFlushAccumulated

# Variables to aid extraction of array parameter description

local tInArrayDescription

put false into tInArrayDescription

local tArrayDepth

put 0 into tArrayDepth

local tInternalBlankLines

repeat for each line tLine in pText

# Variables to store regex matches

local tNextElementName, tParamType, tAfterElement

get word 1 of tLine

if tInArrayDescription then

# Keep track of array depth

if it begins with "{" then

add 1 to tArrayDepth

put tLine & return after tAccumulatedContent

next repeat

end if

if word -1 of tLine ends with "}" then

subtract 1 from tArrayDepth

put tLine & return after tAccumulatedContent

if tArrayDepth <= 0 then

put false into tInArrayDescription

end if

next repeat

end if

end if

if tArrayDepth > 0 then

put tLine & return after tAccumulatedContent

next repeat

end if

# If this matches the element definition regex, flush the accumulated content to the elements array

# otherwise just append to the accumulated content

if word 1 of tLine is empty then

# AL-2015-09-03: [[ Bug 15866 ]] If we have an empty line and there is already content for this element,

# then the blank line is intentional whitespace, so keep track of the number

if tAccumulatedContent is not empty then

add 1 to tInternalBlankLines

end if

next repeat

else if matchText(tLine, tElementRegex, tNextElementName, tParamType, tAfterElement) then

if tElementCount is not 0 then

put tElementA into tElementsA[tElementCount]

delete the last char of tAccumulatedContent

put tAccumulatedContent into tElementsA[tElementCount]["content"]

end if

add 1 to tElementCount

put empty into tAccumulatedContent

put 0 into tInternalBlankLines

# Prevent propagation of element details

put empty into tElementA

put tNextElementName into tElementA["name"]

if tParamType is not empty then

put tParamType into tElementA["type"]

if tParamType is "array" then

put true into tInArrayDescription

end if

end if

put empty into tParamType

if word 1 of tAfterElement is not empty then

put word 1 to -1 of tAfterElement & return into tAccumulatedContent

end if

else

# AL-2015-09-03: [[ Bug 15866 ]] Include internal blank lines in content

repeat tInternalBlankLines

put return after tAccumulatedContent

end repeat

put 0 into tInternalBlankLines

put tLine & return after tAccumulatedContent

end if

end repeat

# Add any remaining text to the last element

put tElementA into tElementsA[tElementCount]

put tAccumulatedContent into tElementsA[tElementCount]["content"]

return tElementsA

end revDocsExtractElements

private command __nameToKeyAndType pName, @rKey, @rType

put pName into rKey

switch pName

case "Summary"

case "Type"

case "Description"

case "Changes"

case "Introduced"

put "standard" into rType

break