<commit_before>External APIs
=============

Use *coala* to make your application better.

DBus
----

The *coala* DBus API essentially creates a server which can have multiple
clients connected to it. The clients communicate to the *coala* server
using DBus. To start the server, first install *coala* and then simple run
``coala-dbus``.

This spawns a bus with the name ``org.coala_analyzer.v1`` as a
SessionBus and can be verified and tested using a DBus debugger like
`DFeet <https://wiki.gnome.org/Apps/DFeet>`__. The bus has 1 object-path
by default - ``/org/coala_analyzer/v1``. This is the first point of
contact with *coala* for any client.

The object-path ``/org/coala_analyzer/v1`` has the interface
``org.coala_analyzer.v1`` which contains the two methods -
``CreateDocument`` and ``DisposeDocument``. These are used to tell *coala*
about the documents you wish to analyze.

``CreateDocument``
~~~~~~~~~~~~~~~~~~

**Args**: the path of the document

**Returns**: object-path for the document

A document is defined by it's path. The path should be a absolute path,
not a relative one. This method returns an object-path which will be
hence forth used to interact with that document.

``DisposeDocument``
~~~~~~~~~~~~~~~~~~~

**Args**: the path to the document

**Returns**: none

It disposes the object-path corresponding to the given path.

Now, the object-path returned by the ``CreateDocument`` method also has
the interface ``org.coala_analyzer.v1``. This interface is used to
handle which config file *coala* will use to analyze the document, and the
function to get analysis results. It contains 4 functions:
<commit_msg>Rework External_APIs.rst<commit_after>External APIs
=============

Use coala to make your application better.

DBus
----

The coala DBus API essentially creates a server which can have multiple
clients connected to it. The clients communicate to the coal* server
using DBus. To start the server, first
:doc:`install coala <Install>`
and then simply run ``coala-dbus``.

This spawns a bus with the name ``org.coala_analyzer.v1`` as a
SessionBus that can be verified and tested using a DBus debugger like
`DFeet <https://wiki.gnome.org/Apps/DFeet>`__. The bus has 1 object-path
by default - ``/org/coala_analyzer/v1``. This is the first point of
contact with coala for any client.

The object-path ``/org/coala_analyzer/v1`` has the interface
``org.coala_analyzer.v1`` which contains the two methods -
``CreateDocument`` and ``DisposeDocument``. These are used to tell coala
about the documents you wish to analyze.

``CreateDocument``
~~~~~~~~~~~~~~~~~~

**Args**: the path of the document

**Returns**: object-path for the document

A document is defined by its path. The path should be an absolute path,
not a relative one. This method returns an object-path which will be
hence forth used to interact with that document.

``DisposeDocument``
~~~~~~~~~~~~~~~~~~~

**Args**: the path to the document

**Returns**: none

It disposes the object-path corresponding to the given path.

Now, the object-path returned by the ``CreateDocument`` method also has
the interface ``org.coala_analyzer.v1``. This interface is used to
handle which config file coala will use to analyze the document, and the
function to get analysis results. It contains 4 functions:

{'fraction_non_alphanumeric': 0.11212397447584321, 'fraction_numerical': 0.00425402613187481, 'mean_word_length': 4.6563573883161515, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3706653', 'n_tokens_mistral': 937, 'n_tokens_neox': 911, 'n_words': 448}