Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.typeset

    BreakOpportunity.kind

    The reason for a classified boundary.

    BreakOpportunity.kind: BreakKind
    Receiver
    BreakOpportunity
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.typeset in language mode 5.21.

    The current compiler selects std/typeset.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    BreakOpportunity

    Parameter constraints

    Additional contracts are Pending.

    BreakKind.CjkCluster() constructs the variant for the existing CJK and East Asian cluster classification. BreakKind.KoreanCluster() is absent and rejected.

    Renaming this variant preserves the classification predicates and the effect of the selected Unicode, locale, custom punctuation, and shaping-boundary policies.

    A CjkCluster category does not itself permit a break. classifyBreaks returns the opportunities admitted by its supplied policy.

    Related rule: Name the CJK cluster break category

    classifyBreaks reads measured clusters in array order and returns Result<Array<BreakOpportunity>, TypesetError>. It does not shape text, normalize strings, split a cluster, or change any supplied record or array.

    Each BreakCluster.text is the scalar string for one indivisible measured unit. Empty text still occupies one cluster index. advance includes trackingAfter. A span width sums its advances and removes the trackingAfter of its final cluster.

    advance and advance minus trackingAfter must be nonnegative point lengths. Zero advance and signed trackingAfter are accepted. Invalid extents return TypesetError.InvalidInput. Length arithmetic follows the common Length contract.

    classifyBreaks sums stored point ticks and compares them with the stored point targets. It has no DistanceGrid argument and does not quantize to a paragraph grid. Exact equality with a target counts as fitting.

    boundaryAllowed has exactly one entry for each cluster. Entry i governs the boundary after cluster i. The last entry must be true for nonempty input. A wrong mask length or a false last entry returns TypesetError.InvalidInput.

    Validation checks mask length and terminal permission, word targets, forbidBefore, forbidAfter, generated hyphen indices, and measured extents in that order. Array checks visit entries in input order. Unicode mandatory crossings are checked before boundary conflicts are visited in increasing cluster order. An empty result follows successful structural and policy validation.

    An empty cluster array with a valid empty boundary mask returns Ok with an empty opportunity array. It does not create a synthetic unit or terminal opportunity.

    Successful nonempty results contain increasing, unique unitEnd values from one through the cluster count. unitEnd is an exclusive cluster index rather than a byte or scalar offset. The final opportunity has unitEnd equal to the cluster count and kind ForcedEnd.

    Repeated calls with equal cluster values and equal policies produce the same ordered opportunities and categories. Validation and classification do not read host locale, perform I/O, invoke caller callbacks, or mutate input values. Argument expressions use the ordinary language evaluation order.

    A BreakOpportunity carries a boundary and its category. It does not carry a penalty width or BreakRule. A caller preserving mandatory boundaries maps every ForcedEnd opportunity to a Forced penalty before calling breakParagraph.

    Related rule: Classify measured clusters into an ordered boundary sequence

    Result

    Additional contracts are Pending.

    The declared result type is BreakKind.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Select this field from a value of its named type without call parentheses.

    The category records how the boundary was classified. It does not supply a BreakRule. Preserve ForcedEnd boundaries by mapping them to Forced penalties when building paragraph items.

    Why

    Link

    A named break category lets planning apply the chosen cost policy to the same classified boundary. The category describes the boundary while the locale policy decides its admissibility.

    Related entries

    Link

    std.typeset

    Name the CJK cluster break category

    Link
    Ruletopaz.stdlib.contract.cjk-cluster.rule

    Name the CJK cluster break category

    BreakKind.CjkCluster() constructs the variant for the existing CJK and East Asian cluster classification. BreakKind.KoreanCluster() is absent and rejected.

    Renaming this variant preserves the classification predicates and the effect of the selected Unicode, locale, custom punctuation, and shaping-boundary policies.

    A CjkCluster category does not itself permit a break. classifyBreaks returns the opportunities admitted by its supplied policy.

    Why

    A break category names the text it classifies. CjkCluster covers the existing Chinese, Japanese, and Korean classification path and matches the module's CjkInterCharacter vocabulary. Locale policy continues to determine where a break is allowed.

    Examples Use the CJK cluster variantReject the former KoreanCluster name

    Diagnostics TPZ5006

    Source evidence

    Use the CJK cluster variant

    Link

    check · checking · Verification: not-run

    main.tpzUse the CJK cluster variantOpen in Playground
    1. import std.typeset as ts
    2. let kind: ts.BreakKind = ts.BreakKind.CjkCluster()
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject the former KoreanCluster name

    Link

    reject · checking · Verification: not-run

    main.tpzReject the former KoreanCluster nameOpen in Playground
    1. import std.typeset as ts
    2. let kind = ts.BreakKind.KoreanCluster()
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-korean-cluster at main.tpz:2:12

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Unknown member or field

    Classify measured clusters into an ordered boundary sequence

    Link
    Ruletopaz.stdlib.contract.typeset-break-inputs.rule

    Classify measured clusters into an ordered boundary sequence

    classifyBreaks reads measured clusters in array order and returns Result<Array<BreakOpportunity>, TypesetError>. It does not shape text, normalize strings, split a cluster, or change any supplied record or array.

    Each BreakCluster.text is the scalar string for one indivisible measured unit. Empty text still occupies one cluster index. advance includes trackingAfter. A span width sums its advances and removes the trackingAfter of its final cluster.

    advance and advance minus trackingAfter must be nonnegative point lengths. Zero advance and signed trackingAfter are accepted. Invalid extents return TypesetError.InvalidInput. Length arithmetic follows the common Length contract.

    classifyBreaks sums stored point ticks and compares them with the stored point targets. It has no DistanceGrid argument and does not quantize to a paragraph grid. Exact equality with a target counts as fitting.

    boundaryAllowed has exactly one entry for each cluster. Entry i governs the boundary after cluster i. The last entry must be true for nonempty input. A wrong mask length or a false last entry returns TypesetError.InvalidInput.

    Validation checks mask length and terminal permission, word targets, forbidBefore, forbidAfter, generated hyphen indices, and measured extents in that order. Array checks visit entries in input order. Unicode mandatory crossings are checked before boundary conflicts are visited in increasing cluster order. An empty result follows successful structural and policy validation.

    An empty cluster array with a valid empty boundary mask returns Ok with an empty opportunity array. It does not create a synthetic unit or terminal opportunity.

    Successful nonempty results contain increasing, unique unitEnd values from one through the cluster count. unitEnd is an exclusive cluster index rather than a byte or scalar offset. The final opportunity has unitEnd equal to the cluster count and kind ForcedEnd.

    Repeated calls with equal cluster values and equal policies produce the same ordered opportunities and categories. Validation and classification do not read host locale, perform I/O, invoke caller callbacks, or mutate input values. Argument expressions use the ordinary language evaluation order.

    A BreakOpportunity carries a boundary and its category. It does not carry a penalty width or BreakRule. A caller preserving mandatory boundaries maps every ForcedEnd opportunity to a Forced penalty before calling breakParagraph.

    Why

    A measured cluster is the unit that shaping can safely keep together. Exclusive indices connect classification to paragraph items without converting through text offsets. A complete terminal boundary and deterministic order make the output suitable for reproducible layout.

    Examples Classify atomic clusters in repeatable boundary orderClassify an empty cluster sequenceReject a mask with the wrong number of entriesReject negative measured and untracked cluster extentsReject a masked paragraph end in every rulesetKeep exact point measurements at the classifier boundary

    Source evidence

    Classify atomic clusters in repeatable boundary order

    Link

    run · running · Verification: not-run

    main.tpzClassify atomic clusters in repeatable boundary orderOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    3. import std.test
    5. let clusters = [ts.BreakCluster { text: "한", advance: 1pt, trackingAfter: 0pt }, ts.BreakCluster { text: "글", advance: 1pt, trackingAfter: 0pt }]
    6. let selected = ts.BreakPolicy {
    7. mode: ts.BreakMode.Character(),
    8. rules: ts.KinsokuRules.AtlasDefault(),
    9. forbidBefore: [],
    10. forbidAfter: [],
    11. boundaryAllowed: [true, true],
    12. generatedHyphenEnds: [],
    13. protectFittingLatin: false,
    14. preserveShortWords: false,
    15. narrowestWordTarget: 0pt,
    16. bodyWordTarget: 0pt
    17. }
    18. for pass in ([0, 1]) {
    19. let breaks = test.assertOk(ts.classifyBreaks(clusters, selected))
    20. for boundary in (breaks) {
    21. let category = match (boundary.kind) {
    22. case CjkCluster() => "CJK"
    23. case ForcedEnd() => "end"
    24. case _ => "unexpected kind"
    25. }
    26. io.writeLine("{pass} {boundary.unitEnd} {category}")
    27. }
    28. }
    29. io.writeLine(clusters[0].text)
    Expected outputexit 0
    0 1 CJK
0 2 end
1 1 CJK
1 2 end
한
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0 1 CJK
    2. 0 2 end
    3. 1 1 CJK
    4. 1 2 end
    5. 한

    This exact example has not been executed.

    Source evidence

    Classify an empty cluster sequence

    Link

    run · running · Verification: not-run

    main.tpzClassify an empty cluster sequenceOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    3. import std.test
    5. let clusters: Array<ts.BreakCluster> = []
    6. let selected = ts.BreakPolicy {
    7. mode: ts.BreakMode.Character(),
    8. rules: ts.KinsokuRules.AtlasDefault(),
    9. forbidBefore: [],
    10. forbidAfter: [],
    11. boundaryAllowed: [],
    12. generatedHyphenEnds: [],
    13. protectFittingLatin: false,
    14. preserveShortWords: false,
    15. narrowestWordTarget: 0pt,
    16. bodyWordTarget: 0pt
    17. }
    18. let breaks = test.assertOk(ts.classifyBreaks(clusters, selected))
    19. io.writeLine("{breaks.length}")
    Expected outputexit 0
    0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0

    This exact example has not been executed.

    Source evidence

    Reject a mask with the wrong number of entries

    Link

    run · running · Verification: not-run

    main.tpzReject a mask with the wrong number of entriesOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    3. import std.test
    5. function outcome(value: Result<Array<ts.BreakOpportunity>, ts.TypesetError>) -> string {
    6. match (value) {
    7. case Ok(_) => "Ok"
    8. case Err(InvalidInput(_)) => "InvalidInput"
    9. case Err(InvalidPolicy(_)) => "InvalidPolicy"
    10. case Err(_) => "unexpected error"
    11. }
    12. }
    14. let clusters = [ts.BreakCluster { text: "a", advance: 1pt, trackingAfter: 0pt }]
    15. let selected = ts.BreakPolicy {
    16. mode: ts.BreakMode.Character(),
    17. rules: ts.KinsokuRules.AtlasDefault(),
    18. forbidBefore: [],
    19. forbidAfter: [],
    20. boundaryAllowed: [],
    21. generatedHyphenEnds: [],
    22. protectFittingLatin: false,
    23. preserveShortWords: false,
    24. narrowestWordTarget: 0pt,
    25. bodyWordTarget: 0pt
    26. }
    27. io.writeLine(outcome(ts.classifyBreaks(clusters, selected)))
    Expected outputexit 0
    InvalidInput
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. InvalidInput

    This exact example has not been executed.

    Source evidence

    Reject negative measured and untracked cluster extents

    Link

    run · running · Verification: not-run

    main.tpzReject negative measured and untracked cluster extentsOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    3. import std.test
    5. function outcome(value: Result<Array<ts.BreakOpportunity>, ts.TypesetError>) -> string {
    6. match (value) {
    7. case Ok(_) => "Ok"
    8. case Err(InvalidInput(_)) => "InvalidInput"
    9. case Err(InvalidPolicy(_)) => "InvalidPolicy"
    10. case Err(_) => "unexpected error"
    11. }
    12. }
    14. let selected = ts.BreakPolicy {
    15. mode: ts.BreakMode.Character(),
    16. rules: ts.KinsokuRules.AtlasDefault(),
    17. forbidBefore: [],
    18. forbidAfter: [],
    19. boundaryAllowed: [true],
    20. generatedHyphenEnds: [],
    21. protectFittingLatin: false,
    22. preserveShortWords: false,
    23. narrowestWordTarget: 0pt,
    24. bodyWordTarget: 0pt
    25. }
    26. io.writeLine(outcome(ts.classifyBreaks([ts.BreakCluster { text: "a", advance: -1pt, trackingAfter: 0pt }], selected)))
    27. io.writeLine(outcome(ts.classifyBreaks([ts.BreakCluster { text: "b", advance: 1pt, trackingAfter: 2pt }], selected)))
    Expected outputexit 0
    InvalidInput
InvalidInput
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. InvalidInput
    2. InvalidInput

    This exact example has not been executed.

    Source evidence

    Reject a masked paragraph end in every ruleset

    Link

    run · running · Verification: not-run

    main.tpzReject a masked paragraph end in every rulesetOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    3. import std.test
    5. function outcome(value: Result<Array<ts.BreakOpportunity>, ts.TypesetError>) -> string {
    6. match (value) {
    7. case Ok(_) => "Ok"
    8. case Err(InvalidInput(_)) => "InvalidInput"
    9. case Err(InvalidPolicy(_)) => "InvalidPolicy"
    10. case Err(_) => "unexpected error"
    11. }
    12. }
    14. let clusters = [ts.BreakCluster { text: "a", advance: 1pt, trackingAfter: 0pt }]
    15. let atlas = ts.BreakPolicy {
    16. mode: ts.BreakMode.Character(),
    17. rules: ts.KinsokuRules.AtlasDefault(),
    18. forbidBefore: [],
    19. forbidAfter: [],
    20. boundaryAllowed: [false],
    21. generatedHyphenEnds: [],
    22. protectFittingLatin: false,
    23. preserveShortWords: false,
    24. narrowestWordTarget: 0pt,
    25. bodyWordTarget: 0pt
    26. }
    27. let unicode = ts.BreakPolicy {
    28. mode: ts.BreakMode.Character(),
    29. rules: ts.KinsokuRules.Unicode16Ja(),
    30. forbidBefore: [],
    31. forbidAfter: [],
    32. boundaryAllowed: [false],
    33. generatedHyphenEnds: [],
    34. protectFittingLatin: false,
    35. preserveShortWords: false,
    36. narrowestWordTarget: 0pt,
    37. bodyWordTarget: 0pt
    38. }
    39. io.writeLine(outcome(ts.classifyBreaks(clusters, atlas)))
    40. io.writeLine(outcome(ts.classifyBreaks(clusters, unicode)))
    Expected outputexit 0
    InvalidInput
InvalidInput
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. InvalidInput
    2. InvalidInput

    This exact example has not been executed.

    Source evidence

    Keep exact point measurements at the classifier boundary

    Link

    run · running · Verification: not-run

    main.tpzKeep exact point measurements at the classifier boundaryOpen in Playground
    1. import std.typeset as ts
    2. import std.test
    3. import std.io
    5. let clusters = [
    6. ts.BreakCluster { text: "a", advance: 0.5002pt, trackingAfter: 0pt },
    7. ts.BreakCluster { text: "b", advance: 0.5002pt, trackingAfter: 0pt }
    8. ]
    9. let policy = ts.BreakPolicy {
    10. mode: ts.BreakMode.Word(), rules: ts.KinsokuRules.AtlasDefault(),
    11. forbidBefore: [], forbidAfter: [], boundaryAllowed: [true, true],
    12. generatedHyphenEnds: [], protectFittingLatin: false, preserveShortWords: false,
    13. narrowestWordTarget: 0pt, bodyWordTarget: 1pt
    14. }
    15. let result = test.assertOk(ts.classifyBreaks(clusters, policy))
    16. for boundary in (result) {
    17. io.writeLine("{boundary.unitEnd}")
    18. }
    Expected outputexit 0
    1
2
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 1
    2. 2

    This exact example has not been executed.

    Source evidence

    Menu

    Download