Index: xotcl/library/lib/xodoc.xotcl =================================================================== diff -u -r2c6cdd4f5d1c45c96e996a70b54ae4c5f46a40fd -r435b41481fb51bf000ebe736d8574fefbeec1710 --- xotcl/library/lib/xodoc.xotcl (.../xodoc.xotcl) (revision 2c6cdd4f5d1c45c96e996a70b54ae4c5f46a40fd) +++ xotcl/library/lib/xodoc.xotcl (.../xodoc.xotcl) (revision 435b41481fb51bf000ebe736d8574fefbeec1710) @@ -1,402 +1,412 @@ -# $Id: xodoc.xotcl,v 1.2 2004/10/30 20:19:55 neumann Exp $ +# $Id: xodoc.xotcl,v 1.3 2005/09/09 21:07:23 neumann Exp $ + package provide xotcl::xodoc 0.84 package require xotcl::staticMetadataAnalyzer package require xotcl::htmllib #package require xotcl::trace +package require XOTcl -@ @File { - description { - XOTcl documentation tool. Overloads the command @, which is used - as a documentation token. - } -} +namespace eval ::xotcl::xodoc { + namespace import ::xotcl::* -@ Class MetadataTokenHTML { - description {Instmixin to provide HTML printing. Such instmixins - are registered for all token types. - } -} -Class MetadataTokenHTML -@ MetadataTokenHTML abstract instproc printHTML {} { - description {Print token to HTML document object} -} -MetadataTokenHTML abstract instproc printHTML {} + @ @File { + description { + XOTcl documentation tool. Overloads the command @, which is used + as a documentation token. + } + } -@ MetadataTokenHTML instproc getDocPropertiesHTML {} { - description { - Returns list of properties as HTML. + @ Class MetadataTokenHTML { + description {Instmixin to provide HTML printing. Such instmixins + are registered for all token types. + } } -} + Class MetadataTokenHTML + @ MetadataTokenHTML abstract instproc printHTML {} { + description {Print token to HTML document object} + } + MetadataTokenHTML abstract instproc printHTML {} -MetadataTokenHTML instproc getDocPropertiesHTML {htmlDoc} { - foreach p [my set properties] { - $htmlDoc startTableRow -valign top - if {[my exists $p]} { - $htmlDoc startTableCell -valign top - $htmlDoc addString " [my capitalize $p]:" - $htmlDoc endTableCell + @ MetadataTokenHTML instproc getDocPropertiesHTML {} { + description { + Returns list of properties as HTML. + } + } - $htmlDoc startTableCell -valign top - if {$p == "errorCodes"} { - # Build table cell with list of error codes. - foreach {code desc} [my set $p] { - set code [string map [list < <\; > >\;] $code] - set desc [string map [list < <\; > >\;] $desc] - $htmlDoc addString "$code: $desc\n

" + MetadataTokenHTML instproc getDocPropertiesHTML {htmlDoc} { + foreach p [my set properties] { + $htmlDoc startTableRow -valign top + if {[my exists $p]} { + $htmlDoc startTableCell -valign top + $htmlDoc addString " [my capitalize $p]:" + $htmlDoc endTableCell + + $htmlDoc startTableCell -valign top + if {$p == "errorCodes"} { + # Build table cell with list of error codes. + foreach {code desc} [my set $p] { + set code [string map [list < <\; > >\;] $code] + set desc [string map [list < <\; > >\;] $desc] + $htmlDoc addString "$code: $desc\n

" + } + } else { + $htmlDoc addString [my set $p] + } + $htmlDoc endTableCell + } + $htmlDoc endTableRow } - } else { - $htmlDoc addString [my set $p] - } - $htmlDoc endTableCell } - $htmlDoc endTableRow - } -} -MetadataTokenHTML instproc reflowHTML {left paragraph} { - #set result "" - #foreach line [split $paragraph \n] { - # if {![regexp {^ *$} $line]} { - # append result "$left$line
\n" - # } - #} - #return $result - return $paragraph -} + MetadataTokenHTML instproc reflowHTML {left paragraph} { + #set result "" + #foreach line [split $paragraph \n] { + # if {![regexp {^ *$} $line]} { + # append result "$left$line
\n" + # } + #} + #return $result + return $paragraph + } -MetadataToken instmixin [concat [MetadataToken info instmixin] MetadataTokenHTML] + MetadataToken instmixin [concat [MetadataToken info instmixin] MetadataTokenHTML] -@ Class FileTokenHTML -superclass MetadataTokenHTML -Class FileTokenHTML -superclass MetadataTokenHTML -FileTokenHTML instproc printHTML {htmlDoc} { - $htmlDoc addLineBreak - $htmlDoc addString " Filename: " - $htmlDoc addAnchor [my set name] -href [my set name] - $htmlDoc addLineBreak - $htmlDoc addLineBreak - $htmlDoc startTable -border 0 - my getDocPropertiesHTML $htmlDoc - $htmlDoc endTable -} + @ Class FileTokenHTML -superclass MetadataTokenHTML + Class FileTokenHTML -superclass MetadataTokenHTML + FileTokenHTML instproc printHTML {htmlDoc} { + $htmlDoc addLineBreak + $htmlDoc addString " Filename: " + $htmlDoc addAnchor [my set name] -href [my set name] + $htmlDoc addLineBreak + $htmlDoc addLineBreak + $htmlDoc startTable -border 0 + my getDocPropertiesHTML $htmlDoc + $htmlDoc endTable + } -FileToken instmixin [concat [FileToken info instmixin] FileTokenHTML] + FileToken instmixin [concat [FileToken info instmixin] FileTokenHTML] -@ Class ConstraintTokenHTML -superclass MetadataTokenHTML -Class ConstraintTokenHTML -superclass MetadataTokenHTML -ConstraintTokenHTML instproc printHTML {htmlDoc} { - $htmlDoc addAnchor "" -name [my set name] - $htmlDoc addString "

Constraint: [my set name]

" - $htmlDoc addLineBreak - $htmlDoc startTable -border 0 - my getDocPropertiesHTML $htmlDoc - $htmlDoc endTable -} + @ Class ConstraintTokenHTML -superclass MetadataTokenHTML + Class ConstraintTokenHTML -superclass MetadataTokenHTML + ConstraintTokenHTML instproc printHTML {htmlDoc} { + $htmlDoc addAnchor "" -name [my set name] + $htmlDoc addString "

Constraint: [my set name]

" + $htmlDoc addLineBreak + $htmlDoc startTable -border 0 + my getDocPropertiesHTML $htmlDoc + $htmlDoc endTable + } -ConstraintToken instmixin [concat [ConstraintToken info instmixin] ConstraintTokenHTML] + ConstraintToken instmixin [concat [ConstraintToken info instmixin] ConstraintTokenHTML] -@ Class ObjTokenHTML -superclass MetadataTokenHTML -Class ObjTokenHTML -superclass MetadataTokenHTML -ObjTokenHTML instproc getProcsHTML {htmlDoc} { - set c "" - set pl [MetadataToken sortTokenList [my procList]] - if {[my istype ClassToken]} { - set pl [concat [MetadataToken sortTokenList [my instprocList]] $pl] - } - foreach p $pl { - set pn [$p set name] - set label($pn) "$pn" - } - foreach l [lsort [array names label]] { - if {$c != ""} {append c ", "} - append c $label($l) - } - if {$c != ""} {append c "."} - $htmlDoc addString "$c" -} - -ObjTokenHTML instproc printHTML {htmlDoc} { - $htmlDoc addAnchor "" -name [my set name] - if {[my istype MetaClassToken]} { - set start "

MetaClass:" - } elseif {[my istype ClassToken]} { - set start "

Class:" - } else { - set start "

Object:" - } - $htmlDoc addString "$start [my set name]

" - if {[my exists cl]} { - $htmlDoc addString "Class: [my set cl]" - $htmlDoc addLineBreak - } - if {[my exists heritage]} { - $htmlDoc addString "Heritage: [my set heritage]" - $htmlDoc addLineBreak - } + @ Class ObjTokenHTML -superclass MetadataTokenHTML + Class ObjTokenHTML -superclass MetadataTokenHTML + ObjTokenHTML instproc getProcsHTML {htmlDoc} { + set c "" + set pl [MetadataToken sortTokenList [my procList]] + if {[my istype ClassToken]} { + set pl [concat [MetadataToken sortTokenList [my instprocList]] $pl] + } + foreach p $pl { + set pn [$p set name] + set label($pn) "$pn" + } + foreach l [lsort [array names label]] { + if {$c != ""} {append c ", "} + append c $label($l) + } + if {$c != ""} {append c "."} + $htmlDoc addString "$c" + } + + ObjTokenHTML instproc printHTML {htmlDoc} { + $htmlDoc addAnchor "" -name [my set name] + if {[my istype MetaClassToken]} { + set start "

MetaClass:" + } elseif {[my istype ClassToken]} { + set start "

Class:" + } else { + set start "

Object:" + } + $htmlDoc addString "$start [my set name]

" + if {[my exists cl]} { + $htmlDoc addString "Class: [my set cl]" + $htmlDoc addLineBreak + } + if {[my exists heritage]} { + $htmlDoc addString "Heritage: [my set heritage]" + $htmlDoc addLineBreak + } - set head "" - if {[my procList] != ""} {set head " Procs "} - if {[my istype ClassToken]} { - if {[my instprocList] != ""} {set head " Procs/Instprocs: "} - } - $htmlDoc addString $head - my getProcsHTML $htmlDoc + set head "" + if {[my procList] != ""} {set head " Procs "} + if {[my istype ClassToken]} { + if {[my instprocList] != ""} {set head " Procs/Instprocs: "} + } + $htmlDoc addString $head + my getProcsHTML $htmlDoc - $htmlDoc startTable -border 0 - my getDocPropertiesHTML $htmlDoc - $htmlDoc endTable -} + $htmlDoc startTable -border 0 + my getDocPropertiesHTML $htmlDoc + $htmlDoc endTable + } -ObjToken instmixin [concat [ObjToken info instmixin] ObjTokenHTML] + ObjToken instmixin [concat [ObjToken info instmixin] ObjTokenHTML] -@ Class MethodTokenHTML -superclass MetadataTokenHTML -Class MethodTokenHTML -superclass MetadataTokenHTML + @ Class MethodTokenHTML -superclass MetadataTokenHTML + Class MethodTokenHTML -superclass MetadataTokenHTML -# Prints out method information as HTML. -MethodTokenHTML instproc printHTML {htmlDoc} { - #my showVars - set argText "\n" + # Prints out method information as HTML. + MethodTokenHTML instproc printHTML {htmlDoc} { + #my showVars + set argText "\n" - HtmlBuilder args + HtmlBuilder args - set a "Arguments:" + set a "Arguments:" - set anchor [my set obj]-[my set name] - $htmlDoc addAnchor "" -name $anchor + set anchor [my set obj]-[my set name] + $htmlDoc addAnchor "" -name $anchor - if {[my abstract]} {$htmlDoc addString "abstract"} - $htmlDoc addString "[my set name] " + if {[my abstract]} {$htmlDoc addString "abstract"} + $htmlDoc addString "[my set name] " - args set indentLevel [$htmlDoc set indentLevel] + args set indentLevel [$htmlDoc set indentLevel] - if {[my exists arguments]} { - #set argText "\n" - foreach {arg argDescription} [my set arguments] { - if {[llength $arg] > 1} { - # A default value was given to the argument. - $htmlDoc addString "?[lindex $arg 0]?" - set at "?[lindex $arg 0]?:$argDescription Default: \"[lindex $arg 1]\"." - } else { - $htmlDoc addString "$arg" - set at "$arg: $argDescription" - } - args startTableRow -valign top - args startTableCell -valign top - args addString $a - set a "" - args endTableCell - args startTableCell -valign top - args addString $at - args endTableCell - args endTableRow - } - } - $htmlDoc startTable -border 0 - - $htmlDoc addString [args toString] - args destroy + if {[my exists arguments]} { + #set argText "
\n" + foreach {arg argDescription} [my set arguments] { + if {[llength $arg] > 1} { + # A default value was given to the argument. + $htmlDoc addString "?[lindex $arg 0]?" + set at "?[lindex $arg 0]?:$argDescription Default: \"[lindex $arg 1]\"." + } else { + $htmlDoc addString "$arg" + set at "$arg: $argDescription" + } + args startTableRow -valign top + args startTableCell -valign top + args addString $a + set a "" + args endTableCell + args startTableCell -valign top + args addString $at + args endTableCell + args endTableRow + } + } + $htmlDoc startTable -border 0 + + $htmlDoc addString [args toString] + args destroy - my getDocPropertiesHTML $htmlDoc + my getDocPropertiesHTML $htmlDoc - $htmlDoc endTable + $htmlDoc endTable - #$htmlDoc endListItem -} + #$htmlDoc endListItem + } -MethodToken instmixin [concat [MethodToken info instmixin] MethodTokenHTML] + MethodToken instmixin [concat [MethodToken info instmixin] MethodTokenHTML] -@ Class XODoc { description "Handler class for building a documentation database" } + @ Class XODoc { description "Handler class for building a documentation database" } -Class XODoc -superclass StaticMetadataAnalyzer + Class XODoc -superclass StaticMetadataAnalyzer -@ XODoc proc documentFileAsHTML { - file "filename of the xotcl file to be documented" - docdir "directory to which the html file is written" -} { - description "Uses the xoDoc package to produce an HTML documentation of + @ XODoc proc documentFileAsHTML { + file "filename of the xotcl file to be documented" + docdir "directory to which the html file is written" + } { + description "Uses the xoDoc package to produce an HTML documentation of a specified file ***.xotcl. The file is written to ***.html in docdir" - return "file basename without suffix" -} + return "file basename without suffix" + } -XODoc proc documentFileAsHTML {file docdir} { - set docdb [XODoc [XODoc autoname docdb]] - ::@ set analyzerObj $docdb - $docdb analyzeFile $file - set ext [file extension $file] - if {$ext != ""} {set ext -[string trimleft $ext .]} - set docfilename [file rootname [file tail $file]]$ext - $docdb writeFile ${docdir}/$docfilename.html $file - $docdb destroy - return $docfilename -} + XODoc proc documentFileAsHTML {file docdir} { + set docdb [XODoc [XODoc autoname docdb]] + ::@ set analyzerObj $docdb + $docdb analyzeFile $file + set ext [file extension $file] + if {$ext != ""} {set ext -[string trimleft $ext .]} + set docfilename [file rootname [file tail $file]]$ext + $docdb writeFile ${docdir}/$docfilename.html $file + $docdb destroy + return $docfilename + } -XODoc instproc printPackages {htmlDoc} { - my instvar packageList - $htmlDoc addString "

Package/File Information

" - if {[llength $packageList] > 0} { - foreach t $packageList { - if {[$t type] == "provide"} { - $htmlDoc addString " Package provided: [$t name] [$t version]" - } elseif {[$t type] == "require"} { - $htmlDoc addString " Package required: [$t name] [$t version]" - } - $htmlDoc addLineBreak + XODoc instproc printPackages {htmlDoc} { + my instvar packageList + $htmlDoc addString "

Package/File Information

" + if {[llength $packageList] > 0} { + foreach t $packageList { + if {[$t type] == "provide"} { + $htmlDoc addString " Package provided: [$t name] [$t version]" + } elseif {[$t type] == "require"} { + $htmlDoc addString " Package required: [$t name] [$t version]" + } + $htmlDoc addLineBreak + } + } else { + $htmlDoc addString " No package provided/required " + $htmlDoc addLineBreak + } } - } else { - $htmlDoc addString " No package provided/required " - $htmlDoc addLineBreak - } -} -XODoc instproc printExtensions {htmlDoc} { - my instvar extensions - if {[info exists extensions]} { - # Add list of extensions. - foreach extension $extensions { - $htmlDoc addLineBreak - $htmlDoc addString "

Document extension: [$extension name]" - $htmlDoc addString "Description: [$extension description]" - $htmlDoc addLineBreak + XODoc instproc printExtensions {htmlDoc} { + my instvar extensions + if {[info exists extensions]} { + # Add list of extensions. + foreach extension $extensions { + $htmlDoc addLineBreak + $htmlDoc addString "

Document extension: [$extension name]" + $htmlDoc addString "Description: [$extension description]" + $htmlDoc addLineBreak + } + } } - } -} -XODoc instproc printObjList {htmlDoc} { - set objList [MetadataToken sortTokenList [my objList]] + XODoc instproc printObjList {htmlDoc} { + set objList [MetadataToken sortTokenList [my objList]] - if {[llength $objList]>0} { - $htmlDoc addLineBreak - $htmlDoc addString "Defined Objects/Classes: " - $htmlDoc startUnorderedList - foreach obj $objList { - set on [$obj set name] - $htmlDoc startListItem - $htmlDoc addAnchor "$on:" -href "#$on" - $obj getProcsHTML $htmlDoc - $htmlDoc addLineBreak - $htmlDoc endListItem + if {[llength $objList]>0} { + $htmlDoc addLineBreak + $htmlDoc addString "Defined Objects/Classes: " + $htmlDoc startUnorderedList + foreach obj $objList { + set on [$obj set name] + $htmlDoc startListItem + $htmlDoc addAnchor "$on:" -href "#$on" + $obj getProcsHTML $htmlDoc + $htmlDoc addLineBreak + $htmlDoc endListItem + } + $htmlDoc endUnorderedList + } } - $htmlDoc endUnorderedList - } -} -XODoc instproc printFileToken {htmlDoc} { - if {[my exists fileToken]} { - [my set fileToken] printHTML $htmlDoc - } else { - $htmlDoc addString " No file information. \n" - } - $htmlDoc addLineBreak -} + XODoc instproc printFileToken {htmlDoc} { + if {[my exists fileToken]} { + [my set fileToken] printHTML $htmlDoc + } else { + $htmlDoc addString " No file information. \n" + } + $htmlDoc addLineBreak + } -XODoc instproc printConstraintsList {htmlDoc} { - set constraintList [MetadataToken sortTokenList [my constraintList]] + XODoc instproc printConstraintsList {htmlDoc} { + set constraintList [MetadataToken sortTokenList [my constraintList]] - if {[llength $constraintList]>0} { - $htmlDoc addLineBreak - $htmlDoc addString "Defined Constraints: " - $htmlDoc startUnorderedList - foreach c $constraintList { - set cn [$c set name] - $htmlDoc startListItem - $htmlDoc addAnchor "$cn:" -href "#$cn" - $htmlDoc addLineBreak - $htmlDoc endListItem + if {[llength $constraintList]>0} { + $htmlDoc addLineBreak + $htmlDoc addString "Defined Constraints: " + $htmlDoc startUnorderedList + foreach c $constraintList { + set cn [$c set name] + $htmlDoc startListItem + $htmlDoc addAnchor "$cn:" -href "#$cn" + $htmlDoc addLineBreak + $htmlDoc endListItem + } + $htmlDoc endUnorderedList + } } - $htmlDoc endUnorderedList - } -} -XODoc instproc printConstraints {htmlDoc} { - foreach c [my set constraintList] { - $htmlDoc addHorizontalRule - $htmlDoc startParagraph - $c printHTML $htmlDoc - $htmlDoc endParagraph - } - $htmlDoc addLineBreak -} + XODoc instproc printConstraints {htmlDoc} { + foreach c [my set constraintList] { + $htmlDoc addHorizontalRule + $htmlDoc startParagraph + $c printHTML $htmlDoc + $htmlDoc endParagraph + } + $htmlDoc addLineBreak + } -XODoc instproc printProcsList {htmlDoc list string} { - if {[llength $list] > 0} { - $htmlDoc addString "

$string

" - $htmlDoc startUnorderedList - foreach s $list { - $htmlDoc startListItem - $s printHTML $htmlDoc - $htmlDoc endListItem + XODoc instproc printProcsList {htmlDoc list string} { + if {[llength $list] > 0} { + $htmlDoc addString "

$string

" + $htmlDoc startUnorderedList + foreach s $list { + $htmlDoc startListItem + $s printHTML $htmlDoc + $htmlDoc endListItem + } + $htmlDoc endUnorderedList + } } - $htmlDoc endUnorderedList - } -} -XODoc instproc printObjs {htmlDoc} { - set objList [MetadataToken sortTokenList [my objList]] + XODoc instproc printObjs {htmlDoc} { + set objList [MetadataToken sortTokenList [my objList]] - foreach t $objList { - $htmlDoc addHorizontalRule - $htmlDoc startParagraph - $t printHTML $htmlDoc - if {[$t istype ClassToken]} { - my printProcsList $htmlDoc [$t set instprocList] Instprocs + foreach t $objList { + $htmlDoc addHorizontalRule + $htmlDoc startParagraph + $t printHTML $htmlDoc + if {[$t istype ClassToken]} { + my printProcsList $htmlDoc [$t set instprocList] Instprocs + } + my printProcsList $htmlDoc [$t set procList] Procs + $htmlDoc endParagraph + } } - my printProcsList $htmlDoc [$t set procList] Procs - $htmlDoc endParagraph - } -} -XODoc instproc replaceFormatTags {fc} { - regsub -all <@ $fc < fc - regsub -all " - htmlDoc addImage -src "./logo-100.jpg" -alt "$name" -align MIDDLE - htmlDoc addStringDecr "$name" - htmlDoc addHorizontalRule - htmlDoc startParagraph + @ XODoc instproc printHTML { + name "name of the html document" + } { + description "Create HTML documentation object from metadata token" + } + XODoc instproc printHTML {name} { + HtmlBuilder htmlDoc + htmlDoc startDocument -title "XOTcl - Documentation -- $name" \ + -bgcolor FFFFFF -stylesheet xotcl-doc.css + htmlDoc addStringIncr "

" + htmlDoc addImage -src "./logo-100.jpg" -alt "$name" -align MIDDLE + htmlDoc addStringDecr "$name

" + htmlDoc addHorizontalRule + htmlDoc startParagraph - my printPackages htmlDoc - my printExtensions htmlDoc - my printObjList htmlDoc - my printConstraintsList htmlDoc - my printFileToken htmlDoc - my printObjs htmlDoc - my printConstraints htmlDoc - htmlDoc endParagraph - htmlDoc addHorizontalRule - htmlDoc startParagraph - htmlDoc endParagraph - htmlDoc addAnchor "Back to index page." -href "./index.html" - htmlDoc addLineBreak - htmlDoc addHorizontalRule - htmlDoc startParagraph - htmlDoc endParagraph - htmlDoc endDocument - set r [my replaceFormatTags [htmlDoc toString]] - htmlDoc destroy - return $r -} + my printPackages htmlDoc + my printExtensions htmlDoc + my printObjList htmlDoc + my printConstraintsList htmlDoc + my printFileToken htmlDoc + my printObjs htmlDoc + my printConstraints htmlDoc + htmlDoc endParagraph + htmlDoc addHorizontalRule + htmlDoc startParagraph + htmlDoc endParagraph + htmlDoc addAnchor "Back to index page." -href "./index.html" + htmlDoc addLineBreak + htmlDoc addHorizontalRule + htmlDoc startParagraph + htmlDoc endParagraph + htmlDoc endDocument + set r [my replaceFormatTags [htmlDoc toString]] + htmlDoc destroy + return $r + } -@ XODoc instproc writeFile { - filename "file name destination" name "name of the html document" -} { - description "Create HTML docuemntation from metadata token and write to file " + @ XODoc instproc writeFile { + filename "file name destination" name "name of the html document" + } { + description "Create HTML docuemntation from metadata token and write to file " + } + XODoc instproc writeFile {filename name} { + set content [my printHTML $name] + set f [open $filename w] + puts $f $content + close $f + } + + namespace export \ + MetadataTokenHTML FileTokenHTML ConstraintTokenHTML ObjTokenHTML \ + MethodTokenHTML XODoc } -XODoc instproc writeFile {filename name} { - set content [my printHTML $name] - set f [open $filename w] - puts $f $content - close $f -} - +namespace import ::xotcl::xodoc::*