khenaidoo | ac63710 | 2019-01-14 15:44:34 -0500 | [diff] [blame] | 1 | // Copyright 2015 The Go Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style |
| 3 | // license that can be found in the LICENSE file. |
| 4 | |
| 5 | //go:generate go run gen.go gen_trieval.go gen_ranges.go |
| 6 | |
| 7 | // Package bidi contains functionality for bidirectional text support. |
| 8 | // |
Scott Baker | 8461e15 | 2019-10-01 14:44:30 -0700 | [diff] [blame] | 9 | // See https://www.unicode.org/reports/tr9. |
khenaidoo | ac63710 | 2019-01-14 15:44:34 -0500 | [diff] [blame] | 10 | // |
| 11 | // NOTE: UNDER CONSTRUCTION. This API may change in backwards incompatible ways |
| 12 | // and without notice. |
| 13 | package bidi // import "golang.org/x/text/unicode/bidi" |
| 14 | |
| 15 | // TODO: |
| 16 | // The following functionality would not be hard to implement, but hinges on |
| 17 | // the definition of a Segmenter interface. For now this is up to the user. |
| 18 | // - Iterate over paragraphs |
| 19 | // - Segmenter to iterate over runs directly from a given text. |
| 20 | // Also: |
| 21 | // - Transformer for reordering? |
| 22 | // - Transformer (validator, really) for Bidi Rule. |
| 23 | |
| 24 | // This API tries to avoid dealing with embedding levels for now. Under the hood |
| 25 | // these will be computed, but the question is to which extent the user should |
| 26 | // know they exist. We should at some point allow the user to specify an |
| 27 | // embedding hierarchy, though. |
| 28 | |
| 29 | // A Direction indicates the overall flow of text. |
| 30 | type Direction int |
| 31 | |
| 32 | const ( |
| 33 | // LeftToRight indicates the text contains no right-to-left characters and |
| 34 | // that either there are some left-to-right characters or the option |
| 35 | // DefaultDirection(LeftToRight) was passed. |
| 36 | LeftToRight Direction = iota |
| 37 | |
| 38 | // RightToLeft indicates the text contains no left-to-right characters and |
| 39 | // that either there are some right-to-left characters or the option |
| 40 | // DefaultDirection(RightToLeft) was passed. |
| 41 | RightToLeft |
| 42 | |
| 43 | // Mixed indicates text contains both left-to-right and right-to-left |
| 44 | // characters. |
| 45 | Mixed |
| 46 | |
| 47 | // Neutral means that text contains no left-to-right and right-to-left |
| 48 | // characters and that no default direction has been set. |
| 49 | Neutral |
| 50 | ) |
| 51 | |
| 52 | type options struct{} |
| 53 | |
| 54 | // An Option is an option for Bidi processing. |
| 55 | type Option func(*options) |
| 56 | |
| 57 | // ICU allows the user to define embedding levels. This may be used, for example, |
| 58 | // to use hierarchical structure of markup languages to define embeddings. |
| 59 | // The following option may be a way to expose this functionality in this API. |
| 60 | // // LevelFunc sets a function that associates nesting levels with the given text. |
| 61 | // // The levels function will be called with monotonically increasing values for p. |
| 62 | // func LevelFunc(levels func(p int) int) Option { |
| 63 | // panic("unimplemented") |
| 64 | // } |
| 65 | |
| 66 | // DefaultDirection sets the default direction for a Paragraph. The direction is |
| 67 | // overridden if the text contains directional characters. |
| 68 | func DefaultDirection(d Direction) Option { |
| 69 | panic("unimplemented") |
| 70 | } |
| 71 | |
| 72 | // A Paragraph holds a single Paragraph for Bidi processing. |
| 73 | type Paragraph struct { |
| 74 | // buffers |
| 75 | } |
| 76 | |
| 77 | // SetBytes configures p for the given paragraph text. It replaces text |
| 78 | // previously set by SetBytes or SetString. If b contains a paragraph separator |
| 79 | // it will only process the first paragraph and report the number of bytes |
| 80 | // consumed from b including this separator. Error may be non-nil if options are |
| 81 | // given. |
| 82 | func (p *Paragraph) SetBytes(b []byte, opts ...Option) (n int, err error) { |
| 83 | panic("unimplemented") |
| 84 | } |
| 85 | |
| 86 | // SetString configures p for the given paragraph text. It replaces text |
| 87 | // previously set by SetBytes or SetString. If b contains a paragraph separator |
| 88 | // it will only process the first paragraph and report the number of bytes |
| 89 | // consumed from b including this separator. Error may be non-nil if options are |
| 90 | // given. |
| 91 | func (p *Paragraph) SetString(s string, opts ...Option) (n int, err error) { |
| 92 | panic("unimplemented") |
| 93 | } |
| 94 | |
| 95 | // IsLeftToRight reports whether the principle direction of rendering for this |
| 96 | // paragraphs is left-to-right. If this returns false, the principle direction |
| 97 | // of rendering is right-to-left. |
| 98 | func (p *Paragraph) IsLeftToRight() bool { |
| 99 | panic("unimplemented") |
| 100 | } |
| 101 | |
| 102 | // Direction returns the direction of the text of this paragraph. |
| 103 | // |
| 104 | // The direction may be LeftToRight, RightToLeft, Mixed, or Neutral. |
| 105 | func (p *Paragraph) Direction() Direction { |
| 106 | panic("unimplemented") |
| 107 | } |
| 108 | |
| 109 | // RunAt reports the Run at the given position of the input text. |
| 110 | // |
| 111 | // This method can be used for computing line breaks on paragraphs. |
| 112 | func (p *Paragraph) RunAt(pos int) Run { |
| 113 | panic("unimplemented") |
| 114 | } |
| 115 | |
| 116 | // Order computes the visual ordering of all the runs in a Paragraph. |
| 117 | func (p *Paragraph) Order() (Ordering, error) { |
| 118 | panic("unimplemented") |
| 119 | } |
| 120 | |
| 121 | // Line computes the visual ordering of runs for a single line starting and |
| 122 | // ending at the given positions in the original text. |
| 123 | func (p *Paragraph) Line(start, end int) (Ordering, error) { |
| 124 | panic("unimplemented") |
| 125 | } |
| 126 | |
| 127 | // An Ordering holds the computed visual order of runs of a Paragraph. Calling |
| 128 | // SetBytes or SetString on the originating Paragraph invalidates an Ordering. |
| 129 | // The methods of an Ordering should only be called by one goroutine at a time. |
| 130 | type Ordering struct{} |
| 131 | |
| 132 | // Direction reports the directionality of the runs. |
| 133 | // |
| 134 | // The direction may be LeftToRight, RightToLeft, Mixed, or Neutral. |
| 135 | func (o *Ordering) Direction() Direction { |
| 136 | panic("unimplemented") |
| 137 | } |
| 138 | |
| 139 | // NumRuns returns the number of runs. |
| 140 | func (o *Ordering) NumRuns() int { |
| 141 | panic("unimplemented") |
| 142 | } |
| 143 | |
| 144 | // Run returns the ith run within the ordering. |
| 145 | func (o *Ordering) Run(i int) Run { |
| 146 | panic("unimplemented") |
| 147 | } |
| 148 | |
| 149 | // TODO: perhaps with options. |
| 150 | // // Reorder creates a reader that reads the runes in visual order per character. |
| 151 | // // Modifiers remain after the runes they modify. |
| 152 | // func (l *Runs) Reorder() io.Reader { |
| 153 | // panic("unimplemented") |
| 154 | // } |
| 155 | |
| 156 | // A Run is a continuous sequence of characters of a single direction. |
| 157 | type Run struct { |
| 158 | } |
| 159 | |
| 160 | // String returns the text of the run in its original order. |
| 161 | func (r *Run) String() string { |
| 162 | panic("unimplemented") |
| 163 | } |
| 164 | |
| 165 | // Bytes returns the text of the run in its original order. |
| 166 | func (r *Run) Bytes() []byte { |
| 167 | panic("unimplemented") |
| 168 | } |
| 169 | |
| 170 | // TODO: methods for |
| 171 | // - Display order |
| 172 | // - headers and footers |
| 173 | // - bracket replacement. |
| 174 | |
| 175 | // Direction reports the direction of the run. |
| 176 | func (r *Run) Direction() Direction { |
| 177 | panic("unimplemented") |
| 178 | } |
| 179 | |
| 180 | // Position of the Run within the text passed to SetBytes or SetString of the |
| 181 | // originating Paragraph value. |
| 182 | func (r *Run) Pos() (start, end int) { |
| 183 | panic("unimplemented") |
| 184 | } |
| 185 | |
| 186 | // AppendReverse reverses the order of characters of in, appends them to out, |
| 187 | // and returns the result. Modifiers will still follow the runes they modify. |
| 188 | // Brackets are replaced with their counterparts. |
| 189 | func AppendReverse(out, in []byte) []byte { |
| 190 | panic("unimplemented") |
| 191 | } |
| 192 | |
| 193 | // ReverseString reverses the order of characters in s and returns a new string. |
| 194 | // Modifiers will still follow the runes they modify. Brackets are replaced with |
| 195 | // their counterparts. |
| 196 | func ReverseString(s string) string { |
| 197 | panic("unimplemented") |
| 198 | } |