|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 16-Nov-2018 | - |
| README.md | H A D | 16-Nov-2018 | 4.1 KiB | 139 | 114 |
| gen_accept.go | H A D | 16-Nov-2018 | 68.1 KiB | 2,457 | 1,685 |
| gen_activity.go | H A D | 16-Nov-2018 | 68.7 KiB | 2,453 | 1,682 |
| gen_add.go | H A D | 16-Nov-2018 | 67.4 KiB | 2,453 | 1,682 |
| gen_announce.go | H A D | 16-Nov-2018 | 68.6 KiB | 2,457 | 1,685 |
| gen_application.go | H A D | 16-Nov-2018 | 58.9 KiB | 2,094 | 1,440 |
| gen_arrive.go | H A D | 16-Nov-2018 | 66.6 KiB | 2,401 | 1,648 |
| gen_article.go | H A D | 16-Nov-2018 | 58.1 KiB | 2,094 | 1,440 |
| gen_audio.go | H A D | 16-Nov-2018 | 57.7 KiB | 2,094 | 1,440 |
| gen_block.go | H A D | 16-Nov-2018 | 67.9 KiB | 2,453 | 1,682 |
| gen_collection.go | H A D | 16-Nov-2018 | 64.5 KiB | 2,307 | 1,596 |
| gen_collectionpage.go | H A D | 16-Nov-2018 | 68.4 KiB | 2,421 | 1,683 |
| gen_create.go | H A D | 16-Nov-2018 | 67.9 KiB | 2,453 | 1,682 |
| gen_delete.go | H A D | 16-Nov-2018 | 68 KiB | 2,453 | 1,682 |
| gen_dislike.go | H A D | 16-Nov-2018 | 68.2 KiB | 2,453 | 1,682 |
| gen_document.go | H A D | 16-Nov-2018 | 58.3 KiB | 2,094 | 1,440 |
| gen_event.go | H A D | 16-Nov-2018 | 57.7 KiB | 2,094 | 1,440 |
| gen_flag.go | H A D | 16-Nov-2018 | 67.5 KiB | 2,453 | 1,682 |
| gen_follow.go | H A D | 16-Nov-2018 | 68.1 KiB | 2,453 | 1,682 |
| gen_group.go | H A D | 16-Nov-2018 | 57.7 KiB | 2,094 | 1,440 |
| gen_ignore.go | H A D | 16-Nov-2018 | 68 KiB | 2,453 | 1,682 |
| gen_image.go | H A D | 16-Nov-2018 | 59.3 KiB | 2,162 | 1,490 |
| gen_intransitiveactivity.go | H A D | 16-Nov-2018 | 70 KiB | 2,401 | 1,648 |
| gen_invite.go | H A D | 16-Nov-2018 | 68 KiB | 2,453 | 1,682 |
| gen_join.go | H A D | 16-Nov-2018 | 67.5 KiB | 2,453 | 1,682 |
| gen_leave.go | H A D | 16-Nov-2018 | 67.7 KiB | 2,453 | 1,682 |
| gen_like.go | H A D | 16-Nov-2018 | 67.5 KiB | 2,453 | 1,682 |
| gen_link.go | H A D | 16-Nov-2018 | 15.9 KiB | 582 | 390 |
| gen_listen.go | H A D | 16-Nov-2018 | 67.9 KiB | 2,453 | 1,682 |
| gen_mention.go | H A D | 16-Nov-2018 | 15.6 KiB | 582 | 390 |
| gen_move.go | H A D | 16-Nov-2018 | 67.5 KiB | 2,453 | 1,682 |
| gen_note.go | H A D | 16-Nov-2018 | 57.5 KiB | 2,094 | 1,440 |
| gen_object.go | H A D | 16-Nov-2018 | 58.1 KiB | 2,094 | 1,440 |
| gen_offer.go | H A D | 16-Nov-2018 | 67.7 KiB | 2,453 | 1,682 |
| gen_orderedcollection.go | H A D | 16-Nov-2018 | 66.3 KiB | 2,307 | 1,596 |
| gen_orderedcollectionpage.go | H A D | 16-Nov-2018 | 71.3 KiB | 2,455 | 1,708 |
| gen_organization.go | H A D | 16-Nov-2018 | 59.2 KiB | 2,094 | 1,440 |
| gen_page.go | H A D | 16-Nov-2018 | 57.4 KiB | 2,094 | 1,440 |
| gen_person.go | H A D | 16-Nov-2018 | 57.9 KiB | 2,094 | 1,440 |
| gen_place.go | H A D | 16-Nov-2018 | 62 KiB | 2,264 | 1,565 |
| gen_profile.go | H A D | 16-Nov-2018 | 59.2 KiB | 2,128 | 1,465 |
| gen_question.go | H A D | 16-Nov-2018 | 72.6 KiB | 2,595 | 1,782 |
| gen_read.go | H A D | 16-Nov-2018 | 67.4 KiB | 2,453 | 1,682 |
| gen_reject.go | H A D | 16-Nov-2018 | 68 KiB | 2,453 | 1,682 |
| gen_relationship.go | H A D | 16-Nov-2018 | 63.1 KiB | 2,227 | 1,534 |
| gen_remove.go | H A D | 16-Nov-2018 | 68 KiB | 2,453 | 1,682 |
| gen_service.go | H A D | 16-Nov-2018 | 58.1 KiB | 2,094 | 1,440 |
| gen_streams.go | H A D | 16-Nov-2018 | 82 KiB | 3,050 | 2,762 |
| gen_tentativeaccept.go | H A D | 16-Nov-2018 | 70.2 KiB | 2,453 | 1,682 |
| gen_tentativereject.go | H A D | 16-Nov-2018 | 70.2 KiB | 2,453 | 1,682 |
| gen_tombstone.go | H A D | 16-Nov-2018 | 61.2 KiB | 2,184 | 1,503 |
| gen_travel.go | H A D | 16-Nov-2018 | 66.6 KiB | 2,401 | 1,648 |
| gen_undo.go | H A D | 16-Nov-2018 | 67.7 KiB | 2,453 | 1,682 |
| gen_update.go | H A D | 16-Nov-2018 | 68.1 KiB | 2,453 | 1,682 |
| gen_video.go | H A D | 16-Nov-2018 | 57.7 KiB | 2,094 | 1,440 |
| gen_view.go | H A D | 16-Nov-2018 | 67.4 KiB | 2,453 | 1,682 |
| streams_data_test.go | H A D | 16-Nov-2018 | 27.4 KiB | 1,132 | 1,130 |
| streams_test.go | H A D | 16-Nov-2018 | 9 KiB | 341 | 323 |
README.md
1# streams
2
3Please read the `README.md` in the `go-fed/activity/vocab` package first. This
4library is a convenience layer on top of the `go-fed/activity/vocab` library, so
5this README builds off of that one.
6
7This library is entirely code-generated by the
8`go-fed/activity/tools/streams/gen` library and `go-fed/activity/tools/streams`
9tool. Run `go generate` to refresh the library, which requires `$GOPATH/bin` to
10be on your `$PATH`.
11
12## What it does
13
14This library provides a `Resolver`, which is simply a collection of callbacks
15that clients can specify to handle specific ActivtyStream data types. The
16`Resolver.Deserialize` method turns a JSON-decoded `map[string]interface{}`
17into its proper type, passed to the corresponding callback.
18
19For example, given the data:
20
21```golang
22{
23 "@context": "https://www.w3.org/ns/activitystreams",
24 "type": "Note",
25 "name": "Equivalent Exchange",
26 "content": "I'll give half of my life to you and you give half of yours to me!",
27 "attachment": "https://example.com/attachment"
28}
29```
30
31in `b []byte` one can do the following:
32
33```golang
34var m map[string]interface{}
35if err := json.Unmarshal(b, &m); err != nil {
36 return err
37}
38r := &Resolver {
39 NoteCallback: func(n *Note) error {
40 // 1) Use the Note concrete type here
41 // 2) Errors are propagated transparently
42 },
43}
44if handled, err := r.Deserialize(m); err != nil {
45 // 3) Any errors from #2 can be handled, or the payload is an unknown type.
46 return err
47} else if !handled {
48 // 4) The callback to handle the concrete type was not set.
49}
50```
51
52Only set the callbacks that are interesting. There is no need to set every
53callback, unless your application requires it.
54
55## Using concrete types
56
57The convenience layer provides easy access to properties with specific types.
58However, because ActivityStreams is fundamentally built off of JSON-LD and
59still permits large degree of freedom when it comes to obtaining a concrete type
60for a property, the convenience API is built to give clients the freedom to
61choose how best to federate.
62
63For every type in this package (except `Resolver`), there is an equivalent type
64in the `activity/vocab` package. It takes only a call to `Raw` to go from this
65convenience API to the full API:
66
67```golang
68r := &Resolver {
69 NoteCallback: func(n *Note) error {
70 // Raw is available for all ActivityStream types
71 vocabNote := n.Raw()
72 },
73}
74```
75
76To determine whether the call to `Raw` is needed, the "get" and "has" methods
77use `Resolution` and `Presence` types to inform client code. The client is free
78to support as many types as is feasible within the specific application.
79
80Reusing the `Note` example above that has an `attachment`, the following is
81client code that tries to handle every possible type that `attachment` can
82take. **The W3C does not require client applications to support all of these
83use cases.**
84
85```golang
86r := &Resolver {}
87r.NoteCallback = func(n *Note) error {
88 if n.LenAttachment() == 1 {
89 if presence := n.HasAttachment(0); p == ConvenientPresence {
90 // A new or existing Resolver can be used. This is the convenient getter.
91 if resolution, err := n.ResolveAttachment(r, 0); err != nil {
92 return err
93 } else if resolution == RawResolutionNeeded {
94 vocabNote := n.Raw()
95 // Use the full API
96 if vocabNote.IsAttachmentIRI(0) {
97 ...
98 } else ...
99 }
100 } else if p == RawPresence {
101 vocabNote := n.Raw()
102 // Use the full API
103 if vocabNote.IsAttachmentIRI(0) {
104 ...
105 } else ...
106 }
107 }
108}
109```
110
111## Serializing data
112
113Creating a raw type and serializing it is straightforward:
114
115```golang
116n := &Note{}
117n.AddName("I'll see you again")
118n.AddContent("You don't have to be alone when I leave")
119// The "type" property is automatically handled...
120m, err := n.Serialize()
121if err != nil {
122 return err
123}
124// ...but "@context" is not.
125m["@context"] = "https://www.w3.org/ns/activitystreams"
126b, err := json.Marshal(m)
127```
128
129The only caveat is that clients must set `"@context"` manually at this time.
130
131## What it doesn't do
132
133Please see the same section in the `go-fed/activity/vocab` package.
134
135## Other considerations
136
137This library is entirely code-generated. Please see the same section in the
138`go-fed/activity/vocab` package for more details.
139