From 61bba41c056d2ea9b699002a91649ca51d203ed9 Mon Sep 17 00:00:00 2001
From: Melody <melody@Curiosity.fritz.box>
Date: Wed, 28 Aug 2024 19:35:54 +0200
Subject: [PATCH] Docs

---
 parser.go | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/parser.go b/parser.go
index 41afffe..7c6d7a9 100644
--- a/parser.go
+++ b/parser.go
@@ -7,6 +7,7 @@ import (
 	"github.com/piprate/json-gold/ld"
 )
 
+// Internal so that others don't mess with this and potentially accidentally overwrite it, breaking everything
 var allInternalParsersExceptBase []UnmarshalFunc = []UnmarshalFunc{
 	ParseUDIdData,
 	ParseUDTypeData,
@@ -82,6 +83,15 @@ func chainParse(
 	return current, errors
 }
 
+// Unmarshal raw data into an Activitypub object in the form of a recursive BaseApChain
+// Each element corresponds to one attribute the object contained
+// If ldOptions or processor are nil, the following defaults are used:
+// - ldOptions: `ld.NewJsonLdOptions("")`
+// - processor: `ld.NewJsonLdProcessor()`
+// Returns an ActivityPub object and a list of errors produced by the parser functions
+// Not each function has to produce an error. Those will have nil as error value
+// Those errors (or nils) come in the order of the parser functions
+// which can be inspected in the `allInternalParsersExceptBase` internal variable
 func Unmarshal(
 	raw []byte,
 	ldOptions *ld.JsonLdOptions,
@@ -105,6 +115,8 @@ func Unmarshal(
 	return UnmarshalPreprocessed(data, extraParsers...)
 }
 
+// Unmarshal a preproccessed object. Preproccessed meaning being first parsed as json and then expanded by json-gold
+// Otherwise the same as Unmarshal
 func UnmarshalPreprocessed(
 	raw map[string]any,
 	extraParsers ...UnmarshalFunc,
@@ -113,3 +125,23 @@ func UnmarshalPreprocessed(
 	allParsers := slices.Concat(allInternalParsersExceptBase, extraParsers)
 	return chainParse(raw, &base, allParsers...)
 }
+
+// Find an attribute in an ActivityPub object of the given type
+// Returns a pointer to the found attribute and whether it found it
+// 2nd parameter is true if the attribute was found, false otherwise
+func FindAttribute[T BaseApChain](object BaseApChain) (*T, bool) {
+	var obj T
+	var ok bool
+	// Try and cast object into wanted type
+	// If cast failed, do inner codeblock
+	// Try and cast again
+	for obj, ok = object.(T); !ok; obj, ok = object.(T) {
+		// Get the next attribute in the chain
+		object, ok = object.GetSelfOrBase()
+		// If this is the final object in the chain, cancel and return false
+		if !ok {
+			return nil, false
+		}
+	}
+	return &obj, true
+}