Verified Commit 0e0c05c7 authored by Camil Staps's avatar Camil Staps 🙂

Documentation

parent 4dc66b6d
definition module Cloogle
/**
* The API for Cloogle, a Clean search engine.
* https://cloogle.org
*/
from StdOverloaded import class zero, class fromString, class toString,
class fromInt, class toInt, class <
from Data.Maybe import :: Maybe
from Text.JSON import generic JSONEncode, generic JSONDecode, :: JSONNode
/**
* A Cloogle request
*/
:: Request
= { unify :: Maybe String
, name :: Maybe String
, className :: Maybe String
, typeName :: Maybe String
, modules :: Maybe [String]
, libraries :: Maybe [String]
, include_builtins :: Maybe Bool
, include_core :: Maybe Bool
, page :: Maybe Int
= { unify :: Maybe String //* Functions that unify with this type
, name :: Maybe String //* Entries that match this name
, className :: Maybe String //* Exactly this class
, typeName :: Maybe String //* Exactly this type
, modules :: Maybe [String] //* Modules to search in
, libraries :: Maybe [String] //* Libraries to search in
, include_builtins :: Maybe Bool //* Whether language builtins should be included
, include_core :: Maybe Bool //* Whether library core modules should be included
, page :: Maybe Int //* Pagination of the results
}
/**
* A Cloogle response
*/
:: Response
= { return :: Int
, data :: [Result]
, msg :: String
, more_available :: Maybe Int
= { return :: Int //* A return code (use fromInt of CloogleError)
, data :: [Result] //* The actual results
, msg :: String //* A human-readable message describing the return code
, more_available :: Maybe Int //* How many more results are available in next pages
, suggestions :: Maybe [(Request, Int)]
//* Suggestions for related requests and how many results they have
}
/**
* A single Cloogle result
*/
:: Result
= FunctionResult FunctionResult
| TypeResult TypeResult
| ClassResult ClassResult
| MacroResult MacroResult
| ModuleResult ModuleResult
= FunctionResult FunctionResult //* A normal function, generic, class member, constructor or record field
| TypeResult TypeResult //* A type definition
| ClassResult ClassResult //* A class definition
| MacroResult MacroResult //* A macro
| ModuleResult ModuleResult //* A module
/**
* Basic data that is included in any Cloogle result
*/
:: BasicResult
= { library :: String
, filename :: String
, modul :: String
, dcl_line :: Maybe Int
, icl_line :: Maybe Int
, distance :: Int
, builtin :: Maybe Bool
, documentation :: Maybe String
= { library :: String //* The library the entry was found in
, filename :: String //* The basename of the definition module
, modul :: String //* The full (hierarchical) module name
, dcl_line :: Maybe Int //* The line in the definition module of this entry
, icl_line :: Maybe Int //* The line in the implementation module of this entry
, distance :: Int //* A distancy measure, lower is more relevant
, builtin :: Maybe Bool //* Whether this is a builtin function
, documentation :: Maybe String //* The CleanDoc description for this result
}
/**
* Cloogle result about a function, generic, class member, constructor or
* record field
*
* @representation A tuple of basic and function-specific data
*/
:: FunctionResult :== (BasicResult, FunctionResultExtras)
/**
* Function-specific Cloogle result data
*/
:: FunctionResultExtras
= { func :: String
, unifier :: Maybe StrUnifier
, cls :: Maybe ShortClassResult
, constructor_of :: Maybe String
, recordfield_of :: Maybe String
= { func :: String //* A string representation of the type
, unifier :: Maybe StrUnifier //* A unifier, if the request included a type
, cls :: Maybe ShortClassResult //* The class, if this is a class member
, constructor_of :: Maybe String //* The type that this is a constructor of
, recordfield_of :: Maybe String //* The type that this is a record field of
, generic_derivations :: Maybe [(String, [LocationResult])]
, param_doc :: Maybe [String]
, generic_var_doc :: Maybe [String]
, result_doc :: Maybe String
//* Derivations, if this is a generic function, and their locations
, param_doc :: Maybe [String] //* Documentation of the parameters
, generic_var_doc :: Maybe [String] //* Documentation of the generic type variables
, result_doc :: Maybe String //* Documentation of the result
}
/**
* Cloogle result about a type definition
*
* @representation A tuple of basic and type-specific data
*/
:: TypeResult :== (BasicResult, TypeResultExtras)
/**
* Type-specific Cloogle result data
*/
:: TypeResultExtras
= { type :: String
//* A string representation of the definition
, type_instances :: [(String, [String], [LocationResult])]
//* Instances of the type: the class, the class parameters and the locations of the instance
, type_derivations :: [(String, [LocationResult])]
//* Generic derivations of the type: the generic and the locations of the derivation
, type_field_doc :: Maybe [Maybe String]
//* Documentation of the record fields
, type_constructor_doc :: Maybe [Maybe String]
//* Documentation of the constructors
, type_representation_doc :: Maybe String
//* Documentation of the synonym type representation
}
/**
* Cloogle result about a class definition
*
* @representation A tuple of basic and class-specific data
*/
:: ClassResult :== (BasicResult, ClassResultExtras)
/**
* Class-specific Cloogle result data
*/
:: ClassResultExtras
= { class_name :: String
, class_heading :: String
, class_funs :: [String]
= { class_name :: String //* The name of the class
, class_heading :: String //* The class name and variables
, class_funs :: [String] //* The class members (may contain newlines if there are macros)
, class_instances :: [([String], [LocationResult])]
//* Instances of the class: the types and the locations of the instances
}
/**
* Cloogle result about a macro
*
* @representation A tuple of basic and macro-specific data
*/
:: MacroResult :== (BasicResult, MacroResultExtras)
/**
* Macro-specific Cloogle result data
*/
:: MacroResultExtras
= { macro_name :: String
, macro_representation :: String
, macro_param_doc :: Maybe [String]
, macro_result_doc :: Maybe String
= { macro_name :: String //* The name
, macro_representation :: String //* A string representation
, macro_param_doc :: Maybe [String] //* Documentation of the parameters
, macro_result_doc :: Maybe String //* Documentation of the result
}
/**
* Cloogle result about a module
*
* @representation A tuple of basic and module-specific data
*/
:: ModuleResult :== (BasicResult, ModuleResultExtras)
/**
* Module-specific Cloogle result data
*/
:: ModuleResultExtras
= { module_is_core :: Bool
= { module_is_core :: Bool //* Whether this module is part of a library core
}
/**
* A location in a Clean library
*
* @representation The library, the module, the line in the definition module
* and the line in the implementation module
*/
:: LocationResult :== (String, String, Maybe Int, Maybe Int)
/**
* A type unifier, represented with strings
*/
:: StrUnifier
= { left_to_right :: [(String,String)]
, right_to_left :: [(String,String)]
, used_synonyms :: [(String,String)]
= { left_to_right :: [(String,String)] //* Transformations from request to response
, right_to_left :: [(String,String)] //* Transformations from response to request
, used_synonyms :: [(String,String)] //* Synonyms that were used during unification
}
:: ShortClassResult = { cls_name :: String, cls_vars :: [String] }
/**
* Basic data about a class definition
*/
:: ShortClassResult
= { cls_name :: String //* The name
, cls_vars :: [String] //* The type variables
}
/**
* A Cloogle Error
*/
:: CloogleError
/* Cloogle system errors */
= NoResults
| InvalidInput
| InvalidName
| InvalidType
= NoResults //* No matching entries were found
| InvalidInput //* The input is invalid (e.g., combining typeName and className)
| InvalidName //* The name is invalid (e.g., contains spaces)
| InvalidType //* A type could not be parsed (e.g., in unify)
/* Cloogle.org errors */
| ServerDown
| IllegalMethod
| IllegalRequest
| ServerTimeout
| DosProtection
| ServerDown //* The Cloogle backend could not be reached
| IllegalMethod //* Incorrect HTTP method to the API
| IllegalRequest //* Incorrect parameters to the API
| ServerTimeout //* Connection to the Cloogle backend timed out
| DosProtection //* Too many requests from this client, try again later
/* Wildcard to make fromInt total */
| OtherCloogleError String
| OtherCloogleError String //* Another Cloogle error
instance toInt CloogleError
instance fromInt CloogleError
......
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