Any tips on which IRI implementation to use for what?

[gmorpheme]

I would love some kind of high level orientation documentation for this library.

• Why are there something like six representations of the concept of an IRI? What's the principle?
• How should you generally pass IRIs? How should you store them? (I'm sure the answer is "it depends"... but on what?)

I'm losing some time trying to work out how to wrangle a sophia::term::SimpleIri into a sophia::iri::Iri, and either missing something that isn't quite obvious enough or doing something entirely misconceived in the first place... do I go through changing everything into one... or the other? I'm bouncing around the docs and source to work out what implements which variations of From and how many different ways I can get out a &str, or Box or MownStr.

I think just one or two high level tips would really help.

[pchampin]

Yes, the high-level user documentation is long overdue :-/ But at the moment I'm busy refactoring the code. Hopefully, once this is done, it will be less of a mess ;-)

In the meantime, I will try to help you make sense of it.

Why are there something like six representations of the concept of an IRI? What's the principle?

sophia_iri (republished as sophia::iri) provides simple string wrappers whose sole purpose is to guarantee that the string is a valid IRI (resp. IRI reference). That's the most basic way to represent an IRI.

sophia_term (republished as sophia_term), on the other hand, provides a number of types for representing RDF terms (using different kinds of smart pointers for strings, depending on your needs, as documented here). Those types can be used to represent IRIs, of course, but their intent is more general, as they can also represent literals, bnodes...

SimpleIri is, I confess, a historical oddity, and will go away in v0.8. You should probably not use it beyond the situations where the API produces one.

How should you generally pass IRIs? How should you store them? (I'm sure the answer is "it depends"... but on what?)

If your are interested specifically in IRIs, and not any other kind of terms, then you should use the four types provides by sophia_iri. The choice is as follow:

• Iri and IriBox are absolute,
  while IriRef and IriRefBox can also be relative
• Iri and IriRef do not own the underlying text (they act as &str),
  while IriBox and IriRefBox do own (they act like Box<str>)

As a bonus: the way to get rid of a SimpleIri is to convert it to an IriRefBox like that:

    IriRefBox::new_unchecked(si.value().into())

(or IriBox if you check in advance that si.is_absolute() returns true)

Hope this helps.

[damooo]

There seems also sophia_term::iri::Iri, that implements TTerm, but dedicatedly for only iri terms. And is generic over term_data type it contains. If one need iri only type, that also can be used as TTerm, it seems good choice.

If SimpleIri is deprecated, this may be good alternative for such cases? (for vocabularies, etc.)

[pchampin]

@damooo you are right, sophia_term introduces its own lot to the mess :-/

sophia_term::iri::Iri is mostly meant as component of Term. It is not really meant to be used standalone (in retrospect, having it implement TTerm was not a great idea, as it sends the wrong signal). In future versions, it might not even be publicly exposed.

If SimpleIri is deprecated, this may be good alternative for such cases? (for vocabularies, etc.)

That would not possible, because of their respective place in the dependency chain:

sophia_iri < sophia_api < sophia_term

Namespaces are defined in sophia_api so they must not rely on types from sophia_term.

Again, apologies for the confusion all this creates. As I mentioned earlier, a great refactoing is in progress (not pushed yet). This discussion helps me in double-checking that the new design is clearer and better documenter 😉

[damooo]

@pchampin
None of apologies, instead we have to thank for your time and hard work.

And in above case, there is good value in having a type that is a TTerm, and guaranteed to be an iri among all kinds. In accordance with type driven design principle Parse, don't validate, it is better to have a type for invariant that expresses a TTerm that is guaranteed to be an iri term.

This case can be expressed in two ways. As it is known that, a term can be of any of few standard invariants, we can have dedicated invariant for each kind and an enum sum type wrapping all cases. This is the model currently implemented by sophia_term::Term apis. I think it's great.

If that possibility is deprecated, we have to create new_type wrapping sophia_term::Term, for each desired invariant. That is not as elegant as current.

[pchampin]

And in above case, there is good value in having a type that is a TTerm, and guaranteed to be an iri among all kinds.

Absolutely. But the types defined in sophia_iri fullfil this purpose already. sophia_iri::iri::Iri is mostly redundant in this respect (it only continues to exist)

As it is known that, a term can be of any of few standard invariants, we can have dedicated invariant for each kind and an enum sum type wrapping all cases.

Agreed again. This will be kept in the new design. And all "invariant types" (bnode identifier, variable name), as well as the sum type, will be provided in sophia_api directly.

This is the model currently implemented by sophia_term::Term apis.

And this is a wrong separation of concerns --mostly due to historical reasons, as explained above.
In the next design, sophia_api::term will contain:

• the trait for terms
• invariant wrappers for the different kinds of terms
• a simple implementation of the trait as an enum around the different invariant wrapper
  (which will be usable as a replacement of RefTerm, BoxTerm and MownTerm)

and sophia_term will be dedicated to "data-sharing" implementations of the term trait (TermFactory, RcTerm and ArcTerm).

Note also that the next version of the trait will be more abstract than it currently is. This will enable nice stuff, like the ability to use i32 or f64 literals directly as terms.

[damooo]

Great if sophia_api itself provides those abstractions directly. _/\_