' Generate-report.ebs

'

' This is a RoseScript utility with which a user can traverse a 

' Rational Rose model and generate a Microsoft Word Document

' from the template "Formal.dot"

'

' A lot of the early versions of this script were derived from

' work previously published on the Rational Developer's Network

' and made freely available.

'

' TBD:

'       3. Provide cleaning subroutine or external utility to curb growth of %TEMP%

'               with rosedXXX.wmf files of rendered diagrams.

'       4. Provide a package selection drop-down on the Dialog so that many projects can 

'               coexist in the same model (bonus - reduces the probability of a 

'               mook accidentally choosing to document the EPOC32 "include" package).

'

Const DefaultTool$ = "ReportGen"

Const PRODUCTDEFAULTWORDDOCFILENAME     = 103

'

' Different report type specs

'

Const RepAnalysisType = 0

Const RepDesignType = 1

Const RepAnalysisNDesignType = 2

Const RepTestType = 3

'

' Model verification options

'

Const RepVerifyNot = 0

Const RepVerifySection = 1

Const RepVerifyEmbed = 2

'

' There is a state machine in here and these are the states

'

Const RPh_StartUp = 0

Const RPh_Dynamic = 1

Const RPh_Static = 2

Const RPh_TailBoiler = 3

Const RPh_Crosscheck = 4

'

' For proofreading purposes

'

Const MissingTextStr$ = "ATTENTION: Do You Need Documentation For This Item?"

'

' Useful type declaraions

'

'

' Told you there was a state machine in here

'

Type GeneratorStateType

    Phase As Integer

End Type

'

' Configurability - if this was Python, I'd serialise it

' and make it a config file

'

Type ReportOptionsType

    Title As String

    FileName As String

    Template As String

    Generate As Boolean

    WhiteBlock As Boolean

    ClassDiagrams As Boolean

    ScenarioDiagrams As Boolean

    StateDiagrams As Boolean

    UseCaseDiagrams As Boolean

    CppSyntax As Boolean

    PublicOnly As Boolean

	FEBoiler As Boolean

	BEBoiler As Boolean

	SupportSubheadingTags As Boolean

    HighlightDocGaps As Boolean

    DocType As Integer

    VerifyType As Integer

End Type

'

' When verifying the model, we need to establish relationships

' between scenario/sequence diagrams and their title. Also, on each iteration, we need to 

' check that we don't create duplicate entries where a method is used

' more than once in the same context.

'

Type DiagEntry

    FigureTitle As String

    Diagram As ScenarioDiagram

    SeenBefore As Boolean

End Type

'

' Globals - don't we just lurve Basic?

'

Private ReportOptions As ReportOptionsType

Private GeneratorState As GeneratorStateType

'

' An array of DiagEntry

'

Public GlobalDiagList() As DiagEntry

'

' So, the documentation doesn't explain how one would elicit the

' size of a dynamic array, so the counts have to be externalised.

' Just exactly how crap is that?

'

Public DiagListCount As Integer

Public GlobalDiagListSize As Integer

Public LicensedRoseApplication As Application

Private resIFace As Object

Public RWU_DiagramCount As Integer

'

' Sort of like an Application Constructor - yech!

'

Sub WordUtilInit()

    Let RWU_DiagramCount = 1

    Let DiagListCount = 0

    Let GlobalDiagListSize = 0

    ReDim GlobalDiagList(0)

End Sub

'

' Helper function

'

Sub Para(WordApp As Object)

    WordApp.InsertPara

End Sub

'

' For banging in a huge bunch of whitespace

'

Sub WhiteBlock(WordApp As Object)

    Para WordApp

    Para WordApp

    Para WordApp

    Para WordApp

    Para WordApp

End Sub

'

' Helper for page breaks

'

Sub Break(WordApp As Object)

    WordApp.InsertPageBreak

End Sub

'

' This is to overcome the limitations of Word as a programmable application

' and all I can say is that the details are nasty.

'

Sub ReplaceFinalParagraphKludge (WordApp As Object)

    WordApp.linedown

    WordApp.charright 1, 1  ' go right one character and select

    WordApp.insertpara      ' overwrite the selected para marker with a new one

    WordApp.lineup

End Sub

'

' Will need to reset the state on these objects regularly

'

Sub ResetGlobalDiagList

    For i% = 0 To GlobalDiagListSize-1

        GlobalDiagList(i).SeenBefore = False

    Next i

End Sub

'

' We need this for extracting diagrams and rendering them

' on the file system before inserting them into a Word

' document. Note that this does not clean up after itself

' which means that you are likely to accumulate rosedXXX.wmf

' files in your %TEMP% directory. The good news is that it

' transparently reuses files on each run, so this is not inevitable

' and unrestrained growth.

'

Function GetTmpFileName

    Dim tmpFileName As String

    Dim tmpPathName As String

    tmpPathName = Environ("TEMP")

    If tmpPathName = ""     Then

        tmpPathName = CurDir

    End If

    Do

        tmpFileName = tmpPathName + "\rosed" & RWU_DiagramCount & ".wmf"

        If Not Dir(tmpFileName)="" Then

            Kill(tmpFileName)

        End If

    Loop Until (Dir(tmpFileName)="")

    RWU_DiagramCount = RWU_DiagramCount + 1

    GetTmpFileName = tmpFileName

End Function

'----------------------------------------------------------------------------

'

' Specialist Word-related subroutines

'

'

' Generic Diagram insertion

'

Sub WordInsertDiagram(fileName As String, WordApp As Object)

    'ReplaceFinalParagraphKludge WordApp

    WordApp.CenterPara

    WordApp.InsertPicture fileName, false, false

    Para WordApp

	ReplaceFinalParagraphKludge WordApp

End Sub

'

' Each diagram type is literally a different type in the object model, so

' since Basic has no polymorphic facilities, we have to resort to

' coding up a subroutine for each type. Yawn!

'

Sub WordInsertScenarioDiagram(aDiagram As ScenarioDiagram, WordApp As Object)

    Dim tmpFileName As String

    Let tmpFileName = GetTmpFileName

    aDiagram.RenderEnhanced tmpFileName

    WordInsertDiagram tmpFileName, WordApp

End Sub

Sub WordInsertStateDiagram(aDiagram As StateDiagram, WordApp As Object)

    Dim tmpFileName As String

    Let tmpFileName = GetTmpFileName

    aDiagram.RenderEnhanced tmpFileName

    WordInsertDiagram tmpFileName, WordApp

End Sub

Sub WordInsertClassDiagram(aDiagram As ClassDiagram, WordApp As Object)

    Dim tmpFileName As String

    Let tmpFileName = GetTmpFileName

    aDiagram.RenderEnhanced tmpFileName

    WordInsertDiagram tmpFileName, WordApp

End Sub

'

' So we want to be able to translate our "depth" in the model into the

' appropriate heading style in Word.

'

Function GetWordHeadingStyleName(HeadingNumber As Integer) As String

    GetWordHeadingStyleName = "Heading " & CStr(HeadingNumber)

End Function

'

' Generalised heading insertion by number

'

Sub WordInsertHeading(aLevel As Integer, aString As String, WordApp As Object)

        ' If you do not do it, it will not run.

    ReplaceFinalParagraphKludge WordApp

        ' Here's the real code that actually does something

    WordApp.FormatStyle GetWordHeadingStyleName(aLevel)      

    WordApp.Insert aString

    Para WordApp

    WordApp.FormatStyle "Normal"

End Sub

Sub WordInsertDocumentation(HeadingLevel As Integer, Documentation As String, WordApp As Object)

	'

	' It was requested that the script support the insertion of

	' an HTML-like tag in the object documentation that would force the 

	' insertion of a subheading in the output text.

	' This will interefere with the real HTML generation capabilities

	' of Rose, so it was originally only supported as a variant on the 

	' script. This presents boring maintenance duplication issues, however, so it

	' was reincorporated as a configurable option. Unfortunately, it does change 

	' the signature of this method such that it requires a HeadingLevel even when it 

	' doesn't use one. 

	'

	Dim Astr As String

	Dim Bstr As String

	Dim Cstr As String

    If Documentation <> "" Then

		If ReportOptions.SupportSubheadingTags Then

			Astr = Trim(Documentation)

			Print "Astr: ", Astr

			x% = InStr(1,Astr,"<h>",1)

			y% = InStr(1,Astr,"</h>",1)

			While x% <> 0 And y% <> 0

				Cstr = Left(Astr,x%-1)

				Print "Cstr : ", Cstr

        		WordApp.FormatStyle "Normal"

        		WordApp.Insert Trim(Cstr)

        		Para WordApp

				Bstr = Mid(Astr,x%+3,y%-(x%+3))

				Print "Bstr : ", Bstr

				WordInsertHeading HeadingLevel,Trim(Bstr),WordApp

				Astr = Right(Astr,Len(Astr)-(y%+3))

				Print "Astr : ",Astr

				x% = InStr(1,Astr,"<h>",1)

				y% = InStr(1,Astr,"</h>",1)

			Wend

        	WordApp.FormatStyle "Normal"

        	WordApp.Insert Trim(Astr)

        	Para WordApp

		Else

        	WordApp.FormatStyle "Normal"

        	WordApp.Insert Trim(Documentation)

        	Para WordApp

		End If

    Else

        ' Oh no - we seem to have missed out a piece of documentation.

        ' Another proofreading setting will highlight this lacuna for

        ' you in lucky red text.

        If ReportOptions.HighlightDocGaps Then

            WordApp.FormatStyle "Body Text"

            WordApp.Insert MissingTextStr

            Para WordApp

        End If

    End If

	'

    ' To assist in the proofreading phases, it seemed useful

    ' to have a mode in which large chunks of whitespace were

    ' inserted into the document at every point where the hard working

    ' editor might wish to scribble notes and comments during the development

    ' of the text. Run the script with this set and print out the resultant document

    ' and you have a doc that facilitates the inveterate scribbler.

    ' I'm a great believer in appropriate technology.

	'

    If ReportOptions.WhiteBlock Then

        WhiteBlock WordApp

    End If

End Sub

'

' Of course we want each of our diagrams to be numbered and titled.

' It's the done thing, and it's the thing that gets done here.

'

Sub WordInsertFigureName(aFigureName As String, WordApp As Object)

    WordApp.FormatStyle "Centered"

    WordApp.Insert "Figure " + CStr(RWU_DiagramCount-1) & ": " & aFigureName

    Para WordApp

    WordApp.FormatStyle "Normal"

End Sub

'

' Unfortunately, we have to operate slightly differently for scenarios, because of

' the verifications we may wish to run.

'

Sub WordInsertScenarioFigureName(aFigureName As String, WordApp As Object, XCEntry As DiagEntry)

    Dim tstr$

    tstr = "Figure " + CStr(RWU_DiagramCount-1) & ": " & aFigureName

    WordApp.FormatStyle "Centered"

    'WordApp.Insert "Figure " + CStr(RWU_DiagramCount-1) & ": " & aFigureName

    WordApp.Insert tstr

    Para WordApp

    WordApp.FormatStyle "Normal"

        ' Need  to keep track of titles applied to scenario diagrams.

    XCEntry.FigureTitle = tstr

    Let GlobalDiagList(DiagListCount) = XCEntry

    DiagListCount = DiagListCount + 1

End Sub

'---------------------------------------------------------------------------

'

' Some handy utility muffins.

'

Public Function GetResourceString(resourceID As Long) As String

    If (resIFace Is Nothing) then

        Set resIFace = CreateObject("rvsreportgenres.rvsrepgeninterface")

    End If

    GetResourceString = resIFace.GetString(resourceID)

End Function

Function GetLicensedRoseApplication() As Application

    Set GetLicensedRoseApplication = RoseApp.GetLicensedApplication("{A567222E-CBBE-11D0-BC0B-00A024C67143}")

End Function

Function ReportDialogLoop(controlname$, action%, suppvalue%) As Integer

    If controlname$ = "Browse" Then

        FileName$ = SaveFilename$ ("Create a Word document",  "Word Documents:*.DOC")

        If FileName$ <> "" Then

            DlgText "FileName", FileName$

        End If

        ReportDialogLoop = 1

    End If

End Function

Function EnclosingDirPath(FileName As String)

    ' Extracts the enclosing directory path from a file name

    Dim Pos1, Pos2, Pos3

    On Error GoTo EnclosingDirPath_exception

    Pos3 = 255

    Pos2 = 1

    Pos1 = 1

    Do

        Pos3 = InStr(Pos2 + 1, FileName, "\")

        If Pos3 <> 0 Then

            Pos1 = Pos2

            Pos2 = Pos3

        Else

            Exit Do

        End If

    Loop

    EnclosingDirPath = Left(FileName, Pos2 - 1)

    Exit Function

EnclosingDirPath_exception:

    Resume EnclosingDirPath_end

EnclosingDirPath_end:

    'Exit with the full path

    EnclosingDirPath = FileName

End Function

Function GetAllOfClasses(aCategory As Category) As ClassCollection

    Dim theCatClassCollection As New ClassCollection

    Dim theCatClass As Class, theCatInnerClass As Class

    Dim I As Integer, J As Integer

    For I = 1 To aCategory.Classes.Count

        Set theCatClass =  aCategory.Classes.GetAt(I)

        theCatClassCollection.Add theCatClass

        For J = 1 To theCatClass.GetAllNestedClasses.Count

            Set theCatInnerClass = theCatClass.GetAllNestedClasses.GetAt(J)

            theCatClassCollection.Add theCatInnerClass

        Next J

    Next I

    Set GetAllOfClasses = theCatClassCollection

End Function

Function MakeFileName (Path As String, FileName As String) As String

    ' Check to see if the last character is a separator

    If Instr ("\/", Right$(Path, 1)) Then

        MakeFileName$ = Path & FileName

    Else

        MakeFileName$ = Path & "\" & FileName

    End If

End Function

Function ChangeFileExtension (FullFileName As String, NewExtension As String) As String

    FilePath$ = FileParse$ (FullFileName, 2)

    FileRoot$ = FileParse$ (FullFileName, 4)

    ChangeFileExtension$ = MakeFileName$ (FilePath$, FileRoot$ & "." & NewExtension$)

End Function

'------------------------------------------------------------------------------

'

' Rose collections are unsorted. This is not considered sightly.

'

Sub sortalpha( aCategory As Category, myAlpha() As String)

    Dim theCatClassCollection As ClassCollection

    Set theCatClassCollection = GetAllOfClasses(aCategory)

    For ike = 1 To theCatClassCollection.count

        myAlpha(ike) = theCatClassCollection.GetAt(ike).Name

    Next ike

    arraysort myAlpha

    Set theCatClassCollection = Nothing

End Sub

Sub sortalphaclassdiagrams( aCategory As Category, myAlpha() As String)

    Dim classDiagrams As ClassDiagramCollection

    Set classDiagrams = aCategory.ClassDiagrams

    For ike = 1 To classDiagrams.count

        myAlpha(ike) = classDiagrams.GetAt(ike).Name

    Next ike

    arraysort myAlpha

    Set classDiagrams = Nothing

End Sub

Sub sortalphascenariodiagrams( aCategory As Category, myAlpha() As String)

    Dim scenarioDiagrams As ScenarioDiagramCollection

    Set scenarioDiagrams = aCategory.ScenarioDiagrams

    For ike = 1 To ScenarioDiagrams.count

        myAlpha(ike) = ScenarioDiagrams.GetAt(ike).Name

    Next ike

    arraysort myAlpha

    Set ScenarioDiagrams = Nothing

End Sub

'------------------------------------------------------------------------------

'

' These higher level procedures pretty much do what their names say they do.

'

Sub SearchForClassDiagramsInPackage(WordApp As Object, aCategory As Category, HeadingNumber As Integer)

    Dim classDiagrams As ClassDiagramCollection

    Dim aClassDiagram As ClassDiagram

    Dim Alpha() As String

    Set classDiagrams = aCategory.ClassDiagrams

    ReDim Alpha(classDiagrams.Count)

    SortAlphaClassDiagrams aCategory, alpha

    If classDiagrams.Count Then

        'Dim theClass As Class

        'Dim NestedClasses As ClassCollection

        For CLSID = 1 To classDiagrams.Count

            Ike = classDiagrams.FindFirst(Alpha(CLSID))

            Set aClassDiagram = classDiagrams.GetAt(Ike)

        	If Not (aClassDiagram.IsUseCaseDiagram) Then

				WordInsertHeading HeadingNumber, aClassDiagram.Name, WordApp

            	WordInsertClassDiagram aClassDiagram, WordApp

            	WordInsertFigureName aClassDiagram.Name, WordApp

            	WordInsertDocumentation HeadingNumber+1, aClassDiagram.Documentation, WordApp

        	End If

        Next CLSID

    End If

    'For clsID = 1 To classDiagrams.Count

     '   Set aClassDiagram=classDiagrams.GetAt(clsID)

     '   If Not (aClassDiagram.IsUseCaseDiagram) Then

	 '		WordInsertHeading HeadingNumber, aClassDiagram.Name, WordApp

     '       WordInsertClassDiagram aClassDiagram, WordApp

     '       WordInsertFigureName aClassDiagram.Name, WordApp

     '       WordInsertDocumentation HeadingNumber+1, aClassDiagram.Documentation, WordApp

      '  End If

    'Next clsID

End Sub

Sub SearchForSeqAndCollabDiagramsInPackage(WordApp As Object, aCategory As Category, HeadingNumber As Integer)

    Dim ScenarioDiagrams As ScenarioDiagramCollection

    Dim aScenarioDiagram As ScenarioDiagram

    Dim Alpha() As String

    Set ScenarioDiagrams = aCategory.ScenarioDiagrams

    ReDim Alpha(ScenarioDiagrams.Count)

    SortAlphaScenarioDiagrams aCategory, alpha

    Dim XCEntry As DiagEntry