vendor/github.com/bennyscetbun/jsongo/README.md

   1 jsongo
   2 ======
   3
   4 **Jsongo is a simple library for golang to help you build Json without static struct or map[string]interface**
   5
   6 [json.Marshal](http://golang.org/pkg/encoding/json/#Marshal) and [json.Unmarshal](http://golang.org/pkg/encoding/json/#Unmarshal) have never been that easy
   7
   8 **If you had only one function to look at, look at the "[At](#at)" function**
   9
  10 ***If you want an easy way to turn your json into a structure you should use the "[Print](#print)" function after unmarshalling json in a JSONNODE***
  11
  12 You can find the doc on godoc.org [![GoDoc](https://godoc.org/github.com/bennyscetbun/jsongo?status.png)](https://godoc.org/github.com/bennyscetbun/jsongo)
  13
  14
  15 ##JsonNode
  16
  17 JsonNode is the basic Structure that you must use when using jsongo. It can either be a:
  18 - Map (jsongo.TypeMap)
  19 - Array (jsongo.TypeArray)
  20 - Value (jsongo.TypeValue) *Precisely a pointer store in an interface{}*
  21 - Undefined (jsongo.TypeUndefined) *default type*
  22
  23 *When a JSONNode Type is set you cant change it without using Unset() first*
  24 ____
  25 ###Val
  26 ####Synopsis:
  27 turn this JSONNode to TypeValue and set that value
  28 ```go
  29 func (that *JSONNode) Val(val interface{})
  30 ```
  31
  32 ####Examples
  33 #####code:
  34 ```go
  35 package main
  36
  37 import (
  38     "github.com/bennyscetbun/jsongo"
  39 )
  40
  41 func main() {
  42     root := jsongo.JSONNode{}
  43         root.Val(42)
  44         root.DebugPrint("")
  45 }
  46 ```
  47 #####output:
  48 ```
  49 42
  50 ```
  51 #####code:
  52 ```go
  53 package main
  54
  55 import (
  56     "github.com/bennyscetbun/jsongo"
  57 )
  58 type MyStruct struct {
  59         Member1 string
  60         Member2 int
  61 }
  62
  63 func main() {
  64         root := jsongo.JSONNode{}
  65         root.Val(MyStruct{"The answer", 42})
  66         root.DebugPrint("")
  67 }
  68 ```
  69 #####output:
  70 ```
  71 {
  72   "Member1": "The answer",
  73   "Member2": 42
  74 }
  75 ```
  76 _____
  77 ###Array
  78 ####Synopsis:
  79  Turn this JSONNode to a TypeArray and/or set the array size (reducing size will make you loose data)
  80 ```go
  81 func (that *JSONNode) Array(size int) *[]JSONNode
  82 ```
  83
  84 ####Examples
  85 #####code:
  86 ```go
  87 package main
  88
  89 import (
  90     "github.com/bennyscetbun/jsongo"
  91 )
  92
  93 func main() {
  94     root := jsongo.JSONNode{}
  95         a := root.Array(4)
  96     for i := 0; i < 4; i++ {
  97         (*a)[i].Val(i)
  98     }
  99         root.DebugPrint("")
 100 }
 101 ```
 102 #####output:
 103 ```
 104 [
 105   0,
 106   1,
 107   2,
 108   3
 109 ]
 110 ```
 111 #####code:
 112 ```go
 113 package main
 114
 115 import (
 116     "github.com/bennyscetbun/jsongo"
 117 )
 118
 119 func main() {
 120     root := jsongo.JSONNode{}
 121     a := root.Array(4)
 122     for i := 0; i < 4; i++ {
 123         (*a)[i].Val(i)
 124     }
 125     root.Array(2) //Here we reduce the size and we loose some data
 126         root.DebugPrint("")
 127 }
 128 ```
 129 #####output:
 130 ```
 131 [
 132   0,
 133   1
 134 ]
 135 ```
 136 ____
 137 ###Map
 138 ####Synopsis:
 139 Turn this JSONNode to a TypeMap and/or Create a new element for key if necessary and return it
 140 ```go
 141 func (that *JSONNode) Map(key string) *JSONNode
 142 ```
 143
 144 ####Examples
 145 #####code:
 146 ```go
 147 package main
 148
 149 import (
 150     "github.com/bennyscetbun/jsongo"
 151 )
 152
 153 func main() {
 154     root := jsongo.JSONNode{}
 155     root.Map("there").Val("you are")
 156     root.Map("here").Val("you should be")
 157         root.DebugPrint("")
 158 }
 159 ```
 160 #####output:
 161 ```
 162 {
 163   "here": "you should be",
 164   "there": "you are"
 165 }
 166 ```
 167 ____
 168 ###At
 169 ####Synopsis:
 170 Helps you move through your node by building them on the fly
 171
 172 *val can be string or int only*
 173
 174 *strings are keys for TypeMap*
 175
 176 *ints are index in TypeArray (it will make array grow on the fly, so you should start to populate with the biggest index first)*
 177 ```go
 178 func (that *JSONNode) At(val ...interface{}) *JSONNode
 179 ```
 180
 181 ####Examples
 182 #####code:
 183 ```go
 184 package main
 185
 186 import (
 187     "github.com/bennyscetbun/jsongo"
 188 )
 189
 190 func main() {
 191     root := jsongo.JSONNode{}
 192     root.At(4, "Who").Val("Let the dog out") //is equivalent to (*root.Array(5))[4].Map("Who").Val("Let the dog out")
 193     root.DebugPrint("")
 194 }
 195 ```
 196 #####output:
 197 ```
 198 [
 199   null,
 200   null,
 201   null,
 202   null,
 203   {
 204     "Who": "Let the dog out"
 205   }
 206 ]
 207 ```
 208 #####code:
 209 ```go
 210 package main
 211
 212 import (
 213     "github.com/bennyscetbun/jsongo"
 214 )
 215
 216 func main() {
 217     root := jsongo.JSONNode{}
 218     root.At(4, "Who").Val("Let the dog out")
 219     //to win some time you can even even save a certain JSONNode
 220         node := root.At(2, "What")
 221         node.At("Can", "You").Val("do with that?")
 222         node.At("Do", "You", "Think").Val("Of that")
 223     root.DebugPrint("")
 224 }
 225 ```
 226 #####output:
 227 ```
 228 [
 229   null,
 230   null,
 231   {
 232     "What": {
 233       "Can": {
 234         "You": "do with that?"
 235       },
 236       "Do": {
 237         "You": {
 238           "Think": "Of that"
 239         }
 240       }
 241     }
 242   },
 243   null,
 244   {
 245     "Who": "Let the dog out"
 246   }
 247 ]
 248 ```
 249 ____
 250 ###Print
 251 ####Synopsis:
 252 Helps you build your code by printing a go structure from the json you ve just unmarshaled
 253
 254 ```go
 255 func (that *JSONNode) Print()
 256 ```
 257
 258 ____
 259 ###Other Function
 260 There is plenty of other function, you should check the complete doc [![GoDoc](https://godoc.org/github.com/bennyscetbun/jsongo?status.png)](https://godoc.org/github.com/bennyscetbun/jsongo)
 261
 262 ####A last Example for fun
 263 #####code:
 264 ```go
 265 package main
 266
 267 import (
 268     "github.com/bennyscetbun/jsongo"
 269 )
 270
 271 func ShowOnlyValue(current *jsongo.JSONNode) {
 272     switch current.GetType() {
 273         case jsongo.TypeValue:
 274                         println(current.Get().(string))
 275                 case jsongo.TypeMap:
 276                         for _, key := range current.GetKeys() {
 277                                 ShowOnlyValue(current.At(key))
 278                         }
 279                 case jsongo.TypeArray:
 280                         for _, key := range current.GetKeys() {
 281                                 ShowOnlyValue(current.At(key))
 282                         }
 283         }
 284 }
 285
 286 func main() {
 287     root := jsongo.JSONNode{}
 288     root.At(4, "Who").Val("Let the dog out")
 289         node := root.At(2, "What")
 290         node.At("Can", "You").Val("do with that?")
 291         node.At("Do", "You", "Think").Val("Of that")
 292         ShowOnlyValue(&root)
 293 }
 294 ```
 295 #####output:
 296 ```
 297 Of that
 298 do with that?
 299 Let the dog out
 300 ```
 301 _____
 302 _____
 303 ##Json Marshal/Unmarshal
 304
 305 One of the main purpose of jsongo was to create Json from data without using static structure or map[string]interface.
 306
 307 You can use the full power of the [encoding/json](http://golang.org/pkg/encoding/json/) package with jsongo.
 308
 309 ###Marshal
 310 ####Example
 311 #####code:
 312 ```go
 313 package main
 314
 315 import (
 316     "encoding/json"
 317         "fmt"
 318     "github.com/bennyscetbun/jsongo"
 319 )
 320
 321 type Test struct {
 322         Static string `json:"static"`
 323         Over int `json:"over"`
 324 }
 325
 326 func main() {
 327         root := jsongo.JSONNode{}
 328         root.At("A", "AA", "AAA").Val(42)
 329
 330         node := root.At("A", "AB")
 331         node.At(1).Val("Peace")
 332         node.At(0).Val(Test{"struct suck when you build json", 9000})
 333         root.At("B").Val("Oh Yeah")
 334
 335         tojson, err := json.MarshalIndent(&root, "", "  ")
 336         if err != nil {
 337                 fmt.Printf("%s\n", err.Error())
 338                 return
 339         }
 340         fmt.Printf("%s\n", tojson)
 341 }
 342 ```
 343 #####output:
 344 ```
 345 {
 346   "A": {
 347     "AA": {
 348       "AAA": 42
 349     },
 350     "AB": [
 351       {
 352         "static": "struct suck when you build json",
 353         "over": 9000
 354       },
 355       "Peace"
 356     ]
 357   },
 358   "B": "Oh Yeah"
 359 }
 360 ```
 361 ____
 362 ###Unmarshal
 363 Unmarshal using JSONNode follow some simple rules:
 364 - Any TypeUndefined JSONNode will be set to the right type, any other type wont be changed
 365 - Array will grow if necessary
 366 - New keys will be added to Map
 367 - Values set to nil "*.Val(nil)*" will be turn into the type decide by Json
 368 - It will respect any current mapping and will return errors if needed
 369
 370 You can set a node as "DontExpand" with the UnmarshalDontExpand function and thoose rules will apply:
 371 - The type wont be change for any type
 372 - Array wont grow
 373 - New keys wont be added to Map
 374 - Values set to nil "*.Val(nil)*" will be turn into the type decide by Json
 375 - It will respect any current mapping and will return errors if needed
 376
 377 ####Example of full expand
 378 #####code:
 379 ```go
 380 package main
 381
 382 import (
 383     "encoding/json"
 384     "github.com/bennyscetbun/jsongo"
 385     "fmt"
 386 )
 387
 388 func main() {
 389     root := jsongo.JSONNode{}
 390     fromjson := `{
 391           "A": {
 392                 "AA": {
 393                   "AAA": 42
 394                 },
 395                 "AB": [
 396                   {
 397                         "static": "struct suck when you build json",
 398                         "over": 9000
 399                   },
 400                   "Peace"
 401                 ]
 402           },
 403           "B": "Oh Yeah"
 404         }`
 405     err := json.Unmarshal([]byte(fromjson), &root)
 406         if err != nil {
 407                 fmt.Printf("%s\n", err.Error())
 408                 return
 409         }
 410         root.DebugProspect(0, "\t")
 411 }
 412 ```
 413 #####output:
 414 ```
 415 Is of Type: TypeMap
 416 A:
 417         Is of Type: TypeMap
 418         AA:
 419                 Is of Type: TypeMap
 420                 AAA:
 421                         Is of Type: TypeValue
 422                         Value of type: float64
 423                         42
 424         AB:
 425                 Is of Type: TypeArray
 426                 [0]:
 427                         Is of Type: TypeMap
 428                         static:
 429                                 Is of Type: TypeValue
 430                                 Value of type: string
 431                                 struct suck when you build json
 432                         over:
 433                                 Is of Type: TypeValue
 434                                 Value of type: float64
 435                                 9000
 436                 [1]:
 437                         Is of Type: TypeValue
 438                         Value of type: string
 439                         Peace
 440 B:
 441         Is of Type: TypeValue
 442         Value of type: string
 443         Oh Yeah
 444 ```
 445 ####Example expand with mapping
 446 #####code:
 447 ```go
 448 package main
 449
 450 import (
 451     "encoding/json"
 452     "github.com/bennyscetbun/jsongo"
 453     "fmt"
 454 )
 455 type Test struct {
 456     Static string `json:"static"`
 457     Over int `json:"over"`
 458 }
 459
 460 func main() {
 461         root := jsongo.JSONNode{}
 462     fromjson := `{
 463       "A": {
 464                 "AA": {
 465                   "AAA": 42
 466                 },
 467                 "AB": [
 468                   {
 469                         "static": "struct suck when you build json",
 470                         "over": 9000
 471                   },
 472                   "Peace"
 473                 ]
 474           },
 475           "B": "Oh Yeah"
 476         }`
 477         root.At("A", "AB", 0).Val(Test{})
 478     err := json.Unmarshal([]byte(fromjson), &root)
 479         if err != nil {
 480                 fmt.Printf("%s\n", err.Error())
 481                 return
 482         }
 483         root.DebugProspect(0, "\t")
 484 }
 485 ```
 486 #####output:
 487 ```
 488 Is of Type: TypeMap
 489 A:
 490         Is of Type: TypeMap
 491         AB:
 492                 Is of Type: TypeArray
 493                 [0]:
 494                         Is of Type: TypeValue
 495                         Value of type: main.Test
 496                         {Static:struct suck when you build json Over:9000}
 497                 [1]:
 498                         Is of Type: TypeValue
 499                         Value of type: string
 500                         Peace
 501         AA:
 502                 Is of Type: TypeMap
 503                 AAA:
 504                         Is of Type: TypeValue
 505                         Value of type: float64
 506                         42
 507 B:
 508         Is of Type: TypeValue
 509         Value of type: string
 510         Oh Yeah
 511 ```
 512 ####Example expand with some UnmarshalDontExpand
 513 #####code:
 514 ```go
 515 package main
 516
 517 import (
 518     "encoding/json"
 519     "github.com/bennyscetbun/jsongo"
 520     "fmt"
 521 )
 522 type Test struct {
 523         Static string `json:"static"`
 524         Over int `json:"over"`
 525 }
 526
 527 func main() {
 528     root := jsongo.JSONNode{}
 529     fromjson := `{
 530       "A": {
 531                 "AA": {
 532                   "AAA": 42
 533                 },
 534                 "AB": [
 535                   {
 536                         "static": "struct suck when you build json",
 537                         "over": 9000
 538                   },
 539                   "Peace"
 540                 ]
 541           },
 542           "B": "Oh Yeah"
 543         }`
 544         root.At("A", "AB").UnmarshalDontExpand(true, false).At(0).Val(Test{})
 545     err := json.Unmarshal([]byte(fromjson), &root)
 546         if err != nil {
 547                 fmt.Printf("%s\n", err.Error())
 548                 return
 549         }
 550         root.DebugProspect(0, "\t")
 551 }
 552 ```
 553 #####output:
 554 ```
 555 Is of Type: TypeMap
 556 A:
 557         Is of Type: TypeMap
 558         AB:
 559                 Is of Type: TypeArray
 560                 [0]:
 561                         Is of Type: TypeValue
 562                         Value of type: main.Test
 563                         {Static:struct suck when you build json Over:9000}
 564         AA:
 565                 Is of Type: TypeMap
 566                 AAA:
 567                         Is of Type: TypeValue
 568                         Value of type: float64
 569                         42
 570 B:
 571         Is of Type: TypeValue
 572         Value of type: string
 573         Oh Yeah
 574 ```