TableIdentifier.hs

{- |
Copyright : Flipstone Technology Partners 2023
License   : MIT
Stability : Stable

@since 1.0.0.0
-}
module Orville.PostgreSQL.Schema.TableIdentifier
  ( TableIdentifier
  , unqualifiedNameToTableId
  , setTableIdSchema
  , tableIdQualifiedName
  , tableIdUnqualifiedName
  , tableIdSchemaName
  , tableIdToString
  , tableIdUnqualifiedNameString
  , tableIdSchemaNameString
  )
where

import qualified Orville.PostgreSQL.Expr as Expr

{- |
  An identifier used by Orville to identify a particular table in a particular
  schema.

@since 1.0.0.0
-}
data TableIdentifier = TableIdentifier
  { i_tableIdName :: String
  , i_tableIdSchema :: Maybe String
  }
  deriving (Eq, Ord, Show)

{- |
  Constructs a 'TableIdentifier' where the table's name will not be qualified
  by a particular schema.

@since 1.0.0.0
-}
unqualifiedNameToTableId :: String -> TableIdentifier
unqualifiedNameToTableId name =
  TableIdentifier
    { i_tableIdName = name
    , i_tableIdSchema = Nothing
    }

{- |
  Sets the schema of the 'TableIdentifier'. Wherever applicable, references to
  the table will be qualified by the given schema name.

@since 1.0.0.0
-}
setTableIdSchema :: String -> TableIdentifier -> TableIdentifier
setTableIdSchema schema tableId =
  tableId
    { i_tableIdSchema = Just schema
    }

{- |
  Returns the 'Expr.Qualified Expr.TableName' that should be used to refer to
  the table in SQL queries.

@since 1.0.0.0
-}
tableIdQualifiedName :: TableIdentifier -> Expr.Qualified Expr.TableName
tableIdQualifiedName tableId =
  Expr.qualifyTable
    (tableIdSchemaName tableId)
    (tableIdUnqualifiedName tableId)

{- |
  Returns the unqualified 'Expr.TableName' that should be used to refer to the
  table in SQL queries where an unqualified reference is appropriate.

@since 1.0.0.0
-}
tableIdUnqualifiedName :: TableIdentifier -> Expr.TableName
tableIdUnqualifiedName =
  Expr.tableName . i_tableIdName

{- |
  Returns the 'Expr.SchemaName' (if any) that should be used to qualify
  references to the table in SQL queries.

@since 1.0.0.0
-}
tableIdSchemaName :: TableIdentifier -> Maybe Expr.SchemaName
tableIdSchemaName =
  fmap Expr.schemaName . i_tableIdSchema

{- |
  Retrieves the unqualified name of the table as a 'String'.

@since 1.0.0.0
-}
tableIdUnqualifiedNameString :: TableIdentifier -> String
tableIdUnqualifiedNameString =
  i_tableIdName

{- |
  Retrieves the schema name of the table as a 'String'.

@since 1.0.0.0
-}
tableIdSchemaNameString :: TableIdentifier -> Maybe String
tableIdSchemaNameString =
  i_tableIdSchema

{- |
  Converts a 'TableIdentifier' to a 'String' for descriptive purposes. The
  name will be qualified if a schema name has been set for the identifier.

  Note: You should not use this function for building SQL expressions. Use
  'tableIdQualifiedName' instead for that.

@since 1.0.0.0
-}
tableIdToString :: TableIdentifier -> String
tableIdToString tableId =
  case i_tableIdSchema tableId of
    Nothing ->
      i_tableIdName tableId
    Just schema ->
      schema <> "." <> i_tableIdName tableId