"

 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 KWIC (Keyword in Context) or KWOC (Keyword out of Context) indexes.

    (for example, to build such indexes 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 and print as kwic or kwoc.

    To ignore fill words (such as 'and', 'the', 'in', etc.), define those with: #excluded:

    this is defined 

    [author:]

        Claus Gittinger (cg@alan)

    [examples:]

        see examples method

    [see also:]

        https://en.wikipedia.org/wiki/Key_Word_in_Context (english)

        https://de.wikipedia.org/wiki/Permutiertes_Register (german)

"

!

examples

"

    building a kwic; print as kwic and kwoc

                                                                [exBegin]

    |kwic|

    kwic := KeywordInContextIndexBuilder new.

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

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

    kwic addLine:'foo, bar. baz' reference:2.

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

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

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

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

    Transcript showCR:'Printed as KWIC:'.

    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    

        ].

    Transcript cr.

    Transcript showCR:'Printed as KWOC:'.

    kwic 

            Transcript 

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

                space;

                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'!

!

! !

!KeywordInContextIndexBuilder methodsFor:'building'!

addLine:aLine reference:opaqueReference

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

!

addLine:aLine reference:opaqueReference ignoreCase:ignoreCase

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

        |set word|

        ignoreCase ifTrue:[

            word := eachWord asLowercase.

        ] ifFalse:[

        ].

        (excluded includes:word) ifFalse:[

            set add:(aLine -> opaqueReference).

        ]

    ].

! !

!KeywordInContextIndexBuilder methodsFor:'enumerating'!

    "evaluate the argument, for each entry.

     If it is a 4-arg block, it is called with:

        kwic-word, 

        left-text, 

        right text 

        and reference

     If it is a 5-arg block, the original text is passed as additional argument.

     (stupid, but done for backward compatibility)"

    ].    

    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.

                fourArgBlock notNil ifTrue:[

                    fourArgBlock value:word value:left value:right value:ref.

                ] ifFalse:[

                ].    

            ].

        ]

    ]

! !

!KeywordInContextIndexBuilder methodsFor:'initialization'!

initialize

    keywordToLinesMapping := Dictionary new.

    excluded := Set new.

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

! !

!KeywordInContextIndexBuilder class methodsFor:'documentation'!

version

    ^ '$Header$'

!

version_CVS

    ^ '$Header$'

! !