mormot2对bson的封装
mormot.db.nosql.bson.pas单元封装了bson。
TBSONWriter = class(TFileBufferWriter)
下面是这个类的接口：
/// rewind the Stream to the position when Create() was called
// - this will also reset the internal document offset table
procedure CancelAll; override;
/// write a boolean value
procedure BSONWrite(const name: RawUTF8; const value: boolean); overload;
/// write a floating point value
procedure BSONWrite(const name: RawUTF8; const value: Double); overload;
/// write a 32 bit integer value
procedure BSONWrite(const name: RawUTF8; const value: integer); overload;
/// write a 64 bit integer value
procedure BSONWrite(const name: RawUTF8; const value: Int64); overload;
/// write a string (UTF-8) value
procedure BSONWrite(const name: RawUTF8; const value: RawUTF8;
isJavaScript: boolean = false); overload;
/// write a string (UTF-8) value from a memory buffer
procedure BSONWrite(const name: RawUTF8; value: PUTF8Char); overload;
/// write a string (UTF-8) value from a memory buffer
procedure BSONWriteString(const name: RawUTF8; value: PUTF8Char; valueLen: integer);
/// write a binary (BLOB) value
procedure BSONWrite(const name: RawUTF8; Data: pointer; DataLen: integer); overload;
/// write an ObjectID value
procedure BSONWrite(const name: RawUTF8; const value: TBSONObjectID); overload;
/// write a RegEx value
procedure BSONWriteRegEx(const name: RawUTF8; const RegEx, Options: RawByteString);
/// write a data/time value
procedure BSONWriteDateTime(const name: RawUTF8; const value: TDateTime);
/// write an element with no value
// - elemType can be either betNull, betMinKey or betMaxKey
procedure BSONWrite(const name: RawUTF8; elemtype: TBSONElementType); overload;
/// write an element with no value
procedure BSONWrite(const name: RawUTF8; const elem: TBSONElement); overload;
/// write a BSONVariant instance value
procedure BSONWrite(const name: RawUTF8; const bson: TBSONVariantData); overload;
/// write a DocVariant instance value
procedure BSONWrite(const name: RawUTF8; const doc: TDocVariantData); overload;
/// write a TDecimal128 value
procedure BSONWrite(const name: RawUTF8; const value: TDecimal128); overload;
/// write a variant value
// - handle simple types (numbers, strings...) and custom types (TDocVariant
// and TBSONVariant, trying a translation to JSON for other custom types)
procedure BSONWriteVariant(const name: RawUTF8; const value: variant); overload;
/// write an open array (const Args: array of const) argument
// - handle simple types (numbers, strings...) and custom types (TDocVariant)
procedure BSONWrite(const name: RawUTF8; const value: TVarRec); overload;
/// write a value from the supplied JSON content
// - is able to handle any kind of values, including nested documents or
// BSON extended syntax (if DoNotTryExtendedMongoSyntax=false)
// - this method is used recursively by BSONWriteDocFromJSON(), and should
// not be called directly
// - will return JSON=nil in case of unexpected error in the supplied JSON
procedure BSONWriteFromJSON(const name: RawUTF8; var JSON: PUTF8Char;
EndOfObject: PUTF8Char; DoNotTryExtendedMongoSyntax: boolean = false);
/// recursive writing of a BSON document or value from a TDocVariant
// object or array, used e.g. by BSON(const doc: TDocVariantData) function
// - caller should execute BSONAdjustDocumentsSize() on the resulting buffer
// - this method will call BSONDocumentBegin/BSONDocumentEnd internally
// - will raise an EBSONException if doc is not a valid TDocVariant or null
// or if the resulting binary content is bigger than BSON_MAXDOCUMENTSIZE
procedure BSONWriteDoc(const doc: TDocVariantData);
/// write an object specified as name/value pairs as a BSON document
// - data must be supplied two by two, as Name,Value pairs, e.g.
// ! aBSONWriter.BSONWriteObject(['name','John','year',1972]);
// - this method wil be faster than using a BSONWriteDoc(_ObjFast(...))
procedure BSONWriteObject(const NameValuePairs: array of const);
/// write a projection specified as fieldname:1 pairs as a BSON document
procedure BSONWriteProjection(const FieldNamesCSV: RawUTF8);
/// write an object as query parameter
// - will handle all SQL operators, including IN (), IS NULL or LIKE
// - see @http://docs.mongodb.org/manual/reference/operator/query
// - inverted should be TRUE e.g. for a NOT ... expression
// - returns TRUE on success, FALSE if the operator is not implemented yet
function BSONWriteQueryOperator(name: RawUTF8; inverted: boolean;
op: TSynTableStatementOperator; const Value: variant): boolean;
/// write one array item, i.e. the ASCII index name as text
// - only one level of array should be used per TBSONWriter class
procedure BSONWriteArray(const kind: TBSONElementType); overload;
/// write an array specified as a list of items as a BSON document
// - data must be supplied as a list of values e.g.
// ! aBSONWriter.BSONWriteArray(['John',1972]);
// - this method wil be faster than using a BSONWriteDoc(_ArrFast(...))
procedure BSONWriteArray(const Items: array of const); overload;
/// write an array of integers as a BSON Document
procedure BSONWriteArrayOfInteger(const Integers: array of integer);
/// write an array of integers as a BSON Document
procedure BSONWriteArrayOfInt64(const Integers: array of Int64);
/// write some BSON document from a supplied (extended) JSON array or object
// - warning: the incoming JSON buffer will be modified in-place: so you
// should make a private copy before running this method (see e.g. TSynTempBuffer)
// - will handle only '{ ... }', '[ ... ]' or 'null' input, with the standard
// strict JSON format, or BSON-like extensions, e.g. unquoted field names:
// $ {id:10,doc:{name:"John",birthyear:1972}}
// - if DoNotTryExtendedMongoSyntax is default FALSE, then the MongoDB Shell
// syntax will also be recognized to create BSON custom types, like
// $ new Date() ObjectId() MinKey MaxKey /<jRegex>/<jOptions>
// see @http://docs.mongodb.org/manual/reference/mongodb-extended-json
// $ {id:new ObjectId(),doc:{name:"John",date:ISODate()}}
// $ {name:"John",field:/acme.*corp/i}
// - if DoNotTryExtendedMongoSyntax is TRUE, process may be slightly faster
// - will create the BSON binary without any temporary TDocVariant storage
function BSONWriteDocFromJSON(JSON: PUTF8Char; aEndOfObject: PUTF8Char;
out Kind: TBSONElementType; DoNotTryExtendedMongoSyntax: boolean = false): PUTF8Char;
/// to be called before a BSON document will be written
// - each BSONDocumentBegin should be followed by its nested BSONDocumentEnd
procedure BSONDocumentBegin; overload;
/// to be called before a BSON document will be written
// - each BSONDocumentBegin should be followed by its nested BSONDocumentEnd
// - you could create a new BSON object by specifying a name and its
// type, i.e. either betDoc or betArray
procedure BSONDocumentBegin(const name: RawUTF8;
kind: TBSONElementType = betDoc); overload;
/// to be called before a BSON document will be written in an array
// - only one level of array should be used per TBSONWriter class
procedure BSONDocumentBeginInArray(const name: RawUTF8;
kind: TBSONElementType = betDoc);
/// to be called when a BSON document has been written
// - it will store the current stream position into an internal array,
// which will be written when you call AdjustDocumentsSize()
// - you can optional specify how many nested documents should be closed,
// and/or if it should not write an ending betEof item
procedure BSONDocumentEnd(CloseNumber: integer = 1; WriteEndingZero: boolean = true);
/// after all content has been written, call this method on the resulting
// memory buffer to store all document size as expected by the standard
procedure BSONAdjustDocumentsSize(BSON: PByteArray); virtual;
/// flush the content and return the whole binary encoded stream
// - call BSONAdjustDocumentsSize() to adjust all internal document sizes
// - expect the TBSONWriter instance to have been created as such:
// ! TBSONWriter.Create(TRawByteStringStream);
procedure ToBSONDocument(var result: TBSONDocument); virtual;
/// flush the content and return the whole document as a TBSONVariant
// - call ToBSONDocument() to adjust all internal document sizes
// - expect the TBSONWriter instance to have been created as such:
// ! TBSONWriter.Create(TRawByteStringStream);
procedure ToBSONVariant(var result: variant; Kind: TBSONElementType = betDoc);
TBSONDocument = RawByteString;