# Birb

A library of utilities for GLib based applications.

## History

With the development of Pidgin 3 we've been trying to modularize and create
libraries that others are able to use as well. That also means that we didn't
have an easy way to reuse things between libraries.

We could make the libraries depend on each other, but that doesn't work in the
case where we would implement it in libpurple as those dependencies are needed
in libpurple or Pidgin and thus we have a circular dependency. Not only that,
but pulling in libpurple for a single class/API/whatever would bring in a lot
of unnecessary stuff.

So to simplify this dependency issue we decided to create yet another library
that would just have these pieces that we wanted to reuse. For example,
birb has adopted PurpleQueuedOutputStream which is a GOutputStream subclass
that manages a queue of output so you can't write as often as you like.

This was something we wanted to use in our new external XMPP library
[Xeme](https://keep.imfreed.org/xeme/xeme) that is the basis for our new
implementation in libpurple. Since it wouldn't make sense to have an external
library depend on libpurple for PurpleQueuedOutputStream we pulled it out and
put it here in Birb where it can be used much more easily.

## Plans

As previously mentioned we've already pulled in PurpleQueuedOutputStream as
BirbQueuedOutputStream but we do have more than just this planned.

There are a few things we want/need to build that need a verb based command
line parser. While you can technically do this with
[GOptionContext](https://docs.gtk.org/glib/struct.OptionContext.html), there's
a number of things you'd have to do to make that happen. Since we need this in
multiple libraries, we plan on implementing it here in Birb.

It would also be useful to us if we could parse a GMenu in GtkBuilder XML
format into a GMenu without using GtkBuilder due to the core/ui split nature of
libpurple. As such we would like to implement that here as well.

We're also looking at creating an object that can be used to populate a GMenu
via signals that would also gather GActionGroup's and their prefixes.

Last but not least, we need a simple implementation of StringPrep and precis
for a number of things. So we'd like to add at least a basic parser in here
to eliminate duplication across the libraries.

## Building

Birb uses [meson](https://mesonbuild.com/) as a build system. So the steps to
build are the same as any other project using meson:

```
meson setup build
meson compile -C build
meson test --verbose -C build
```

## Contributing

If you would like to contribute, please see our
[Contributing Guide](https://docs.imfreedom.org/contributors-guide/).

## API Reference

The full API reference can be found at
[docs.imfreedom.org/birb/](https://docs.imfreedom.org/birb/)

