Verified Commit ecefe7b1 authored by Camil Staps's avatar Camil Staps 🚀

Clean up readme

parent ca73ee61
# Cloogle [![][travis badge]][travis]
A Clean hoogle clone: search for functions, types, and classes from the Clean
standard libraries.
Use any of the available frontends:
- Web app at [cloogle.org](https://cloogle.org/).
- The `!cloogle` bang on DuckDuckGo.
- [@CloogleBot](https://telegram.me/CloogleBot) on Telegram (see
[CloogleBot](https://github.com/clean-cloogle/CloogleBot)).
- [cloogle-cli](https://github.com/clean-cloogle/cloogle-cli), a command line
interface to the api.
- The `:Cloogle` command in
[camilstaps/vim-clean](https://github.com/camilstaps/vim-clean).
- An email to `query@cloogle.org` with the query in the subject (see
[cloogle-mail](https://github.com/clean-cloogle/cloogle-mail)).
- The IRC bot which often resides on the `#cloogle` channel and the general
Clean channel `#cleanlang` on [freenode][].
(see [clean-irc](https://github.com/clean-cloogle/clean-irc)).
For support and/or contact please join us at the `#cloogle` irc channel on
[freenode][].
The [Clean][] language search engine. Cloogle lets you search for functions,
types, classes and modules from Clean libraries. The web app is available at
[cloogle.org][]. Cloogle was inspired by [Hoogle][].
---
### Readme contents
**Readme contents**
- [HTTP API Specification](#http-api-specification)
- [TCP API Specification](#tcp-api-specification)
- [Library browser](#library-browser)
- [Statistics](#statistics)
- [Setup](#setup)
- [Authors](#authors)
- [Copyright & License](#copyright--license)
- [Frontends](#frontends)
- [Auxiliary tools](#auxiliary-tools)
- [Interfacing with Cloogle](#interfacing-with-cloogle)
- [Preparing a library for indexing](#preparing-a-library-for-indexing)
- [Local setup](#local-setup)
- [Authors, copyright & license](#authors-copyright--license)
---
## HTTP API specification
`api.php` should be called with a `GET` request where the `str` variable
contains the search string. You may also add `mod` (a comma-separated list of
modules to search in) and `page` (for pagination: 0 for the first *n* results,
1 for the next *n*, etc.).
The API will return a JSON formatted data structure containing the following
fields:
## Frontends
These frontends to Cloogle are currently known to us:
- `return`
Return code:
- The web app at [cloogle.org][].
- The `!cloogle` bang on DuckDuckGo.
- [@CloogleBot][] on Telegram (see [CloogleBot][]).
- [cloogle-cli][], a command line interface to the API.
- The `:Cloogle` command or `<LocalLeader>c`in [vim-clean][].
- An email to `query@cloogle.org` with the query in the subject
(see [cloogle-mail][]).
- The IRC bot which often resides on the `#cloogle` channel and the general
Clean channel `#cleanlang` on [freenode][] (see [clean-irc][]).
* `0`: success
* `1`: cache hit, thus success
* `127`: no results
* `128`: ununderstandable input (usually shouldn't happen)
* `129`: invalid name field
* `130`: couldn't parse unify field as a type
* `150`: the Clean backend could not be reached
* `151`: invalid request type (should use GET)
* `152`: no input (GET variable `str` should be set to the search string)
* `153`: the Clean backend timed out
* `154`: you have sent too many requests; try again later (DoS protection)
* `155`: the query was too long
## Auxiliary tools
Several tools used in Cloogle are available as separate libraries from
[github.com/clean-cloogle](https://github.com/clean-cloogle). Additionally,
these tools can be helpful:
- `msg`
**[Cloogle-tags][cloogle-tags]:**
This program lets you index local Clean code in *tagfiles* that can be used by
your text editor.
A human friendly message representing the return code.
**Library browser:**
The frontend includes a library browser to browse through all known Clean
libraries. The browser can be accessed through
[cloogle.org/src](https://cloogle.org/src).
- `data`
**Documentation browser:**
There is also an HTML version of the Clean Language Report, available at
[cloogle.org/doc](https://cloogle.org/doc).
An array of search results. A result is an array of three elements. The first
determines the kind of result. It may be `FunctionResult`, `TypeResult`,
`ClassResult`, or `ModuleResult`. The second contains general data, in
particular the following fields:
**Logging:**
A websocket server on port 31216 provides the realtime [cloogle.org][] log.
* `library`
* `modul`: the module the result was found in (not a typo)
* `filename`: the filename of the definition module
* `dcl_line`: the line where the definition is found
* `distance`: the distance measure we use to sort the results (lower is
better)
**Statistics:**
On [cloogle.org/stats/live.html](https://cloogle.org/stats/live.html), a
realtime usage chart is shown. For longterm statistics you can see
[cloogle.org/stats/longterm.html](https://cloogle.org/stats/longterm.html).
The third element of the array contains data specific to the kind of result.
It is easiest to look in
[`Cloogle.dcl`](https://github.com/clean-cloogle/libcloogle/blob/master/Cloogle.dcl)
at the types
`FunctionResultExtras`, `TypeResultExtras`, `ClassResultExtras`,
and `ModuleResultExtras` to get an idea of the fields that may be returned.
## Interfacing with Cloogle
**TCP API**
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
JSON request in the format described by the `Request` type in [Cloogle.dcl][],
followed by a newline character. The response is in the format described by the
`Response` type. The connection is kept alive for some time to allow further
requests.
- `more_available`
To interface with Cloogle, it is recommended that you use the HTTP API rather
than the TCP API.
If there are more results that can be found using pagination, this will be
the number of results that have a higher distance than the last result sent.
If there are no more results, this field *may* be zero or may not be present.
For a Clean interface to Cloogle, it is suggested that you use [libcloogle][].
- `suggestions`
For a Python interface to Cloogle, you can use [cloogle.py][].
If there are similar searches that may return more results, this will be an
array of two-tuples with the alternative search (which has the same fields as
a request) and the number of results.
**HTTP API**
The HTTP API is a simple wrapper around the TCP API, with a more stable API.
`api.php` should be called with a `GET` request where the `str` parameter
contains the search string. You may also add `mod` (a comma-separated list of
modules to search in) and `page` (for pagination: 0 for the first *n* results,
1 for the next *n*, etc.). For the query syntax in the `str` parameter, see the
'How to use' guidelines on [cloogle.org][].
## TCP API Specification
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
JSON request with at least one of the following fields:
* `unify`, the type to search for as a string.
* `name`, the name of the function to search for.
* `className`, the name of the class to search for.
* `typeName`, the name of the type to search for.
* `libraries`, a list of names of libraries to search in.
* `include_builtins`, a boolean, whether language builtins should be searched or not.
* `include_core`, a boolean, whether library cores should be searched or not.
* `include_apps`, a boolean, whether apps should be searched or not.
* `modules`, a list of names of modules to search in.
* `page`: 0 for the first *n* results, 1 for the next *n*, etc.
All fields are optional. If `className` is present, `unify` and `name` will be
ignored. If `typeName` is present (and `className` is not), `unify` and `name`
will be ignored.
The Clean backend will return a JSON string, similar to the output of the PHP
script described above. The error codes above 150 are specific to the script
and cannot be returned by the Clean backend.
## Library browser
The frontend includes a library browser to browse through all known Clean
libraries. The browser can be accessed through
[cloogle.org/src](https://cloogle.org/src).
The API returns the same JSON as the TCP API, but may include additional
results when searched for Clean error messages (for example, `stack overflow`).
These error messages are indexed by the frontend rather than the backend.
Additionally, the HTTP API may give return codes above 150, which are not used
by the TCP API. For the meaning of the return codes, see [Cloogle.icl][].
## Statistics
A websocket server on port 31216 provides you with the realtime log.
## Preparing a library for indexing
Your library will be most easily accessible when:
On [cloogle.org/stats/live.html](https://cloogle.org/stats/live.html), a
realtime usage chart is shown.
- Functions, type definitions, classes and modules are documented. For details
on the documentation format, see the README of the [Cloogle][] submodule.
- Macros have types using the `@type` documentation field.
For longterm statistics you can see
[cloogle.org/stats/longterm.html](https://cloogle.org/stats/longterm.html).
Having documentation is not a strict requirement, however.
To add your library to the index, follow the steps in
[CONTRIBUTING.md](/CONTRIBUTING.md#3-i-just-want-to-add-library-x) and create a
pull request.
## Setup
After installing
[docker-compose](https://www.docker.com/products/docker-compose) run the
following commands:
## Local setup
After installing [docker-compose][] run the following commands:
```bash
touch cloogle.log
......@@ -172,18 +131,16 @@ Or the following apache2 virtualhost (be sure to enable `mod_proxy`).
<VirtualHost *:80>
ServerName cloogle.org
ServerAdmin webmaster@cloogle.org
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/cloogle.org.log combined
ProxyRequests off
ProxyPass / http://localhost:31280/
ProxyPassReverse / http://localhost:31280/
</VirtualHost>
```
## Authors
## Authors, copyright &amp; license
Cloogle is Copyright &copy; Mart Lubbers and Camil Staps.
Licensed under MIT; See the [LICENSE](/LICENSE) file.
Maintainers:
- [dopefishh](https://github.com/dopefishh)
......@@ -194,10 +151,24 @@ Contributors:
- [ErinvanderVeen](https://github.com/ErinvanderVeen) (logo and UI design)
- [KDercksen](https://github.com/KDercksen) (searching on module; help text)
## Copyright &amp; License
Copyright &copy; Mart Lubbers and Camil Staps.
Licensed under MIT; See the `LICENSE` file.
[cloogle.org]: https://cloogle.org
[Cloogle]: https://github.com/clean-cloogle/Cloogle
[libcloogle]: https://github.com/clean-cloogle/libcloogle
[Cloogle.dcl]: https://github.com/clean-cloogle/libcloogle/blob/master/Cloogle.dcl
[Cloogle.icl]: https://github.com/clean-cloogle/libcloogle/blob/master/Cloogle.icl
[CloogleBot]: https://github.com/clean-cloogle/CloogleBot
[@CloogleBot]: https://telegram.me/CloogleBot
[cloogle-tags]: https://github.com/clean-cloogle/cloogle-tags
[cloogle-cli]: https://github.com/clean-cloogle/cloogle-cli
[cloogle-mail]: https://github.com/clean-cloogle/cloogle-mail
[clean-irc]: https://github.com/clean-cloogle/clean-irc
[cloogle.py]: https://github.com/clean-cloogle/cloogle.py
[Clean]: http://clean.cs.ru.nl
[vim-clean]: https://github.com/camilstaps/vim-clean
[docker-compose]: https://www.docker.com/products/docker-compose
[Hoogle]: https://github.com/ndmitchell/hoogle
[travis badge]: https://api.travis-ci.org/clean-cloogle/cloogle.org.svg?branch=master
[travis]: https://travis-ci.org/clean-cloogle/cloogle.org
[freenode]: https://freenode.net
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment