or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast.mdbuild.mdcli.mdcodegen.mdcorefn.mddocs.mderrors.mdide.mdindex.mdinteractive.mdparser.mdsugar.mdtypes.md
tile.json

index.mddocs/

PureScript

PureScript is a strongly typed functional programming language that compiles to JavaScript. Inspired by Haskell, it features advanced type system capabilities including higher-kinded types, type classes, and row polymorphism. The compiler provides comprehensive tooling including IDE integration, incremental compilation, and documentation generation for building reliable web applications and libraries.

Package Information

  • Package Name: purescript
  • Package Type: hackage
  • Language: Haskell (compiler), PureScript (target language)
  • Installation:
    • Haskell: cabal install purescript or stack install purescript
    • npm wrapper: npm install -g purescript

Core Imports

Using the Haskell library:

import Language.PureScript

For specific functionality:

import Language.PureScript.Make (make, rebuildModule, MakeActions)
import Language.PureScript.Ide (handleCommand)
import Language.PureScript.AST
import Language.PureScript.Types

Basic Usage

Command Line Compilation

# Compile PureScript files to JavaScript
purs compile "src/**/*.purs" "bower_components/*/src/**/*.purs"

# Start IDE server for editor integration
purs ide server --directory .

# Generate documentation
purs docs "src/**/*.purs" --format markdown

Haskell Library Usage

import Language.PureScript
import Language.PureScript.Make
import Language.PureScript.Options

-- Compile a PureScript project
main :: IO ()
main = do
  let options = defaultOptions { optionsVerboseErrors = True }
  result <- runMake options $ make []
  case result of
    Left errors -> print errors
    Right _ -> putStrLn "Compilation successful"

Architecture

PureScript's compiler architecture consists of several key phases and components:

  • Frontend: Parser (CST) → AST → Desugaring → Type Checking
  • Core: Functional representation (CoreFn) with optimization passes
  • Backend: JavaScript code generation with source maps and optimization
  • IDE Integration: Language server with completion, type info, and rebuilding
  • Build System: Incremental compilation with dependency tracking and caching

The compiler supports multiple output targets and provides extensive tooling for modern development workflows including hot reloading, IDE integration, and comprehensive error reporting.

Capabilities

Command Line Interface

The purs executable provides commands for compilation, documentation generation, IDE server, and project analysis.

purs compile [FILES...] [OPTIONS]
purs docs [FILES...] [OPTIONS]
purs ide (server|client) [OPTIONS]
purs repl [OPTIONS]
purs graph [FILES...] [OPTIONS]
purs hierarchy [FILES...] [OPTIONS]
purs publish [OPTIONS]

Command Line Interface

Core AST and Language Constructs

Abstract syntax tree types and language constructs for representing PureScript code including declarations, expressions, types, and patterns.

data Module = Module SourceSpan [Comment] ModuleName [Declaration] (Maybe [DeclarationRef])

data Declaration
  = DataDeclaration SourceAnn DataDeclType ProperName [TypeVarBinding] [DataConstructorDeclaration]
  | TypeSynonymDeclaration SourceAnn ProperName [TypeVarBinding] SourceType
  | ValueDeclaration ValueDeclarationData
  | TypeClassDeclaration SourceAnn ProperName [TypeVarBinding] [SourceConstraint] [FunctionalDependency] [Declaration]
  | TypeInstanceDeclaration SourceAnn ChainId Integer Ident [SourceConstraint] Qualified (Either Text ProperName) [SourceType] TypeInstanceBody
  -- ... other constructors

AST and Language Constructs

Type System

Advanced type system with type inference, kind checking, constraint solving, and support for higher-kinded types, type classes, and row polymorphism.

data Type a
  = TUnknown a Int
  | TypeVar a Text
  | TypeLevelString a PSString
  | TypeConstructor a (Qualified (ProperName 'TypeName))
  | TypeApp a (Type a) (Type a)
  | ForAll a TypeVarVisibility (ProperName 'TypeName) (Maybe (Type a)) (Type a) (Maybe SkolemScope)
  | ConstrainedType a (Constraint a) (Type a)
  -- ... other constructors

type SourceType = Type SourceAnn
type SourceConstraint = Constraint SourceAnn

Type System

Parser and Concrete Syntax Tree

Parser for PureScript syntax with layout rules, error recovery, and complete preservation of syntactic information including comments and whitespace.

parseModule :: Text -> Either ParseError (Module SourceAnn)

data CST.Module a = Module
  { modAnn :: a
  , modKeyword :: Token
  , modName :: Name ModuleName
  , modExports :: Maybe (DelimitedNonEmpty (Export a))
  , modWhere :: Token
  , modImports :: [ImportDecl a]
  , modDecls :: [Declaration a]
  }

Parser and CST

Build System and Compilation

Make system with incremental compilation, dependency resolution, and configurable build actions for custom compilation workflows.

make :: [FilePath] -> Make [ExternsFile]

rebuildModule :: [FilePath] -> Module -> Make ExternsFile

data MakeActions m = MakeActions
  { getInputTimestamp :: ModuleName -> m (Either RebuildPolicy UTCTime)
  , getOutputTimestamp :: ModuleName -> m (Maybe UTCTime)
  , readExterns :: ModuleName -> m (FilePath, B.ByteString)
  , codegen :: CF.Module CF.Ann -> Doc Text -> Linker -> m ()
  , ffiCodegen :: CF.Module CF.Ann -> m ()
  , progress :: ProgressMessage -> m ()
  }

Build System

IDE Integration

Language server functionality providing completion, type information, case splitting, and incremental rebuilding for editor integration.

handleCommand :: IdeEnvironment -> Command -> IO (Either IdeError Success)

data Command
  = Load [FilePath]
  | Type Text Int Int
  | Complete Text Text Int Int
  | CaseSplit Text Int Int WildcardAnns Text
  | AddClause Text Int Int
  | Import FilePath Text Int Int Text
  | List LoadedModulesFilter
  | Quit
  | Reset
  | Pursuit PursuitQuery
  | RebuildFile FilePath

IDE Integration

JavaScript Code Generation

Code generation from CoreFn to JavaScript with optimization passes, source maps, and runtime system integration.

moduleToJs :: CF.Module CF.Ann -> Doc Text

data JS = JSNumericLiteral (Either Integer Double)
        | JSStringLiteral PSString
        | JSBooleanLiteral Bool
        | JSArrayLiteral [JS]
        | JSObjectLiteral [(PSString, JS)]
        | JSBlock [JS]
        | JSVar Ident
        -- ... other constructors

Code Generation

Documentation Generation

Documentation extraction and generation in multiple formats including HTML and Markdown with cross-references and type information.

collectDocs :: [Module] -> Either MultipleErrors [DocModule]

writeDocMarkdown :: DocModule -> Text

writeDocHtml :: DocModule -> Text

data DocModule = DocModule
  { dmName :: ModuleName
  , dmComments :: Maybe Text
  , dmDeclarations :: [DocDeclaration]
  , dmReExports :: [(InPackage ModuleName, [DocDeclaration])]
  }

Documentation

Error Handling and Reporting

Comprehensive error reporting system with source positions, suggestions, and multiple output formats including JSON for tooling integration.

data MultipleErrors = MultipleErrors Bool [ErrorMessage]

data ErrorMessage = ErrorMessage [ErrorMessageHint] SimpleErrorMessage

prettyPrintMultipleErrors :: PPEOptions -> MultipleErrors -> Text

prettyPrintMultipleErrorsBox :: Bool -> MultipleErrors -> Box.Box

errorCode :: ErrorMessage -> Text

Error Handling

Core Functional Representation (CoreFn)

Intermediate representation used between AST and code generation, providing a simplified functional language that eliminates syntactic sugar while preserving semantic information.

data CoreFn.Module a = Module
  { moduleSourceSpan :: SourceSpan
  , moduleName :: ModuleName  
  , moduleImports :: [(a, ModuleName)]
  , moduleExports :: [Ident]
  , moduleDecls :: [CoreFn.Bind a]
  }

data CoreFn.Expr a
  = Literal a (Literal (CoreFn.Expr a))
  | Constructor a (ProperName 'TypeName) (ProperName 'ConstructorName) [Ident]
  | Abs a Ident (CoreFn.Expr a)
  | App a (CoreFn.Expr a) (CoreFn.Expr a)
  | Var a (Qualified Ident)
  | Case a [CoreFn.Expr a] [CoreFn.CaseAlternative a]
  -- ... other constructors

Core Functional Representation

Interactive REPL System

Foundation for PSCi (PureScript interactive) providing command processing, module loading, expression evaluation, and state management for interactive development.

handleCommand :: Command -> StateT PSCiState IO ()

data Command
  = Expression P.Expr                                     -- Evaluate expression
  | TypeOf P.Expr                                        -- Show type of expression
  | Import ImportedModule                                -- Import module
  | LoadFile FilePath                                    -- Load PureScript file
  | Reset                                                -- Reset REPL state
  -- ... other commands

data PSCiState  -- REPL state with imports, bindings, loaded modules

Interactive REPL System

Desugaring Pipeline (Sugar)

Comprehensive desugaring system that transforms high-level PureScript syntax into simpler, explicit forms before type checking.

desugar :: [ExternsFile] -> Module -> StateT (Env, UsedImports) (SupplyT (Either MultipleErrors)) Module

-- Individual desugaring passes:
desugarDoModule :: Module -> m Module                     -- Do-notation to bind
desugarAdoModule :: Module -> m Module                    -- Ado-notation to apply  
rebracketOperators :: Module -> m Module                  -- Operator precedence
desugarTypeClasses :: [ExternsFile] -> Module -> m Module -- Type class dictionaries
desugarObjectWildcards :: Module -> m Module             -- Object wildcards

Desugaring Pipeline

Types

Core Name Types

-- Module names
newtype ModuleName = ModuleName [ProperName 'ModuleName]

-- Identifiers for values and functions  
newtype Ident = Ident Text

-- Proper names for types, constructors, modules
newtype ProperName (a :: ProperNameType) = ProperName Text

-- Qualified names with module prefix
data Qualified a = Qualified (Maybe ModuleName) a

-- Source annotations for error reporting
data SourceAnn = SourceAnn
  { spanName :: Maybe FilePath
  , spanStart :: SourcePos  
  , spanEnd :: SourcePos
  }