jpeddicord/askalono

Think about API

Closed this issue · 3 comments

jpeddicord commented

If you look at generated docs of the public API (while ignoring the lack of documentation) you'll note that while there is an API, it's not very complete and in some cases is a little inconsistent.

I've filed this issue to plan out what the API should look like long-term, starting with a 0.2 release.

See https://amzn.github.io/askalono/doc/askalono/ for the most up-to-date implementation.

  • Store

    • pretty much a HashMap<String, LicenseEntry>
    • Methods:
      • analyze(text: Into<TextData>) -> Result<Match, Error>
      • add(name: &str, Into<TextData>) - add a single license to the store
      • add_header(name: &str, Into<TextData>) - add a header for an existing license
      • add_alternate(name: &str, Into<TextData>) - add a header for an existing license
      • #[cfg(feature='spdx') load_spdx(directory, include_texts) - what it does today, a bit of a shortcut feature
      • ::from_cache(readable: R [Read + Sized])
      • to_cache(writable: W [Write + Sized])

  • LicenseEntry (crate-private)

    • Currently called LicenseData
    • pub(crate) fields original, alternates, headers (referring to TextData)
    • Not expected to be in public API, but writing here for my own sake

  • TextData

    • Fields (all private, but getter methods w/ same name for name/type):
      • name: Option<String>
      • type: LicenseType
      • match_data: MatchData (grams)
      • text_normalized: String (maybe Cow<str>)
      • text_processed: String (ditto on Cow)
    • Methods:
      • ::new(text: &str) - creates a TextData struct w/ no name; Unknown type, with match data computed and text strings stored
      • without_text() - consumes self and outputs a clone/move/whatever without text_* stuff stored. probably only going to be used by the caching mechanism; may start with this as crate visibility.
      • match(other: &TextData) -> f32 - compare self with other and output a score
    • Implements:
      • From<&str>

  • Enum LicenseType: Unknown, Original Header, Alternate

  • Match

    • Fields:
      • pub score: f32
      • pub data: &TextData

Minimal usage:

  1. let store = Store::from_cache(File::open(filename)?);
  2. let out = store.analyze("some string of license text") - since analyze is Into<TextData> and TextData has From<&str>
  3. println!("it's {} with score {}", out.data.name(), out.score);

My current reservations:

  • TextData has some duplicated information when it's stored together in Store, namely name and type. But I think there's some value in keeping that info with each license; it can be re-used as the output for Analyze.
  • add_x methods on Store feel weird.
jpeddicord commented

Going to have a go at implementing this today to see how it feels. No major changes needed behind the scenes, just moving some parts around.

jpeddicord commented

Merging these changes now; won't release 0.2 until I'm sure about it all though.

Stuck docs on https://amzn.github.io/askalono/doc/askalono/ of how this currently looks.

jpeddicord commented

Things feel "nice" with this API so far. Closing this issue.