@@ -92,6 +92,11 @@ import Streamly.Internal.Data.Unbox.TH (DataCon(..))
9292-- * 'inlineSerializeAt' (Just Inline)
9393-- * 'inlineDeserializeAt' (Just Inline)
9494--
95+-- The following experimental options are also available:
96+--
97+-- * 'encodeConstrNames' False
98+-- * 'encodeRecordFields' False
99+--
95100data SerializeConfig =
96101 SerializeConfig
97102 { cfgInlineSize :: Maybe Inline
@@ -127,25 +132,26 @@ inlineDeserializeAt v cfg = cfg {cfgInlineDeserialize = v}
127132-- | __Experimental__
128133--
129134-- In sum types, use Latin-1 encoded original constructor names rather than
130−-- binary values to identify constructors. This option is not useful on a
131−-- product type.
135+-- binary values to identify constructors. This option is not applicable to
136+-- product types.
132137--
133−-- This option enables the following backward compatible behavior:
138+-- This option enables the following behavior:
134139--
135140-- * __Reordering__: Order of the fields can be changed without affecting
136141-- serialization.
137142-- * __Addition__: If a field is added in the new version, the old version of
138143-- the data type can still be deserialized by the new version. The new value
139144-- would never occur in the old one.
140−-- * __Deletion__: If a field is deleted in the new version and deserialization
145+-- * __Deletion__: If a field is deleted in the new version, deserialization
141146-- of the old version will result in an error. TBD: We can possibly designate a
142−-- catch-all field to handle this case.
147+-- catch-all case to handle this scenario.
143148--
144149-- Note that if you change a type, change the semantics of a type, or delete a
145150-- field and add a new field with the same name, deserialization of old data
146151-- may result in silent unexpected behavior.
147152--
148153-- This option has to be the same on both encoding and decoding side.
154+--
149155-- The default is 'False'.
150156--
151157encodeConstrNames :: Bool -> SerializeConfig -> SerializeConfig
@@ -161,11 +167,11 @@ encodeConstrNames v cfg = cfg {cfgConstructorTagAsString = v}
161167-- | __Experimental__
162168--
163169-- In explicit record types, use Latin-1 encoded record field names rather than
164−-- binary values to identify the record fields. Note that this option cannot be
165−-- used on a sum type. Also, it does not work on a product type which is not a
166−-- record, because there are no field names to begin with.
170+-- binary values to identify the record fields. Note that this option is not
171+-- applicable to sum types. Also, it does not work on a product type which is
172+-- not a record, because there are no field names to begin with.
167173--
168−-- This option enables the following backward compatible behavior:
174+-- This option enables the following behavior:
169175--
170176-- * __Reordering__: Order of the fields can be changed without affecting
171177-- serialization.
@@ -173,10 +179,10 @@ encodeConstrNames v cfg = cfg {cfgConstructorTagAsString = v}
173179-- version of the data type can still be deserialized by the new version, the
174180-- field value in the older version is assumed to be 'Nothing'. If any other
175181-- type of field is added, deserialization of the older version results in an
176−-- error but only when that field is accessed in the deserialized record.
182+-- error but only when that field is actually accessed in the deserialized
183+-- record.
177184-- * __Deletion__: If a field is deleted in the new version and it is
178185-- encountered in a previously serialized version then the field is discarded.
179−-- TBD: We can possibly designate a catch-all field to handle this case.
180186--
181187-- This option has to be the same on both encoding and decoding side.
182188--