README.md 5.53 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
- The `!cloogle` bang on DuckDuckGo.
- [@CloogleBot](https://telegram.me/CloogleBot) on Telegram (see
Camil Staps's avatar
Camil Staps committed
11 12 13
	[camilstaps/CloogleBot](https://github.com/clean-cloogle/CloogleBot)).
- [cloogle-cli](https://github.com/clean-cloogle/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)
Camil Staps's avatar
Camil Staps committed
25 26
- [HTTP API Specification](#http-api-specification)
- [TCP API Specification](#tcp-api-specification)
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
## Setup
34
After installing
Mart Lubbers's avatar
Mart Lubbers committed
35
[docker-compose](https://www.docker.com/products/docker-compose) run the
Camil Staps's avatar
Camil Staps committed
36
following command:
Mart Lubbers's avatar
Mart Lubbers committed
37

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

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

Camil Staps's avatar
Camil Staps committed
45 46 47
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
48 49 50 51 52 53 54 55 56 57 58 59 60 61

```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
62
## HTTP API specification
Mart Lubbers's avatar
Mart Lubbers committed
63
`api.php` should be called with a `GET` request where the `str` variable
Camil Staps's avatar
Camil Staps committed
64 65 66 67
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
68
The API will return a JSON formatted data structure containing the following
Camil Staps's avatar
Camil Staps committed
69
fields:
Mart Lubbers's avatar
Mart Lubbers committed
70

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

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

	* `0`: success
Mart Lubbers's avatar
Mart Lubbers committed
76
	* `1`: cache hit, thus success
Camil Staps's avatar
Camil Staps committed
77 78
	* `127`: no results
	* `128`: ununderstandable input (usually shouldn't happen)
Camil Staps's avatar
Camil Staps committed
79 80
	* `129`: invalid name field
	* `130`: couldn't parse unify field as a type
Camil Staps's avatar
Camil Staps committed
81 82 83
	* `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
84
	* `153`: the Clean backend timed out
85
	* `154`: you have sent too many requests; try again later (DoS protection)
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
	determines the kind of result. It may be `FunctionResult`, `TypeResult`,
Camil Staps's avatar
Camil Staps committed
95 96
	`ClassResult`, `MacroResult` or `ModuleResult`. 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 109
	`FunctionResultExtras`, `TypeResultExtras`, `ClassResultExtras`,
	`MacroResultExtras` and `ModuleResultExtras` to get an idea of the fields
	that may be returned.
110

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

117 118 119
- `suggestions`

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

Camil Staps's avatar
Camil Staps committed
123
## TCP API Specification
Camil Staps's avatar
Camil Staps committed
124
`CloogleServer` is a TCP server listening on port 31215 (typically). Send a
125 126 127 128 129
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
130
* `typeName`, the name of the type to search for.
Camil Staps's avatar
Camil Staps committed
131 132
* `libraries`, a list of names of libraries to search in.
* `include_builtins`, a boolean, whether language builtins should be searched or not.
133
* `include_core`, a boolean, whether library cores should be searched or not.
134 135
* `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
136

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

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
145 146 147 148 149
## Statistics
A websocket server on port 31216 provides you with the realtime log.

On [cloogle.org/stats/live.html](https://cloogle.org/stats/live.html), a
realtime usage chart is shown.
Camil Staps's avatar
Camil Staps committed
150

Camil Staps's avatar
Camil Staps committed
151 152 153 154
For longterm statistics you can see
[cloogle.org/stats/longterm.html](https://cloogle.org/stats/longterm.html).

## Authors
Camil Staps's avatar
Camil Staps committed
155 156 157 158 159 160 161
Maintainers:

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

Contributors:

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

164 165 166
## Copyright & License
Copyright © Mart Lubbers and Camil Staps.
Licensed under MIT; See the `LICENSE` file.