Provide C API

[sorairolake]

As far as I know, there is no C implementation of djot yet. So, I think it would be nice if there is C bindings of this library.

see also: https://github.com/eqrion/cbindgen

[hellux]

Yes, the thought has crossed my mind also. Question is, how should the
API look like? The current API is quite Rust-focused and at least some
manual work would be needed to make a reasonable C-API on top of it.

Exposing a function that converts djot directly to html would be simple,
but djot to events and events to html would be a lot more useful.

• I guess c strings would not be an option, but rather custom types that
  work like &str (ptr + len) and Cow (&str or owned ptr + len +
  cap). Most strings are simply a view of the original source code, this
  is not possible with c-strings because then we would need to insert null
  values, overwriting the source code.

• Each event is a variant of the Event ADT/sum type. I guess this could
  be implemented as a tag in addition to a union for the data. Something
  like

  struct djot_event {
    djot_event_tag tag;
    djot_event_data data;
  };
  
  enum djot_event_tag {
    DJOT_EVENT_START;
    DJOT_EVENT_END;
    DJOT_EVENT_STR;
    DJOT_EVENT_SYMBOL;
    ..
  };
  
  union djot_event_data {
    struct { djot_container container; djot_attributes attributes } start;
    struct { djot_container container } end;
    djot_cow_str str;
    djot_cow_str symbol;
    ..
  };
  
  struct djot_container {
    djot_container_tag tag,
    djot_container_data data,
  };
  
  ..

• The parser is currently an iterator of Events, and the html renderer
  accepts any iterator of Events. We could provide the Parser::next
  function to allow pulling one event at a time from C. For the html
  rendering, the C implementation would need to implement a next
  function that allows the renderer to request the events. So, the C
  next function will be a callback that in turn calls Parser::next. Might
  look something like:

  jotdown.h:

  struct djot_parser;
  
  djot_event djot_parser_next(djot_parser*);
  
  typedef djot_event (*djot_next_event)(void *data);
  
  /* returned value is dynamically allocated, must be freed by caller. */
  char *djot_render_html(void *data, djot_next_event callback);

  some_client.c

  #include <jotdown.h>
  
  struct my_renderer {
    djot_parser parser;
    ..
  };
  
  my_renderer my_renderer_new() {
    ..
  }
  
  djot_event my_renderer_next_event(void *data) {
    struct my_renderer *r = (struct my_renderer*)data;
  
    struct djot_event ev = djot_parser_next(&r->parser);
  
    /* do something with event */
  
    return ev;
  }
  
  int main() {
    ..
    struct my_renderer r = my_renderer_new();
    char *html = djot_render_html(&r, my_renderer_next_event);
    ..
    free(html);
    ..
  }

I suppose it should be doable.

[hellux]

Actually, the lua reference implementation does have a minimal C API at https://github.com/jgm/djot.lua/tree/main/clib. It seems to expose direct rendering to HTML and json AST, and modification using lua filters.