"

 COPYRIGHT (c) 2003 by eXept Software AG

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic2' }"

"{ NameSpace: Smalltalk }"

Object subclass:#KeywordInContextIndexBuilder

	instanceVariableNames:'keywordToLinesMapping excluded separatorAlgorithm'

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Support'

!

!KeywordInContextIndexBuilder class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 2003 by eXept Software AG

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    A support class for building a KWIC (Keyword in Context) index.

    (for example, to build a KWIC index on html pages or class documentation).

    To generate a kwic, add each line together with a reference (or page number, or whatever),

    using addLine:reference:.

    Then, when finished, enumerate the kwic.

    [author:]

        Claus Gittinger (cg@alan)

    [instance variables:]

    [class variables:]

    [see also:]

"

!

examples

"

                                                                [exBegin]

    |kwic|

    kwic := KeywordInContextIndexBuilder new.

    kwic excluded:#('the' 'and' 'a' 'an').

    kwic addLine:'bla bla bla' reference:1.

    kwic addLine:'one two three' reference:2.

    kwic addLine:'a cat and a dog' reference:3.

    kwic addLine:'the man in the middle' reference:4.

    kwic addLine:'the man with the dog' reference:5.

    kwic 

        entriesDo:[:word :left :right :ref |

            Transcript 

                show:((left contractTo:20) leftPaddedTo:20);

                space;

                show:((word contractTo:10) leftPaddedTo:10) allBold;

                space;

                show:((right contractTo:20) leftPaddedTo:20);

                space;

                show:'['; show:ref; show:']';

                cr    

        ].

                                                                [exEnd]

  KWIC index over method selector components; build a little browser window:

                                                                [exBegin]

    |kwic v s c list refs|

    kwic := KeywordInContextIndexBuilder new.

    Smalltalk allClassesDo:[:eachClass |

        eachClass instAndClassSelectorsAndMethodsDo:[:sel :mthd |

            kwic addLine:sel reference:mthd.

        ]

    ].

    v := StandardSystemView new.

    v addComponent:(s := HVScrollableView for:SelectionInListView).

    s origin:0.0@0.0 corner:1.0@0.5.

    v addComponent:(c := HVScrollableView for:CodeView).

    c origin:0.0@0.5 corner:1.0@1.0.

    refs := OrderedCollection new.

    list := OrderedCollection new.

    kwic 

        entriesDo:[:word :left :right :ref |

            list add:(word,' ',left,' ',word allBold,' ',right,' (',ref mclass name,')').

            refs add:ref].

    s list:list.

    s action:[:lNr | c contents:(refs at:lNr) source].

    v open.

                                                                [exEnd]

  KWIC index over method selector components, with word separation:

                                                                [exBegin]

    |kwic|

    kwic := KeywordInContextIndexBuilder forMethodSelectorIndex.

    Smalltalk allClassesDo:[:eachClass |

        eachClass instAndClassSelectorsAndMethodsDo:[:sel :mthd |

            kwic addLine:sel reference:mthd.

        ]

    ].

    kwic

                                                                [exEnd]

  KWIC index over method comments:

                                                                [exBegin]

    |kwic v s c refs list|

    kwic := KeywordInContextIndexBuilder forMethodComments.

    Smalltalk allClassesDo:[:eachClass |

        eachClass instAndClassSelectorsAndMethodsDo:[:sel :mthd |

            |comment|

            (sel == #documentation) ifTrue:[

                comment := mthd comment.

                comment notNil ifTrue:[

                    kwic addLine:comment reference:mthd mclass ignoreCase:true.

                ]

            ] ifFalse:[

                (sel ~~ #examples

                and:[ sel ~~ #copyright

                and:[ sel ~~ #version]]) ifTrue:[

                    comment := mthd comment.

                    comment notNil ifTrue:[

                        kwic addLine:comment reference:mthd ignoreCase:true.

                    ]

                ]

            ]

        ]

    ].

    kwic.

                                                                [exEnd]

  KWIC index over class comments:

                                                                [exBegin]

    |kwic|

    kwic := KeywordInContextIndexBuilder forMethodComments.

    Smalltalk allClassesDo:[:eachClass |

        |mthd comment|

        mthd := eachClass theMetaclass compiledMethodAt:#documentation.

        mthd notNil ifTrue:[

            comment := mthd comment.

            comment notNil ifTrue:[

                kwic addLine:comment reference:eachClass theNonMetaclass ignoreCase:true.

            ]

        ]

    ].

    kwic

                                                                [exEnd]

"

! !

!KeywordInContextIndexBuilder class methodsFor:'instance creation'!

forMethodComments

    "return an indexer for method comments"

    |sepChars sep kwic|

    sepChars := '.,;:_ !![]()''"#?<>|' , Character return, Character lf, Character tab.

    sep := [:lines | lines asString asCollectionOfSubstringsSeparatedByAny:sepChars].

    kwic := self new.

    kwic separatorAlgorithm:sep.

    kwic excluded:#('the' 'and' 'a' 'an' 'for' 'with' 'no').

    ^ kwic

!

forMethodSelectorIndex

    "return an indexer for method selector components, with word separation at case boundaries"

    |sep kwic sepUCWords|

    sepUCWords := [:word :keyWords| 

                    |s w c lastC last2C frag|

                    word asLowercase = word ifTrue:[

                        keyWords add:word.

                    ] ifFalse:[

                        s := word readStream.

                        w := '' writeStream.

                        [s atEnd] whileFalse:[

                            c := s next.

                            (c isUppercase) ifTrue:[

                                (lastC notNil and:[lastC isUppercase not]) ifTrue:[

                                    keyWords add:w contents.

                                    w := '' writeStream.

                                ].

                            ] ifFalse:[

                                (last2C notNil and:[last2C isUppercase and:[lastC isUppercase]]) ifTrue:[

                                    c isLetter ifTrue:[

                                        frag := w contents.

                                        w := '' writeStream.

                                        w nextPut:(frag last).

                                        keyWords add:(frag allButLast).

                                    ] ifFalse:[

                                       "/ frag := w contents.

                                       "/ w := '' writeStream.

                                       "/ keyWords add:frag.

                                    ].

                                ].

                            ].

                            w nextPut:c.

                            last2C := lastC.

                            lastC := c.

                        ].

                    ].

                  ].

    sep := [:line | 

                |words keyWords|

                words := line asCollectionOfSubstringsSeparatedByAny:'.,;:_ '.

                keyWords := OrderedCollection new.

                words do:[:eachWord | sepUCWords value:eachWord value:keyWords].

                keyWords

            ].

    kwic := self new.

    kwic separatorAlgorithm:sep.

    ^ kwic

!

new

    ^ self basicNew initialize

! !

!KeywordInContextIndexBuilder methodsFor:'accessing'!

excluded:something

    excluded := something asSet.

!

separatorAlgorithm:something

    separatorAlgorithm := something.

! !

!KeywordInContextIndexBuilder methodsFor:'building'!

addLine:aLine reference:opaqueReference

    "add a text line; the line is split at words and entered into the kwic.

     the reference argument is stored as 'value' of the generated entries"

    self addLine:aLine reference:opaqueReference ignoreCase:false

!

addLine:aLine reference:opaqueReference ignoreCase:ignoreCase

    (separatorAlgorithm value:aLine) do:[:eachWord |

        |set word|

        ignoreCase ifTrue:[

            word := eachWord asLowercase.

        ] ifFalse:[

            word := eachWord asLowercase.

        ].

        (excluded includes:word) ifFalse:[

            set := keywordToLinesMapping at:word ifAbsent:nil.

            set isNil ifTrue:[

                set := Set new.

                keywordToLinesMapping at:word put:set

            ].

            set add:(aLine -> opaqueReference).

        ]

    ].

! !

!KeywordInContextIndexBuilder methodsFor:'enumerating'!

entriesDo:aFourArgBlock

    "evaluate the argument, aFourArgBlock for each triple of kwic-word, left-text, right text and reference"

    keywordToLinesMapping keys asSortedCollection do:[:eachKey |

        |setOfMatches lcKey|

        setOfMatches := keywordToLinesMapping at:eachKey.

        lcKey := eachKey asLowercase.

        setOfMatches do:[:eachAssoc |

            |text ref lines idx lIdx context left right word prevLine nextLine|

            text := eachAssoc key.

            ref := eachAssoc value.

            lines := text asCollectionOfLines.

            idx := lines findFirst:[:line | line asLowercase includesString:lcKey].

            idx ~~ 0 ifTrue:[

                context := lines at:idx.

                idx > 1 ifTrue:[

                    prevLine := (lines at:idx-1).

                    context := prevLine , ' ' , context.

                ].

                idx < lines size ifTrue:[

                    nextLine := (lines at:idx+1).

                    context :=  context , ' ' , nextLine.

                ].

                lIdx := context asLowercase findString:lcKey.

                left := (context copyTo:lIdx - 1) withoutSeparators.

                right := (context copyFrom:lIdx + lcKey size) withoutSeparators.

                word := (context copyFrom:lIdx to:lIdx + lcKey size - 1) withoutSeparators.

                aFourArgBlock value:word value:left value:right value:ref.

            ].

        ]

    ]

! !

!KeywordInContextIndexBuilder methodsFor:'initialization'!

initialize

    keywordToLinesMapping := Dictionary new.

    excluded := Set new.

    separatorAlgorithm := [:line | line asCollectionOfSubstringsSeparatedByAny:' .:,;-'].

! !

!KeywordInContextIndexBuilder class methodsFor:'documentation'!

version

    ^ '$Header$'

!

version_CVS

    ^ '$Header$'

! !