Review verbs for DFG v1.0

[Affie]

Avoid "Swiss Army Knife" syndrome!
Verbs here:

• update verbNoun Dictionary wiki: https://github.com/JuliaRobotics/DistributedFactorGraphs.jl/wiki/Standard-Definitions-of-API-via-verbs-and-set-theory

With regard to:

• Signature
• Return Type
• Error Behaviour

Core verbs:

• list
• get
• add
• delete
• merge
• has[Noun]
• is[Adjective]

Other

• sync
• save
• load
• copyto
• search

TODO add all verbs for DFG v1.0

Considered but not in the API: , update, set, pull/push (use Async modifier)

[Affie]

list
Synchronously list the labels of an existing (composite) data container/object with optional filters.
- Filters on label: eg. startswith, contains, endswith, Regex (not SDK)
- Filter on Solvable (only variables and factors)
- Filter on Tags (tag in node.tags)
- Filter on Type (only variables and factors)

• Synchronous
• Example nouns Variables, Factors, VariableNodeData, PPE -> Vector{Symbol}
• Returns empty list if the container exists but empty
• Throw typed Exeption KeyError or custom exeption if the container does not exist.

---

Legacy refs:

• lsf tag filter  #528

[Affie]

get returns single unique entry else errors.

[Affie]

delete
Remove key and data at a given key if it exists.

• Synchronous
• Example nouns Variables, Factors
• Return number of nodes deleted - change delete return type #1134
• return 0 or try to if label does not exists, so don't throw typed Exception LabelNotFoundError . see delete! should not error (LabelNotFoundError) if node already deleted #1211

[Affie]

On update we decided that merge is a better fit for the current update behaviour.

update can perhaps take keyword arguments of what to update, for example: updateVariable(fg, label; solvable = 1)

As used like this in IIF on updateVariableSolverData!:

updateVariableSolverData!(
  dest,
  var,
  solveKey,
  false,
  [:val; :bw; :infoPerCoord; :solvedCount; :initialized];
  warn_if_absent = false,
)

Although, this specific signature is quite confusing and not very clear that var is not from dest fg. Options here are maybe merge sync copyto or similar.

[dehann]

I disagree with keyword specification for what to fields to update. This is taking CRUD too far.

I agree with using merge for now and keeping update as a reserved verb for later.

Therefore, I would expect DFG v1 usage would generally look something like this:

v1 = getVariable(srcfg, :x1)
mergeTags(v1, [:NEW_TAG;])
setSolvable!(v1, 4)
merge(srcfg, v1)

---

xref:

• DFG cross-over vision 56

[Affie]

has[Noun] (Containment / Existence)
Returns a boolean indicating whether the object exists by label::Symbol. The signatures are similar to get:

hasVariable(dfg, label::Symbol)
hasFactor(dfg, label::Symbol)
hasGraphBlobentry(dfg, label::Symbol)
hasVariableState(dfg, variableLabel::Symbol, stateLabel::Symbol)
hasBlobentry(v::AbstractDFGVariable, blobLabel::Symbol)
hasBlobentry(dfg, variableLabel::Symbol, blobLabel::Symbol)

[dehann]

has, Return[s] a boolean indicating whether the object exists by label::Symbol. [Signatures are similar] to get.

Sounds good to me, how about this for proto-definition text?