@genie-networks/gcl_gsonjs
v0.1.32
Published
GCL gson js library
Downloads
3
Readme
gcl_gsonjs
Genie Common Library - GSON js
changeLog
- [0.1.32] sync with company Library
- [0.1.7] Chaneg Readme.md syntax
- [0.1.6] remove Oper.Reg
Install
npm install @genie-networks/gcl_gsonjs
Usage
/* Require gclGson */
const gclGson = require('gcl_gsonjs')
/* Construct value for each type */
let myNum = 3
let myStr = 'hello'
let myBool = true
let myNull = null
let myUndefine
let myIndex = new gclGson.Index(true, false, 100, 1)
let myDate = new Date()
let myPair = new gclGson.Pair('null', 2)
let myOper = new gclGson.Oper(0x10)
let myBin = new gclGson.Bin([1, 2, 3, 4, 5])
let myUuid = new gclGson.Uuid()
let myMac = new gclGson.Mac('0f:ff:03:04:05:06')
let myDerive = new gclGson.Derive(100)
let myIp = new gclGson.Ip([192, 168, 0, 1])
let myIpv6 = new gclGson.Ip('FE00:1234::1')
let myCidr = new gclGson.Cidr('192.168.0.0/16')
let myTag = new gclGson.Tag(0x12345678123456781, false)
let myArr = [1, "s", myTag]
let myPair = new gclGson.Pair('null', 2)
let myDoc = {x:1, y:"str"}
// Get size for serialize buffer
let bufferSize = gclGson.calcSize(myDoc)
// serialize value
let buf = Buffer.alloc(gclGson.calcSize(myDoc), 0x00)
gclGson.serialize(myDoc, buf, 0)
// deserialize
let desDoc = gclGson.deserialize(buf)
// toJSON
let jsonObj = myDoc.toJSON()
// construct a GSON value from a JSON value
let gsonDoc = gclGson.fromJSON(jsonObj)
// Print as GSON format
console.log(gclGson.print(myDoc))
// Print as GSON format without quotation marks
console.log(gclGson.toString(myDoc))
// serialize GSON and import to a file
gclGson.exportFile(myDoc, 'somewhere')
// Import and deserialize GSON from a file
let importDoc = gclGson.importFile('somewhere')Class
- gclGsonOper - Operator
- gclGsonBin - Binary
- gclGsonTag - Tag
- gclGsonIndex - Index
- gclGsonPair - Pair
- gclGsonUuid - uuid
- gclGsonMac - MAC
- gclGsonIp - IPv4/IPv6
- gclGsonDerive - Derive
Method
- toJSON(gson_obj)
- fromJSON(json_obj)
- calcSize(gson_obj)
- print(gson_obj)
- deserialize(buffer)
- serialize(gson_obj, buffer, offset)
- exportFile(gson_obj, filePath) - retrun a promise
- importFile(filePath) - return a promise and resolve gson_obj
SPEC
Type System
- Simple
- Undefined represents the unexpected absence of value.
- Null represents the intentional absence of value.
- Boolean represents a logical data that can have only the values true or false.
- Date represents the number of milliseconds since 1 January, 1970 UTC.
- Number represents a double-precision floating point number.
- Oper represents a software defined operator.
- Index represents an 64-bit database index with 2-bit direction flag.
- String represents a null-terminated UTF-8 string.
- Bin represents a byte array.
- Uuid represents universally unique identifier defined by RFC-4122.
- Mac represents MAC address.
- Derive represents a derive function ID.
- Ip represents IPv4 or IPv6 address.
- Cidr represents IPv4 or IPv6 CIDR.
- Tag represents tagged id with 1-bit boundary flag.
- Complex
- Array represents a sequence of elements, each is a GSON value.
- Doc represents a sequence of fields, each is a key-value pair.
- The type of key must be a Number or String.
- The type of value could be any GSON value.
- Pair represents a pair of values.
Value Format
| Encoding | Type | Format | Description |
|--------------|-------------|--------------------------------------|-------------|
| 000 00000 | Undefined | 0x00 | unexpected absence of value |
| 000 00001 | Null | 0x01 | intentional absence of value |
| 000 00010 | False | 0x02 | boolean false |
| 000 00011 | True | 0x03 | boolean true |
| 000 00100 | Uint8 | 0x04 + 1{uint} | 8-bits non-negative integer number |
| 000 00101 | Uint16 | 0x05 + 2{uint} | 16-bits non-negative integer number |
| 000 00110 | Uint32 | 0x06 + 4{uint} | 32-bits non-negative integer number |
| 000 00111 | Number | 0x07 + 8{double} | double precision floating point number |
| 000 010xx | Index | 0x08~0x0B + 8{uint) | 64-bit database index with 2-bit direction flag |
| 000 01100 | Doc8 | 0x0C + 1{len} + *{value} | document up to 2^8-1 values |
| 000 01101 | Doc16 | 0x0D + 2{len} + *{value} | document up to 2^16-1 values |
| 000 01110 | Doc32 | 0x0E + 4{len} + *{value} | document up to 2^32-1 values |
| 000 01111 | Date | 0x0F + 8{double} | number of milliseconds since 1 January, 1970 UTC |
| 000 10000 | String8 | 0x10 + 1{size} + *{char} | string up to 2^8-1 chars |
| 000 10001 | String16 | 0x11 + 2{size} + *{char} | string up to 2^16-1 chars |
| 000 10010 | String32 | 0x12 + 4{size} + *{char} | string up to 2^32-1 chars |
| 000 10011 | Oper | 0x13 + 1{code} | operator |
| 000 10100 | Bin8 | 0x14 + 1{size} + *{data} | byte array up to 2^8-1 bytes |
| 000 10101 | Bin16 | 0x15 + 2{size} + *{data} | byte array up to 2^16-1 bytes |
| 000 10110 | Bin32 | 0x16 + 4{size} + *{data} | byte array up to 2^32-1 bytes |
| 000 10111 | Uuid | 0x17 + 16{uuid} | universal unique id defined by RFC-4122 |
| 000 11000 | Array8 | 0x18 + 1{len} + *{value} | array up to 2^8-1 values |
| 000 11001 | Array16 | 0x19 + 2{len} + *{value} | array up to 2^16-1 values |
| 000 11010 | Array32 | 0x1A + 4{len} + *{value} | array up to 2^32-1 values |
| 000 11011 | Pair | 0x1B + {value} + {value} | pair of values |
| 000 11100 | Mac | 0x1C + 6{mac} | mac address |
| 000 11101 | Derive | 0x1D + 1{uint} | lazy derive |
| 000 11110 | Reserved | 0x1E | reserved |
| 000 11111 | Reserved | 0x1F | reserved |
| 001 00000 | Ip4 | 0x20 + 4{ip} | ipv4 address |
| 001 00001 | Ip6 | 0x21 + 16{ip} | ipv6 address |
| 001 00010 | Cidr4 | 0x22 + 1{uint} + 4{ip} | ipv4 CIDR |
| 001 00011 | Cidr6 | 0x23 + 1{uint} + 16{ip} | ipv6 CIDR |
| 001 001xx | Reserved | 0x24~0x27 | reserved |
| 001 0100x | Tag8 | 0x28~0x29 + 1{uint} | 8-bits non-negative integer tag id |
| 001 0101x | Tag16 | 0x2A~0x2B + 2{uint} | 16-bits non-negative integer tag id |
| 001 0110x | Tag32 | 0x2C~0x2D + 4{uint} | 32-bits non-negative integer tag id |
| 001 0111x | Tag52 | 0x2E~0x2F + 8{double} | 52-bits non-negative integer tag id |
| 001 1xxxx | Reserved | 0x30~0x3F | reserved |
| 010 xxxxx | Reserved | 0x40~0x5F | reserved |
| 011 xxxxx | Fixbin | 0x60~0x7F + *{data} | byte array up to 2^5-1 bytes |
| 100 xxxxx | Fixstring | 0x80~0x9F + *{char} | string up to 2^5-1 bytes |
| 101 xxxxx | Fixuint | 0xA0~0xBF | unsigned interger up to 2^5-1 |
| 110 xxxxx | Fixarray | 0xC0~0xDF + *{value} | array up to 2^5-1 values |
| 111 xxxxx | Fixdoc | 0xE0~0xFF + *{value} | document up to 2^5-1 values |
1{uint}is 8-bits unsigned integer in host order.2{uint}is 16-bits unsigned integer in host order.4{uint}is 32-bits unsigned integer in host order.8{uint}is 64-bits unsigned integer in host order.8{double}is 64-bits double precision floating number in host order.1{code}is 8-bits unsigned integer in host order.1{len}: is 8-bits unsigned integer indicates number of values.2{len}: is 16-bits unsigned integer indicates number of values.4{len}: is 32-bits unsigned integer indicates number of values.1{size}: is 8-bits unsigned integer indicates number of bytes.2{size}: is 16-bits unsigned integer indicates number of bytes.4{size}: is 32-bits unsigned integer indicates number of bytes.*{char}is null-terminated string.*{data}is variable size byte array16{uuid}: is 128-bits UUID in RFC-4122 format.6{mac}is 48-bits mac address4{ip}is 32-bits ipv4 address16{ip}is 128-bits ipv6 address{value}is a serialized GSON value.*{value}is zero or more serialized GSON values.
Type String
|type |format |
|--------------|-----------|
|Undefined |"undefined" |
|Null |"null" |
|Boolean |"boolean" |
|Date |"date" |
|Number |"number" |
|Oper |"oper" |
|Index |"index" |
|String |"string" |
|Bin |"bin" |
|Uuid |"uuid" |
|Mac |"mac" |
|Derive |"derive" |
|Ip |"ip" |
|Cidr |"cidr" |
|Tag |"tag" |
|Array |"array" |
|Doc |"doc" |
|Pair |"pair" |
Text Format
|type |format |
|--------------|-----------|
|Undefined |undefined |
|Null |null |
|Boolean |true or false |
|Date |Date("<string>") |
|Number |<number> |
|Oper |$<name> or $<name>(<argument>,...) for expression |
|Index |Index("<src>.<dst>.<msb>.<lsb>") |
|String |"<string>" |
|Bin |Bin("<hexstring>") |
|Uuid |Uuid("<hexstring>") |
|Mac |Mac("<macstring>") |
|Derive |Derive(<number>) |
|Ip |Ip("<ipstring>") |
|Cidr |Cidr("<ipstring>") |
|Tag |Tag("<boundary>.<id>") |
|Array |[<value>,...] |
|Doc |{<key>: <value>,...} |
|Pair |Pair(<value>, <value>) |
JSON Format
|type |JSON format |
|--------------|-----------|
|Undefined |undefined |
|Null |null |
|Boolean |boolean |
|Date |string |
|Number |number |
|Oper |"__OPER":<opcode> |
|Index |"__INDEX:{"__DIR":[src, dst], "__VALUE":[hi, lo]}" |
|String |"<string>" |
|Bin |"__BIN":<hex string> |
|Uuid |"__UUID":<hex string> |
|Mac |"__MAC":<macstring> |
|Ip |"__IP":<ipstring> |
|Cidr |"__CIDR":<cidrstring> |
|Tag |"__TAG:{"__BOUNDARY":boolean, "__VALUE":number}" |
|Derive |"__DERIVE":<number> |
|Array |array |
|Doc |object which keys are string|
|Pair |"__PAIR":[<src>, <dst>] |
JavaScript Implement
- simple
- Undefined is mapped to the standard value undefined.
- Null is mapped to the standard value null.
- Boolean is mapped to the standard class Boolean.
- Date is mapped to the standard class Date.
- Number is mapped to the standard class Number.
- Oper is mapped to the proprietry class gclGsonOper.
- Index is mapped to the proprietry class gclGsonIndex.
- String is mapped to the standard class String.
- Bin is mapped to the proprietry class gclGsonBin.
- Uuid is mapped to the proprietry class gclGsonUuid.
- Mac is mapped to the proprietry class gclGsonMac.
- Ip is mapped to the proprietry class gclGsonIp.
- Cidr is mapped to the proprietry class gclGsonCidr.
- Tag is mapped to the proprietry class gclGsonTag.
- Derive is mapped to the proprietry class gclGsonDerive.
- complex
- Array is map to the standard class Array.
- Doc is map to the standard class Object.
- Pair is map to the proprietry class gclGsonPair.