export.go

     1  // Copyright 2023 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:build goexperiment.jsonv2
     6  
     7  package jsontext
     8  
     9  import (
    10  	"io"
    11  
    12  	"encoding/json/internal"
    13  )
    14  
    15  // TODO(https://go.dev/issue/73435): Remove the Internal symbol.
    16  //
    17  // The Go language lacks a 3rd category of visibility where
    18  // certain symbols can only be referenced from within the same module.
    19  // One solution to this is to put the entirety of a package with
    20  // both public and module-only symbols exposed as an internal package.
    21  // A separate, public package can re-export all of the public symbols
    22  // via type aliases and thus ensuring module-only symbols cannot be
    23  // referenced by the end-user. While this works, it unfortunately
    24  // leads to a poor user experience since the Go pkgsite is unable to
    25  // forward the documentation for symbols like methods and fields.
    26  // We need to improve the pkgsite experience before we can delete
    27  // the Internal symbol.
    28  
    29  // Internal is for internal use only.
    30  // This is exempt from the Go compatibility agreement.
    31  var Internal exporter
    32  
    33  type exporter struct{}
    34  
    35  // Export exposes internal functionality from "jsontext" to "json".
    36  // This cannot be dynamically called by other packages since
    37  // they cannot obtain a reference to the internal.AllowInternalUse value.
    38  func (exporter) Export(p *internal.NotForPublicUse) export {
    39  	if p != &internal.AllowInternalUse {
    40  		panic("unauthorized call to Export")
    41  	}
    42  	return export{}
    43  }
    44  
    45  // The export type exposes functionality to packages with visibility to
    46  // the internal.AllowInternalUse variable. The "json" package uses this
    47  // to modify low-level state in the Encoder and Decoder types.
    48  // It mutates the state directly instead of calling ReadToken or WriteToken
    49  // since this is more performant. The public APIs need to track state to ensure
    50  // that users are constructing a valid JSON value, but the "json" implementation
    51  // guarantees that it emits valid JSON by the structure of the code itself.
    52  type export struct{}
    53  
    54  // Encoder returns a pointer to the underlying encoderState.
    55  func (export) Encoder(e *Encoder) *encoderState { return &e.s }
    56  
    57  // Decoder returns a pointer to the underlying decoderState.
    58  func (export) Decoder(d *Decoder) *decoderState { return &d.s }
    59  
    60  func (export) GetBufferedEncoder(o ...Options) *Encoder {
    61  	return getBufferedEncoder(o...)
    62  }
    63  func (export) PutBufferedEncoder(e *Encoder) {
    64  	putBufferedEncoder(e)
    65  }
    66  
    67  func (export) GetStreamingEncoder(w io.Writer, o ...Options) *Encoder {
    68  	return getStreamingEncoder(w, o...)
    69  }
    70  func (export) PutStreamingEncoder(e *Encoder) {
    71  	putStreamingEncoder(e)
    72  }
    73  
    74  func (export) GetBufferedDecoder(b []byte, o ...Options) *Decoder {
    75  	return getBufferedDecoder(b, o...)
    76  }
    77  func (export) PutBufferedDecoder(d *Decoder) {
    78  	putBufferedDecoder(d)
    79  }
    80  
    81  func (export) GetStreamingDecoder(r io.Reader, o ...Options) *Decoder {
    82  	return getStreamingDecoder(r, o...)
    83  }
    84  func (export) PutStreamingDecoder(d *Decoder) {
    85  	putStreamingDecoder(d)
    86  }
    87  
    88  func (export) IsIOError(err error) bool {
    89  	_, ok := err.(*ioError)
    90  	return ok
    91  }
    92
View as plain text