flags.go 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203
  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. // jsonflags implements all the optional boolean flags.
  5. // These flags are shared across both "json", "jsontext", and "jsonopts".
  6. package jsonflags
  7. import "github.com/go-json-experiment/json/internal"
  8. // Bools represents zero or more boolean flags, all set to true or false.
  9. // The least-significant bit is the boolean value of all flags in the set.
  10. // The remaining bits identify which particular flags.
  11. //
  12. // In common usage, this is OR'd with 0 or 1. For example:
  13. // - (AllowInvalidUTF8 | 0) means "AllowInvalidUTF8 is false"
  14. // - (Multiline | Indent | 1) means "Multiline and Indent are true"
  15. type Bools uint64
  16. func (Bools) JSONOptions(internal.NotForPublicUse) {}
  17. const (
  18. // AllFlags is the set of all flags.
  19. AllFlags = AllCoderFlags | AllArshalV2Flags | AllArshalV1Flags
  20. // AllCoderFlags is the set of all encoder/decoder flags.
  21. AllCoderFlags = (maxCoderFlag - 1) - initFlag
  22. // AllArshalV2Flags is the set of all v2 marshal/unmarshal flags.
  23. AllArshalV2Flags = (maxArshalV2Flag - 1) - (maxCoderFlag - 1)
  24. // AllArshalV1Flags is the set of all v1 marshal/unmarshal flags.
  25. AllArshalV1Flags = (maxArshalV1Flag - 1) - (maxArshalV2Flag - 1)
  26. // NonBooleanFlags is the set of non-boolean flags,
  27. // where the value is some other concrete Go type.
  28. // The value of the flag is stored within jsonopts.Struct.
  29. NonBooleanFlags = 0 |
  30. Indent |
  31. IndentPrefix |
  32. ByteLimit |
  33. DepthLimit |
  34. Marshalers |
  35. Unmarshalers
  36. // DefaultV1Flags is the set of booleans flags that default to true under
  37. // v1 semantics. None of the non-boolean flags differ between v1 and v2.
  38. DefaultV1Flags = 0 |
  39. AllowDuplicateNames |
  40. AllowInvalidUTF8 |
  41. EscapeForHTML |
  42. EscapeForJS |
  43. EscapeInvalidUTF8 |
  44. PreserveRawStrings |
  45. Deterministic |
  46. FormatNilMapAsNull |
  47. FormatNilSliceAsNull |
  48. MatchCaseInsensitiveNames |
  49. CallMethodsWithLegacySemantics |
  50. FormatBytesWithLegacySemantics |
  51. FormatTimeWithLegacySemantics |
  52. MatchCaseSensitiveDelimiter |
  53. MergeWithLegacySemantics |
  54. OmitEmptyWithLegacyDefinition |
  55. ReportErrorsWithLegacySemantics |
  56. StringifyWithLegacySemantics |
  57. UnmarshalArrayFromAnyLength
  58. // AnyWhitespace reports whether the encoded output might have any whitespace.
  59. AnyWhitespace = Multiline | SpaceAfterColon | SpaceAfterComma
  60. // WhitespaceFlags is the set of flags related to whitespace formatting.
  61. // In contrast to AnyWhitespace, this includes Indent and IndentPrefix
  62. // as those settings take no effect if Multiline is false.
  63. WhitespaceFlags = AnyWhitespace | Indent | IndentPrefix
  64. // AnyEscape is the set of flags related to escaping in a JSON string.
  65. AnyEscape = EscapeForHTML | EscapeForJS | EscapeInvalidUTF8
  66. // CanonicalizeNumbers is the set of flags related to raw number canonicalization.
  67. CanonicalizeNumbers = CanonicalizeRawInts | CanonicalizeRawFloats
  68. )
  69. // Encoder and decoder flags.
  70. const (
  71. initFlag Bools = 1 << iota // reserved for the boolean value itself
  72. AllowDuplicateNames // encode or decode
  73. AllowInvalidUTF8 // encode or decode
  74. WithinArshalCall // encode or decode; for internal use by json.Marshal and json.Unmarshal
  75. OmitTopLevelNewline // encode only; for internal use by json.Marshal and json.MarshalWrite
  76. PreserveRawStrings // encode only
  77. CanonicalizeRawInts // encode only
  78. CanonicalizeRawFloats // encode only
  79. ReorderRawObjects // encode only
  80. EscapeForHTML // encode only
  81. EscapeForJS // encode only
  82. EscapeInvalidUTF8 // encode only; only exposed in v1
  83. Multiline // encode only
  84. SpaceAfterColon // encode only
  85. SpaceAfterComma // encode only
  86. Indent // encode only; non-boolean flag
  87. IndentPrefix // encode only; non-boolean flag
  88. ByteLimit // encode or decode; non-boolean flag
  89. DepthLimit // encode or decode; non-boolean flag
  90. maxCoderFlag
  91. )
  92. // Marshal and Unmarshal flags (for v2).
  93. const (
  94. _ Bools = (maxCoderFlag >> 1) << iota
  95. StringifyNumbers // marshal or unmarshal
  96. Deterministic // marshal only
  97. FormatNilMapAsNull // marshal only
  98. FormatNilSliceAsNull // marshal only
  99. OmitZeroStructFields // marshal only
  100. MatchCaseInsensitiveNames // marshal or unmarshal
  101. DiscardUnknownMembers // marshal only
  102. RejectUnknownMembers // unmarshal only
  103. Marshalers // marshal only; non-boolean flag
  104. Unmarshalers // unmarshal only; non-boolean flag
  105. maxArshalV2Flag
  106. )
  107. // Marshal and Unmarshal flags (for v1).
  108. const (
  109. _ Bools = (maxArshalV2Flag >> 1) << iota
  110. CallMethodsWithLegacySemantics // marshal or unmarshal
  111. FormatBytesWithLegacySemantics // marshal or unmarshal
  112. FormatTimeWithLegacySemantics // marshal or unmarshal
  113. MatchCaseSensitiveDelimiter // marshal or unmarshal
  114. MergeWithLegacySemantics // unmarshal
  115. OmitEmptyWithLegacyDefinition // marshal
  116. ReportErrorsWithLegacySemantics // marshal or unmarshal
  117. StringifyWithLegacySemantics // marshal or unmarshal
  118. StringifyBoolsAndStrings // marshal or unmarshal; for internal use by jsonv2.makeStructArshaler
  119. UnmarshalAnyWithRawNumber // unmarshal; for internal use by jsonv1.Decoder.UseNumber
  120. UnmarshalArrayFromAnyLength // unmarshal
  121. maxArshalV1Flag
  122. )
  123. // Flags is a set of boolean flags.
  124. // If the presence bit is zero, then the value bit must also be zero.
  125. // The least-significant bit of both fields is always zero.
  126. //
  127. // Unlike Bools, which can represent a set of bools that are all true or false,
  128. // Flags represents a set of bools, each individually may be true or false.
  129. type Flags struct{ Presence, Values uint64 }
  130. // Join joins two sets of flags such that the latter takes precedence.
  131. func (dst *Flags) Join(src Flags) {
  132. // Copy over all source presence bits over to the destination (using OR),
  133. // then invert the source presence bits to clear out source value (using AND-NOT),
  134. // then copy over source value bits over to the destination (using OR).
  135. // e.g., dst := Flags{Presence: 0b_1100_0011, Value: 0b_1000_0011}
  136. // e.g., src := Flags{Presence: 0b_0101_1010, Value: 0b_1001_0010}
  137. dst.Presence |= src.Presence // e.g., 0b_1100_0011 | 0b_0101_1010 -> 0b_110_11011
  138. dst.Values &= ^src.Presence // e.g., 0b_1000_0011 & 0b_1010_0101 -> 0b_100_00001
  139. dst.Values |= src.Values // e.g., 0b_1000_0001 | 0b_1001_0010 -> 0b_100_10011
  140. }
  141. // Set sets both the presence and value for the provided bool (or set of bools).
  142. func (fs *Flags) Set(f Bools) {
  143. // Select out the bits for the flag identifiers (everything except LSB),
  144. // then set the presence for all the identifier bits (using OR),
  145. // then invert the identifier bits to clear out the values (using AND-NOT),
  146. // then copy over all the identifier bits to the value if LSB is 1.
  147. // e.g., fs := Flags{Presence: 0b_0101_0010, Value: 0b_0001_0010}
  148. // e.g., f := 0b_1001_0001
  149. id := uint64(f) &^ uint64(1) // e.g., 0b_1001_0001 & 0b_1111_1110 -> 0b_1001_0000
  150. fs.Presence |= id // e.g., 0b_0101_0010 | 0b_1001_0000 -> 0b_1101_0011
  151. fs.Values &= ^id // e.g., 0b_0001_0010 & 0b_0110_1111 -> 0b_0000_0010
  152. fs.Values |= uint64(f&1) * id // e.g., 0b_0000_0010 | 0b_1001_0000 -> 0b_1001_0010
  153. }
  154. // Get reports whether the bool (or any of the bools) is true.
  155. // This is generally only used with a singular bool.
  156. // The value bit of f (i.e., the LSB) is ignored.
  157. func (fs Flags) Get(f Bools) bool {
  158. return fs.Values&uint64(f) > 0
  159. }
  160. // Has reports whether the bool (or any of the bools) is set.
  161. // The value bit of f (i.e., the LSB) is ignored.
  162. func (fs Flags) Has(f Bools) bool {
  163. return fs.Presence&uint64(f) > 0
  164. }
  165. // Clear clears both the presence and value for the provided bool or bools.
  166. // The value bit of f (i.e., the LSB) is ignored.
  167. func (fs *Flags) Clear(f Bools) {
  168. // Invert f to produce a mask to clear all bits in f (using AND).
  169. // e.g., fs := Flags{Presence: 0b_0101_0010, Value: 0b_0001_0010}
  170. // e.g., f := 0b_0001_1000
  171. mask := uint64(^f) // e.g., 0b_0001_1000 -> 0b_1110_0111
  172. fs.Presence &= mask // e.g., 0b_0101_0010 & 0b_1110_0111 -> 0b_0100_0010
  173. fs.Values &= mask // e.g., 0b_0001_0010 & 0b_1110_0111 -> 0b_0000_0010
  174. }