Protocol

Encode the following JSON formats into a single line string and pass them to psc-ide's stdin. You can then read the result from psc-ide's stdout as a single line. The result needs to be unwrapped from the "wrapper" which separates success from failure. This wrapper is described at the end of this document.

Command:

Load

The load command "loads" the requested modules into the server for completion and type info.

Params:

• modules :: (optional) [ModuleName]: A list of modules to load. psc-ide-server will try to parse all the declarations in these modules
• dependencies :: (optional) [ModuleName]: A list of modules to load including their dependencies. In contrast to the module field, all the imports in these Modules will also be loaded.

{
  "command": "load",
  "params": {
    "modules": (optional)["Module.Name1", "Module.Name2"],
    "dependencies": (optional)["Module.Name3"]
  }
}

Result:

The Load Command returns a string.

Type

The type command looks up the type for a given identifier.

Params:

• search :: String: The identifier to look for. Only matches on equality.
• filters :: [Filter]: These filters will be applied before looking for the identifier. These filters get combined with AND, so a candidate must match ALL of them to be eligible.

{
  "command": "type",
  "params": {
    "search": "filterM",
    "filters": [Filter]
  }
}

Result: The possible types are returned in the same format as completions

Complete

The complete command looks up possible completions/corrections.

Params:

• filters :: [Filter]: The same as for the type command. A candidate must match all filters.
• matcher :: (optional) Matcher: The strategy used for matching candidates after filtering. Results are scored internally and will be returned in the descending order where the nth element is better then the n+1-th.

If no matcher is given every candidate, that passes the filters, is returned in no particular order.

{
  "command": "complete",
  "params": {
    "filters": [Filter],
    "matcher": (optional) Matcher
  }
}

Result:

The following format is returned as the Result:

[
  {
  "module": "Data.Array",
  "identifier": "filter",
  "type": "forall a. (a -> Boolean) -> Array a -> Array a"
  }
]

CaseSplit

The CaseSplit command takes a line of source code, an area in that line of code and replaces it with all patterns for a given type. The parameter annotations is used to turn type annotations on or off for the constructor fields.

{
 "command": "caseSplit",
 "params": {
  "line": "elem a as",
  "begin": 8,
  "end": 10,
  "annotations": true,
  "type": "List"
 }
}

Result:

The following format is returned as the Result:

[
  "elem a Nil",
  "elem a (Cons (_ :: a) (_ :: List a))"
]

You should then be able to replace the affected line of code in the editor with the new suggestions.

Add Clause

The AddClause command takes a typedeclaration and generates a function template for the given type. The annotations option turns type annotations on or off for the function arguments.

{
 "command": "addClause",
 "params": {
  "line": "elem :: forall a. (Eq a) => a -> List a",
  "annotations": true
 }
}

Result:

The following format is returned as the Result:

[
  "elem :: forall a. (Eq a) => a -> List a",
  "elem ( _ :: a) = ?elem"
]

You should then be able to replace the affected line of code in the editor with the new suggestions.

Pursuit

The pursuit command looks up the packages/completions for a given identifier from Pursuit.

Params:

• query :: String: With type: "package" this should be a module name. With type: "completion" this can be any string to look up.
• type :: String: Takes the following values:
  • package: Looks for packages that contain the given module name.
  • completion Looks for declarations for the query from Pursuit.

{
  "command": "pursuit",
  "params": {
    "query": "Data.Array",
    "type": "package"
  }
}

Result:

package returns:

[
  {
  "module": "Module1.Name",
  "package": "purescript-packagename"
  }
]

completion returns:

[
  {
  "module": "Data.Array",
  "identifier": "filter",
  "type": "forall a. (a -> Boolean) -> Array a -> Array a",
  "package": "purescript-arrays"
  }
]

List

Loaded Modules

list of type loadedModules lists all loaded modules (This means they can be searched for completions etc)

{
  "command": "list",
  "params": {
    "type": "loadedModules"
  }
}

Response:

The list loadedModules command returns a list of strings.

Available Modules

list of type availableModules lists all available modules. (This basically means the contents of the output/ folder.))

{
  "command": "list",
  "params": {
    "type": "availableModules"
  }
}

Response:

The list availableModules command returns a list of strings.

Imports

The list commmand can also list the imports for a given file.

{
  "command": "list",
  "params": {
    "type": "import",
    "file": "/home/kritzcreek/Documents/psc-ide/examples/Main.purs"
  }
}

Response:

The list import command returns a list of imports where imports are of the following form:

Implicit Import(import Data.Array):

[
  {
  "module": "Data.Array",
  "importType": "implicit"
  }
]

Implicit qualified Import(import qualified Data.Array as A):

[
  {
  "module": "Data.Array",
  "importType": "implicit",
  "qualifier": "A"
  }
]

Explicit Import(import Data.Array (filter, filterM, join)):

[
  {
  "module": "Data.Array",
  "importType": "explicit",
  "identifiers": ["filter", "filterM", "join"]
  }
]

Hiding Import(import Data.Array hiding (filter, filterM, join)):

[
  {
  "module": "Data.Array",
  "importType": "hiding",
  "identifiers": ["filter", "filterM", "join"]
  }
]

Cwd/Quit

cwd returns the working directory of the server(should be your project root).

quit quits the server.

{
  "command": "cwd|quit"
}

Result: These commands return strings.

Filter:

Exact filter

The Exact filter only keeps identifiers that are equal to the search term.

{
  "filter": "exact",
  "params": {
    "search": "filterM"
  }
}

Prefix filter

The Prefix filter keeps identifiers/modules/data declarations that are prefixed by the search term.

{
   "filter": "prefix",
   "params": {
     "search": "filt"
   }
}

Module filter

The Module filter only keeps identifiers that appear in the listed modules.

{
   "filter": "modules",
   "params": {
     "modules": ["My.Module"]
   }
}

Dependency filter

The Dependency filter only keeps identifiers that appear in the listed modules and in any of their dependencies/imports.

{
  "filter": "dependencies",
  "params": {
    "modules": ["My.Module"]
  }
}

Matcher:

Flex matcher

Matches any occurence of the search string with intersections

The scoring measures how far the matches span the string, where closer is better. The matches then get sorted with highest score first.

Examples:

• flMa matches flexMatcher. Score: 14.28
• sons matches sortCompletions. Score: 6.25

{
  "matcher": "flex",
  "params": {
    "search": "filt"
  }
}

Distance Matcher

The Distance matcher is meant to provide corrections for typos. It calculates the edit distance in between the search and the loaded identifiers.

{
  "matcher": "distance",
  "params": {
    "search": "dilterM",
    "maximumDistance": 3
  }
}

Responses

All Responses are wrapped in the following format:

{
  "resultType": "success|error",
  "result": Result|Error
}

Error

Errors at this point are merely Error strings. Newlines are escaped like \n and should be taken care of by the editor-plugin.