The Penrose API
This page documents a set of API functions provided by the Haskell backend, available in the following forms:
- WebSocket server: when running Penrose in editor or renderer modes, the server takes JSON wrappers of the API function calls.
- The command-line interface:
penrose runAPIis a command-line version that takes input viastdinand outputs instdout. The JSON formats are the same.
We use the standard Aeson encoding for the JSON input/output of the API functions, represented as the APICall type:
data APICall
= Step Int
State
| Resample Int
State
| StepUntilConvergence State
| CompileTrio String
String
String
| ReconcileNext State
String
String
String
| GetEnv String
String
| GetVersioncompileTrio ::
String -- ^ a Substance program
-> String -- ^ a Style program
-> String -- ^ an Element program
-> Either CompilerError (State, VarEnv) -- ^ an initial state and compiler context for language services
getEnv ::
String -- ^ a Substance program
-> String -- ^ an Element program
-> Either CompilerError VarEnv -- ^ either a compiler error or an environment of the Substance program
step ::
State -- ^ the initial state
-> Int -- ^ the number of steps n for the optimizer to take
-> Either RuntimeError State -- ^ the resulting state after the optimizer takes n steps
resample ::
State -- ^ the initial state
-> Int -- ^ number of samples to choose from (> 0). If it's 1, no selection will occur
-> Either RuntimeError State -- ^ if the number of samples requested is smaller than 1, return error, else return the resulting state
getVersion :: String -- ^ the current version of the Penrose binary
-- Experimental API function for generating a new State given an existing State. To be used to incrementally compile Substance programs.
reconcileNext ::
State -> String -> String -> String -> Either CompilerError (State, VarEnv