.. _usage_label:

=====
Usage
=====

To use :mod:`cnt.rulebase` in a project::

    from cnt import rulebase


Sentence segmentation (see :func:`cnt.rulebase.sentseg` and :func:`cnt.rulebase.sentseg_lazy`) ::

    text = '''
    史卡肯表示:「我今天打的和当初在温布登打的一样,除了这一次幸运之神落在我这边以外。」他说:「其
    实在温布登时最后的胜利也有可能属于我,因为当时打到了第五盘却仍然僵持在二十比十八的对峙。」菲
    利普西斯在当初的温布登比赛中,在面对史卡肯时曾经发出四十四个爱司球,但是为他搏得「重炮手」美誉
    的发球,并没有在今天的球赛中助他一臂之力。菲利普西斯在第一盘第七局以三十比四十落后时,竟然击出
    双发失误;另外在第九局他又再度犯下双发失误球,让史卡肯得以坐拥两次的破发点,并且顺利赢得第一盘
    。在这场历时六十六分钟的比赛里,史卡肯表示:「我大力主攻他的第二发球,同时我也对他的第一发球施
    压,使我取得更多的机会。」这也是史卡肯和菲利普西斯在六度对峙中的第二次获胜。
    '''

    # Return [ (str, (start_idx, end_idx)), ... ]
    rulebase.sentseg(text)

    # Example.
    [('史卡肯表示:「我今天打的和当初在温布登打的一样,除了这一次幸运之神落在我这边以外。', (1, 42)),
    ('」他说:「其实在温布登时最后的胜利也有可能属于我,因为当时打到了第五盘却仍然僵持在二十比十八的对峙。', (42, 92)),
    ('」菲利普西斯在当初的温布登比赛中,在面对史卡肯时曾经发出四十四个爱司球,但是为他搏得「重炮手」美誉的发球,并没有在今天的球赛中助他一臂之力。',
    (92, 162)),
    ('菲利普西斯在第一盘第七局以三十比四十落后时,竟然击出双发失误;', (162, 193)),
    ('另外在第九局他又再度犯下双发失误球,让史卡肯得以坐拥两次的破发点,并且顺利赢得第一盘。', (193, 236)),
    ('在这场历时六十六分钟的比赛里,史卡肯表示:「我大力主攻他的第二发球,同时我也对他的第一发球施压,使我取得更多的机会。', (236, 294)),
    ('」这也是史卡肯和菲利普西斯在六度对峙中的第二次获胜。', (294, 320))]

    # Return a generator.
    rulebase.sentseg_lazy(text)

Pattern filtering (see :obj:`cnt.rulebase.collector`) ::

    text = '」他说:「其实在Wimbledon时最后的胜利也有可能属于我,因为当时打到了第5盘却仍然僵持在20比18的对峙。'

    # 1. Collect Chinese + English + Digits.
    rulebase.collector.chinese_sentence_chars.result(text)

    # 1. Return.
    [('他说', (1, 3)),
    ('其实在Wimbledon时最后的胜利也有可能属于我', (5, 30)),
    ('因为当时打到了第5盘却仍然僵持在20比18的对峙', (31, 55))]


    # 2. Collect only Chinese.
    rulebase.collector.chinese_chars.result(text)

    # 2. Return.
    [('他说', (1, 3)),
    ('其实在', (5, 8)),
    ('时最后的胜利也有可能属于我', (17, 30)),
    ('因为当时打到了第', (31, 39)),
    ('盘却仍然僵持在', (40, 47)),
    ('比', (49, 50)),
    ('的对峙', (52, 55))]


    # 3. Generate a new collector for any Unicode codepoint intervals.
    my_collector_lazy, my_collector = rulebase.collector.generate_collector(
            rulebase.const.ITV_CHINESE_CHARS,
            rulebase.const.ITV_ENGLISH_CHARS,
    )

    # 3. Return.
    [('他说', (1, 3)),
    ('其实在Wimbledon时最后的胜利也有可能属于我', (5, 30)),
    ('因为当时打到了第', (31, 39)),
    ('盘却仍然僵持在', (40, 47)),
    ('比', (49, 50)),
    ('的对峙', (52, 55))]


Pattern replacement (see :obj:`cnt.rulebase.replacer`) ::

    text = '」他说:「其实在Wimbledon时最后的胜利也有可能属于我,因为当时打到了第5盘却仍然僵持在20比18的对峙。'

    # 1. Replace English characters by the empty string.
    rulebase.replacer.english_chars.result(text)

    # 1. Return. (segment, ((start_idx, end_idx), is_replaced))
    [('」他说:「其实在', ((0, 8), False)),
    ('', ((8, 17), True)),
    ('时最后的胜利也有可能属于我,因为当时打到了第5盘却仍然僵持在20比18的对峙。', ((17, 56), False))]


    # 2. Return merged string.
    rulebase.replacer.english_chars_to_string.result(text)

    # 2. Return. str.
    '」他说:「其实在时最后的胜利也有可能属于我,因为当时打到了第5盘却仍然僵持在20比18的对峙。'


    # 3. Generate a new replacer for any Unicode codepoint intervals & arbitrary replacement function.
    my_replacer_lazy, my_replacer, my_replacer_to_string = rulebase.replacer.generate_replacer(
            lambda x: '<{}>'.format(len(x)),
            rulebase.const.ITV_ENGLISH_CHARS,
    )

    # 3. Return.
    [('」他说:「其实在', ((0, 8), False)),
    ('<9>', ((8, 17), True)),
    ('时最后的胜利也有可能属于我,因为当时打到了第5盘却仍然僵持在20比18的对峙。', ((17, 56), False))]
