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

    BreakRule.Forced

    Requires a successful plan to end a line at the boundary.

    BreakRule.Forced()
    Receiver
    Not applicable
    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

    Parameter constraints

    Allowed carries an int preference for a selectable penalty. Negative values favor a break and positive values discourage it under the selected cost model. Zero is neutral. Every representable int remains an Allowed value rather than becoming a hard rule at a numeric threshold.

    Forced requires every successful paragraph plan to end a line at that boundary. A plan cannot cross it or omit it to improve cost. If the required line cannot be admitted, planning returns the applicable TypesetError instead of ignoring the constraint.

    Forbidden makes that penalty unselectable. It is not represented by a large Allowed preference. Penalty validation and duplicate-boundary rules determine the treatment of caller-supplied penalties at the same position.

    BreakKind records a category and BreakRule records a planning constraint. Selecting a kind does not turn an Allowed penalty into Forced or Forbidden. The selected cost model interprets the Allowed preference and preserves both hard rules.

    Constructing a rule creates an enum value and has no I/O or mutation. Allowed requires an int payload. An argument of another type is rejected with TPZ5001.

    Result

    Effects

    Failures

    Result and effects

    Link

    A plan cannot skip or cross this boundary to improve its score. If the required transition cannot form a valid line, the planner returns the applicable TypesetError.

    Resolved contracts

    Link

    Related entries

    Link

    std.typeset

    Express preference, mandatory breaks, and forbidden breaks explicitly

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

    Express preference, mandatory breaks, and forbidden breaks explicitly

    Allowed carries an int preference for a selectable penalty. Negative values favor a break and positive values discourage it under the selected cost model. Zero is neutral. Every representable int remains an Allowed value rather than becoming a hard rule at a numeric threshold.

    Forced requires every successful paragraph plan to end a line at that boundary. A plan cannot cross it or omit it to improve cost. If the required line cannot be admitted, planning returns the applicable TypesetError instead of ignoring the constraint.

    Forbidden makes that penalty unselectable. It is not represented by a large Allowed preference. Penalty validation and duplicate-boundary rules determine the treatment of caller-supplied penalties at the same position.

    BreakKind records a category and BreakRule records a planning constraint. Selecting a kind does not turn an Allowed penalty into Forced or Forbidden. The selected cost model interprets the Allowed preference and preserves both hard rules.

    Constructing a rule creates an enum value and has no I/O or mutation. Allowed requires an int payload. An argument of another type is rejected with TPZ5001.

    Why

    An explicit variant makes a hard constraint independent of scoring scale. Callers can change the cost model without changing the meaning of a mandatory or forbidden break. Signed preferences remain a separate choice about plan quality.

    Source evidence

    Keep signed penalty preferences distinct from hard break rules

    Link
    main.tpzKeep signed penalty preferences distinct from hard break rulesOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    3. import std.test
    4. let rules = [ts.BreakRule.Allowed(-10000), ts.BreakRule.Allowed(0), ts.BreakRule.Allowed(10000)]
    5. for rule in (rules) {
    6. match (rule) {
    7. case Allowed(value) => io.writeLine("{value}")
    8. case _ => io.writeLine("unexpected rule")
    9. }
    10. }
    Expected outputexit 0
    -10000
    0
    10000
    
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    Expected stdout
    1. -10000
    2. 0
    3. 10000
    Source evidence

    Reject a noninteger break preference

    Link
    main.tpzReject a noninteger break preferenceOpen in Playground
    1. import std.typeset as ts
    2. let rule = ts.BreakRule.Allowed("avoid")
    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.

    • TPZ5001 stdlib-break-rule-requires-integer at main.tpz:2:33
    Source evidence

    Diagnostics

    Link

    TPZ5001

    Menu

    Download