AST and Language Constructs

-- | A PureScript module
data Module = Module
  SourceSpan              -- Source location
  [Comment]               -- Leading comments
  ModuleName             -- Module name
  [Declaration]          -- Module body
  (Maybe [DeclarationRef]) -- Export list (Nothing means export all)

-- | Module import declaration
data ImportDeclaration = ImportDeclaration
  { importAnn :: SourceAnn
  , importModule :: ModuleName
  , importType :: ImportDeclarationType
  , importAs :: Maybe ModuleName
  , importHiding :: Bool
  }

-- | Import declaration type
data ImportDeclarationType
  = Implicit                                    -- import Module
  | Explicit [DeclarationRef]                  -- import Module (foo, bar)
  | Hiding [DeclarationRef]                    -- import Module hiding (foo, bar)

-- | Top-level declarations
data Declaration
  = DataDeclaration SourceAnn DataDeclType ProperName [TypeVarBinding] [DataConstructorDeclaration]
  | TypeSynonymDeclaration SourceAnn ProperName [TypeVarBinding] SourceType
  | ValueDeclaration ValueDeclarationData
  | ExternDeclaration SourceAnn Ident SourceType
  | FixityDeclaration SourceAnn (Either ValueFixity TypeFixity)
  | TypeClassDeclaration SourceAnn ProperName [TypeVarBinding] [SourceConstraint] [FunctionalDependency] [Declaration]
  | TypeInstanceDeclaration SourceAnn ChainId Integer Ident [SourceConstraint] Qualified (Either Text ProperName) [SourceType] TypeInstanceBody
  | RoleDeclaration SourceAnn ProperName [Role]
  | KindDeclaration SourceAnn KindSignatureFor ProperName SourceType

-- | Data declaration type
data DataDeclType
  = Data         -- data
  | Newtype      -- newtype

-- | Data constructor declaration
data DataConstructorDeclaration = DataConstructorDeclaration
  { dataCtorAnn :: SourceAnn
  , dataCtorName :: ProperName 'ConstructorName
  , dataCtorFields :: [(Ident, SourceType)]
  }

-- | Value declaration data
data ValueDeclarationData = ValueDeclarationData
  { valdeclSourceAnn :: SourceAnn
  , valdeclIdent :: Ident
  , valdeclName :: NameKind
  , valdeclBinders :: [Binder]
  , valdeclExpression :: Maybe (Guard, Expr)
  }

-- | PureScript expressions
data Expr
  = Literal SourceAnn (Literal Expr)
  | Constructor SourceAnn (Qualified (ProperName 'ConstructorName))
  | Accessor SourceAnn PSString Expr
  | ObjectUpdate SourceAnn Expr [(PSString, Expr)]
  | Abs SourceAnn Ident Expr
  | App SourceAnn Expr Expr
  | Var SourceAnn (Qualified Ident)
  | IfThenElse SourceAnn Expr Expr Expr
  | Case SourceAnn [Expr] [CaseAlternative]
  | TypedValue SourceAnn Bool Expr SourceType
  | Let SourceAnn WhereProvenance [Declaration] Expr
  | Do SourceAnn (Maybe ModuleName) [DoNotationElement]
  | Ado SourceAnn (Maybe ModuleName) [DoNotationElement] Expr
  | TypeClassDictionary SourceAnn SourceConstraint Context [PSString]
  | DeferredDictionary SourceAnn (Qualified (ProperName 'ClassName)) [SourceType]
  | DerivedInstancePlaceholder SourceAnn (Qualified (ProperName 'ClassName)) [SourceType]
  | AnonymousArgument SourceAnn
  | Hole SourceAnn Text

-- | Case alternative
data CaseAlternative = CaseAlternative
  { caseAlternativeBinders :: [Binder]
  , caseAlternativeResult :: Either [(Guard, Expr)] Expr
  }

-- | Guard expressions
data Guard
  = ConditionGuard Expr
  | PatternGuard Binder Expr

-- | Pattern binders
data Binder
  = NullBinder SourceAnn
  | LiteralBinder SourceAnn (Literal Binder)
  | VarBinder SourceAnn Ident
  | ConstructorBinder SourceAnn (Qualified (ProperName 'ConstructorName)) [Binder]
  | RecordBinder SourceAnn [(PSString, Binder)]
  | NamedBinder SourceAnn Ident Binder
  | PositionedBinder SourceAnn SourceSpan Binder
  | TypedBinder SourceAnn SourceType Binder
  | OpBinder SourceAnn (Qualified (OpName 'ValueOpName))
  | BinaryNoParensBinder Binder Binder Binder
  | ParensInBinder SourceAnn Binder

-- | Extract bound names from a binder
binderNames :: Binder -> [Ident]

-- | Check if a binder is irrefutable
isIrrefutable :: Binder -> Bool

-- | Literal values
data Literal a
  = NumericLiteral (Either Integer Double)
  | StringLiteral PSString
  | CharLiteral Char
  | BooleanLiteral Bool
  | ArrayLiteral [a]
  | ObjectLiteral [(PSString, a)]

-- | Extract literal type
literalType :: Literal a -> Type ()

-- | Map over literal contents
overLiteral :: (a -> b) -> Literal a -> Literal b

-- | Operator fixity
data Fixity = Fixity Associativity Int

-- | Operator associativity
data Associativity = Infixl | Infixr | Infix

-- | Value-level operator fixity
data ValueFixity = ValueFixity (OpName 'ValueOpName) (Qualified (Either Ident (ProperName 'ConstructorName))) Fixity

-- | Type-level operator fixity
data TypeFixity = TypeFixity (OpName 'TypeOpName) (Qualified (ProperName 'TypeName)) Fixity

-- | Operator names
data OpName (a :: OpNameType) = OpName Text

-- | Qualified operator names
type QualifiedBy a = Qualified (OpName a)

-- | Source position
data SourcePos = SourcePos
  { sourcePosLine :: Int
  , sourcePosColumn :: Int
  }

-- | Source span
data SourceSpan = SourceSpan FilePath SourcePos SourcePos

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

-- | Create null source position
nullSourcePos :: SourcePos

-- | Create null source span  
nullSourceSpan :: SourceSpan

-- | Create null source annotation
nullSourceAnn :: SourceAnn

-- | Everything lens for expressions
everywhereOnValues :: (Declaration -> Declaration) -> (Expr -> Expr) -> (Binder -> Binder) -> (Declaration -> Declaration, Expr -> Expr, Binder -> Binder)

-- | Everything lens with monadic context
everywhereOnValuesM :: Monad m => (Declaration -> m Declaration) -> (Expr -> m Expr) -> (Binder -> m Binder) -> (Declaration -> m Declaration, Expr -> m Expr, Binder -> m Binder)

-- | Everything lens for types
everywhereOnTypes :: (SourceType -> SourceType) -> (SourceType -> SourceType)

-- | Everything lens for types with monadic context
everywhereOnTypesM :: Monad m => (SourceType -> m SourceType) -> (SourceType -> m SourceType)

-- | Top-down traversal
everywhereOnValuesTopDown :: (Declaration -> Declaration) -> (Expr -> Expr) -> (Binder -> Binder) -> (Declaration -> Declaration, Expr -> Expr, Binder -> Binder)

-- | Extract bound names from declarations
getDeclarationBinds :: Declaration -> [Ident]

-- | Check if declaration is exported
isExported :: DeclarationRef -> Declaration -> Bool

-- | Get declaration name
getDeclarationName :: Declaration -> Maybe (ProperName 'TypeName)

-- | Get value declaration identifier
getValueDeclarationName :: Declaration -> Maybe Ident

-- | Modify declaration annotations
modifyAnn :: (SourceAnn -> SourceAnn) -> Declaration -> Declaration

-- | Strip annotations from expressions
stripPositionInfo :: Expr -> Expr

-- | Add source positions
addPositionInfo :: SourceSpan -> Expr -> Expr

-- | Module name
newtype ModuleName = ModuleName [ProperName 'ModuleName]

-- | Declaration references for imports/exports
data DeclarationRef
  = TypeRef SourceAnn (ProperName 'TypeName) (Maybe [ProperName 'ConstructorName])
  | TypeOpRef SourceAnn (OpName 'TypeOpName)
  | ValueRef SourceAnn Ident
  | ValueOpRef SourceAnn (OpName 'ValueOpName)
  | TypeClassRef SourceAnn (ProperName 'ClassName)
  | TypeInstanceRef SourceAnn Ident (Qualified (ProperName 'ClassName))
  | ModuleRef SourceAnn ModuleName
  | ReExportRef SourceAnn ModuleName DeclarationRef

-- | Comments
data Comment = LineComment Text | BlockComment Text

-- | Where provenance for let bindings
data WhereProvenance = FromWhere | FromLet

-- | Do notation elements
data DoNotationElement
  = DoNotationValue Expr
  | DoNotationBind Binder Expr
  | DoNotationLet [Declaration]
  | PositionedDoNotationElement SourcePos DoNotationElement