README.md 5.11 KB
Newer Older
Camil Staps's avatar
Camil Staps committed
1
# Cloogle
Mart Lubbers's avatar
Mart Lubbers committed
2

Camil Staps's avatar
Camil Staps committed
3 4
A Clean hoogle clone: search for functions, types, and classes from the Clean
standard libraries.
5

Camil Staps's avatar
Camil Staps committed
6
Use any of the available frontends:
Mart Lubbers's avatar
Mart Lubbers committed
7

8
- Web app at [cloogle.org](https://cloogle.org/).
Camil Staps's avatar
Camil Staps committed
9 10 11 12 13
- The `!cloogle` bang on DuckDuckGo.
- [@CloogleBot](https://telegram.me/CloogleBot) on Telegram (see
	[camilstaps/CloogleBot](https://github.com/camilstaps/CloogleBot)).
- [KDercksen/cloogle-cli](https://github.com/KDercksen/cloogle-cli), a command
	line interface to the api.
14 15
- The `:Cloogle` command in
	[camilstaps/vim-clean](https://github.com/camilstaps/vim-clean).
Camil Staps's avatar
Camil Staps committed
16
- An email to `query@cloogle.org` with the query in the subject (see
17 18
	[this gist](https://gist.github.com/camilstaps/bf719319d90d974329ee7e4ad08f1aa2)
	for the implementation).
19 20 21

---

Camil Staps's avatar
Camil Staps committed
22
### Readme contents
23

Camil Staps's avatar
Camil Staps committed
24
- [Setup](#setup)
25 26
- [API specification of the PHP wrapper](#api-specification-for-developers)
- [API specification of the Clean backend](#talking-with-the-clean-backend-directly)
27
- [Statistics](#statistics)
28
- [Authors](#authors)
29
- [Copyright & License](#copyright--license)
30 31

---
Mart Lubbers's avatar
Mart Lubbers committed
32

Camil Staps's avatar
Camil Staps committed
33 34
## Setup

35
After installing
Mart Lubbers's avatar
Mart Lubbers committed
36
[docker-compose](https://www.docker.com/products/docker-compose) run the
Camil Staps's avatar
Camil Staps committed
37
following command:
Mart Lubbers's avatar
Mart Lubbers committed
38

39
```bash
40
docker-compose up
41
```
Camil Staps's avatar
Camil Staps committed
42

43
Your Cloogle server now runs at port `31215` on your local machine.
Camil Staps's avatar
Camil Staps committed
44
The web frontend is available at port `80`, live statistics at port `31216`.
Camil Staps's avatar
Camil Staps committed
45

Camil Staps's avatar
Camil Staps committed
46 47 48
If you intend to run this on a server that has port 80 occupied already, you
can use nginx as a proxy. Change `80:80` to `31280:80` in `docker-compose.yml`
and use the following nginx config:
Camil Staps's avatar
Camil Staps committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62

```nginx
server {
	listen [::]:80;
	server_name cloogle.org;

	location / {
		proxy_pass http://127.0.0.1:31280;
		proxy_set_header Host $host;
		proxy_set_header X-Forwarded-For $remote_addr;
	}
}
```

Camil Staps's avatar
Camil Staps committed
63
## HTTP API specification
Mart Lubbers's avatar
Mart Lubbers committed
64
`api.php` should be called with a `GET` request where the `str` variable
Camil Staps's avatar
Camil Staps committed
65 66 67 68
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.).

Camil Staps's avatar
Camil Staps committed
69
The API will return a JSON formatted data structure containing the following
Camil Staps's avatar
Camil Staps committed
70
fields:
Mart Lubbers's avatar
Mart Lubbers committed
71

Mart Lubbers's avatar
Mart Lubbers committed
72
- `return`
Mart Lubbers's avatar
Mart Lubbers committed
73

Camil Staps's avatar
Camil Staps committed
74 75 76
	Return code:

	* `0`: success
Mart Lubbers's avatar
Mart Lubbers committed
77
	* `1`: cache hit, thus success
Camil Staps's avatar
Camil Staps committed
78 79
	* `127`: no results
	* `128`: ununderstandable input (usually shouldn't happen)
Camil Staps's avatar
Camil Staps committed
80 81
	* `129`: invalid name field
	* `130`: couldn't parse unify field as a type
Camil Staps's avatar
Camil Staps committed
82 83 84
	* `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)
Camil Staps's avatar
Camil Staps committed
85
	* `153`: the Clean backend timed out
Camil Staps's avatar
Camil Staps committed
86

Mart Lubbers's avatar
Mart Lubbers committed
87
- `msg`
Mart Lubbers's avatar
Mart Lubbers committed
88 89

	A human friendly message representing the return code.
Camil Staps's avatar
Camil Staps committed
90

Mart Lubbers's avatar
Mart Lubbers committed
91
- `data`
Mart Lubbers's avatar
Mart Lubbers committed
92

93
	An array of search results. A result is an array of three elements. The first
Camil Staps's avatar
Camil Staps committed
94 95 96
	determines the kind of result. It may be `FunctionResult`, `TypeResult`,
	`ClassResult` or `MacroResult`. The second contains general data, in
	particular the following fields:
Camil Staps's avatar
Camil Staps committed
97 98 99

	* `library`
	* `modul`: the module the result was found in (not a typo)
Camil Staps's avatar
Camil Staps committed
100 101
	* `filename`: the filename of the definition module
	* `dcl_line`: the line where the definition is found
Camil Staps's avatar
Camil Staps committed
102 103 104
	* `distance`: the distance measure we use to sort the results (lower is
		better)

105
	The third element of the array contains data specific to the kind of result.
Camil Staps's avatar
Camil Staps committed
106
	It is easiest to look in `backend/Cloogle.dcl` at the types
Camil Staps's avatar
Camil Staps committed
107 108
	`FunctionResultExtras`, `TypeResultExtras`, `ClassResultExtras` and
	`MacroResultExtras` to get an idea of the fields that may be returned.
109

Camil Staps's avatar
Camil Staps committed
110 111 112 113
- `more_available`

	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.
Camil Staps's avatar
Camil Staps committed
114
	If there are no more results, this field *may* be zero or may not be present.
Camil Staps's avatar
Camil Staps committed
115

116 117 118
- `suggestions`

	If there are similar searches that may return more results, this will be an
119 120
	array of two-tuples with the alternative search (which has the same fields as
	a request) and the number of results.
121

Camil Staps's avatar
Camil Staps committed
122
## TCP API Specification
Camil Staps's avatar
Camil Staps committed
123
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
124 125 126 127 128
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.
Camil Staps's avatar
Camil Staps committed
129
* `typeName`, the name of the type to search for.
130 131 132
* `libraries`, a list of two elements:
	* A list of names of libraries to search in
	* A boolean, whether language builtins should be searched or not.
133 134
* `modules`, a list of names of modules to search in.
* `page`: 0 for the first *n* results, 1 for the next *n*, etc.
Camil Staps's avatar
Camil Staps committed
135

136
All fields are optional. If `className` is present, `unify` and `name` will be
Camil Staps's avatar
Camil Staps committed
137 138
ignored. If `typeName` is present (and `className` is not), `unify` and `name`
will be ignored.
Camil Staps's avatar
Camil Staps committed
139 140 141 142 143

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.

Camil Staps's avatar
Camil Staps committed
144
## Authors
Camil Staps's avatar
Camil Staps committed
145 146 147 148 149 150 151 152

Maintainers:

- [dopefishh](https://github.com/dopefishh)
- [Camil Staps](https://camilstaps.nl)

Contributors:

Camil Staps's avatar
Camil Staps committed
153
- [KDercksen](https://github.com/KDercksen) (searching on module; help text)
Camil Staps's avatar
Camil Staps committed
154

155
## Copyright & License
Mart Lubbers's avatar
Mart Lubbers committed
156

157 158
Copyright © Mart Lubbers and Camil Staps.
Licensed under MIT; See the `LICENSE` file.