hoogle clone for Clean
Clean JavaScript HTML PHP CSS Python Other
Latest commit 95dd74e Feb 13, 2017 @camilstaps camilstaps oops

README.md

Cloogle

A Clean hoogle clone: search for functions, types, and classes from the Clean standard libraries.

Use any of the available frontends:


Readme contents


Setup

After installing docker-compose run the following command:

docker-compose up

Your Cloogle server now runs at port 31215 on your local machine. The web frontend is available at port 80, live statistics at port 31216.

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:

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;
    }
}

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:

  • return

    Return code:

    • 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)
  • msg

    A human friendly message representing the return code.

  • data

    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, MacroResult or ModuleResult. The second contains general data, in particular the following fields:

    • 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)

    The third element of the array contains data specific to the kind of result. It is easiest to look in backend/Cloogle.dcl at the types FunctionResultExtras, TypeResultExtras, ClassResultExtras, MacroResultExtras and ModuleResultExtras to get an idea of the fields that may be returned.

  • 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. If there are no more results, this field may be zero or may not be present.

  • suggestions

    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.

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.
  • 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.

Statistics

A websocket server on port 31216 provides you with the realtime log.

On cloogle.org/stats/live.html, a realtime usage chart is shown.

For longterm statistics you can see cloogle.org/stats/longterm.html.

Authors

Maintainers:

Contributors:

Copyright & License

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