vendor/golang.org/x/text/unicode/bidi/bidi.go

   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 //
   9 // See http://www.unicode.org/reports/tr9.
  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 }