Document schema AST

Fixes #8.
This commit is contained in:
Eugen Wissner 2020-02-14 06:20:05 +01:00
parent 67bebf853c
commit c0e5e30e76
2 changed files with 123 additions and 1 deletions

View File

@ -230,6 +230,7 @@ data Type
| TypeNonNull NonNullType | TypeNonNull NonNullType
deriving (Eq, Show) deriving (Eq, Show)
-- | Represents type names.
type NamedType = Name type NamedType = Name
-- | Helper type to represent Non-Null types and lists of such types. -- | Helper type to represent Non-Null types and lists of such types.
@ -241,10 +242,30 @@ data NonNullType
-- ** Directives -- ** Directives
-- | Directive. -- | Directive.
--
-- Directives begin with "@", can accept arguments, and can be applied to the
-- most GraphQL elements, providing additional information.
data Directive = Directive Name [Argument] deriving (Eq, Show) data Directive = Directive Name [Argument] deriving (Eq, Show)
-- * Type System -- * Type System
-- | Type system can define a schema, a type or a directive.
--
-- @
-- schema {
-- query: Query
-- }
--
-- directive @example on FIELD_DEFINITION
--
-- type Query {
-- field: String @example
-- }
-- @
--
-- This example defines a custom directive "@example", which is applied to a
-- field definition of the type definition "Query". On the top the schema
-- is defined by taking advantage of the type "Query".
data TypeSystemDefinition data TypeSystemDefinition
= SchemaDefinition [Directive] (NonEmpty OperationTypeDefinition) = SchemaDefinition [Directive] (NonEmpty OperationTypeDefinition)
| TypeDefinition TypeDefinition | TypeDefinition TypeDefinition
@ -254,6 +275,8 @@ data TypeSystemDefinition
-- ** Type System Extensions -- ** Type System Extensions
-- | Extension for a type system definition. Only schema and type definitions
-- can be extended.
data TypeSystemExtension data TypeSystemExtension
= SchemaExtension SchemaExtension = SchemaExtension SchemaExtension
| TypeExtension TypeExtension | TypeExtension TypeExtension
@ -261,10 +284,25 @@ data TypeSystemExtension
-- ** Schema -- ** Schema
-- | Root operation type definition.
--
-- Defining root operation types is not required since they have defaults. So
-- the default query root type is "Query", and the default mutation root type
-- is "Mutation". But these defaults can be changed for a specific schema. In
-- the following code the query root type is changed to "MyQueryRootType", and
-- the mutation root type to "MyMutationRootType":
--
-- @
-- schema {
-- query: MyQueryRootType
-- mutation: MyMutationRootType
-- }
-- @
data OperationTypeDefinition data OperationTypeDefinition
= OperationTypeDefinition OperationType NamedType = OperationTypeDefinition OperationType NamedType
deriving (Eq, Show) deriving (Eq, Show)
-- | Extension of the schema definition by further operations or directives.
data SchemaExtension data SchemaExtension
= SchemaOperationExtension [Directive] (NonEmpty OperationTypeDefinition) = SchemaOperationExtension [Directive] (NonEmpty OperationTypeDefinition)
| SchemaDirectivesExtension (NonEmpty Directive) | SchemaDirectivesExtension (NonEmpty Directive)
@ -272,11 +310,28 @@ data SchemaExtension
-- ** Descriptions -- ** Descriptions
-- | GraphQL has built-in capability to document service APIs. Documentation
-- is a GraphQL string that precedes a particular definition and contains
-- Markdown. Any GraphQL definition can be documented this way.
--
-- @
-- """
-- Supported languages.
-- """
-- enum Language {
-- "English"
-- EN
--
-- "Russian"
-- RU
-- }
-- @
newtype Description = Description (Maybe Text) newtype Description = Description (Maybe Text)
deriving (Eq, Show) deriving (Eq, Show)
-- ** Types -- ** Types
-- | Type definitions describe various user-defined types.
data TypeDefinition data TypeDefinition
= ScalarTypeDefinition Description Name [Directive] = ScalarTypeDefinition Description Name [Directive]
| ObjectTypeDefinition | ObjectTypeDefinition
@ -292,6 +347,7 @@ data TypeDefinition
Description Name [Directive] [InputValueDefinition] Description Name [Directive] [InputValueDefinition]
deriving (Eq, Show) deriving (Eq, Show)
-- | Extensions for custom, already defined types.
data TypeExtension data TypeExtension
= ScalarTypeExtension Name (NonEmpty Directive) = ScalarTypeExtension Name (NonEmpty Directive)
| ObjectTypeFieldsDefinitionExtension | ObjectTypeFieldsDefinitionExtension
@ -316,6 +372,16 @@ data TypeExtension
-- ** Objects -- ** Objects
-- | Defines a list of interfaces implemented by the given object type.
--
-- @
-- type Business implements NamedEntity & ValuedEntity {
-- name: String
-- }
-- @
--
-- Here the object type "Business" implements two interfaces: "NamedEntity" and
-- "ValuedEntity".
newtype ImplementsInterfaces t = ImplementsInterfaces (t NamedType) newtype ImplementsInterfaces t = ImplementsInterfaces (t NamedType)
instance Foldable t => Eq (ImplementsInterfaces t) where instance Foldable t => Eq (ImplementsInterfaces t) where
@ -328,10 +394,33 @@ instance Foldable t => Show (ImplementsInterfaces t) where
$ Text.intercalate " & " $ Text.intercalate " & "
$ toList interfaces $ toList interfaces
-- | Definition of a single field in a type.
--
-- @
-- type Person {
-- name: String
-- picture(width: Int, height: Int): Url
-- }
-- @
--
-- "name" and "picture", including their arguments and types, are field
-- definitions.
data FieldDefinition data FieldDefinition
= FieldDefinition Description Name ArgumentsDefinition Type [Directive] = FieldDefinition Description Name ArgumentsDefinition Type [Directive]
deriving (Eq, Show) deriving (Eq, Show)
-- | A list of values passed to a field.
--
-- @
-- type Person {
-- name: String
-- picture(width: Int, height: Int): Url
-- }
-- @
--
-- "Person" has two fields, "name" and "picture". "name" doesn't have any
-- arguments, so 'ArgumentsDefinition' contains an empty list. "picture"
-- contains definitions for 2 arguments: "width" and "height".
newtype ArgumentsDefinition = ArgumentsDefinition [InputValueDefinition] newtype ArgumentsDefinition = ArgumentsDefinition [InputValueDefinition]
deriving (Eq, Show) deriving (Eq, Show)
@ -342,12 +431,32 @@ instance Semigroup ArgumentsDefinition where
instance Monoid ArgumentsDefinition where instance Monoid ArgumentsDefinition where
mempty = ArgumentsDefinition [] mempty = ArgumentsDefinition []
-- | Defines an input value.
--
-- * Input values can define field arguments, see 'ArgumentsDefinition'.
-- * They can also be used as field definitions in an input type.
--
-- @
-- input Point2D {
-- x: Float
-- y: Float
-- }
-- @
--
-- The input type "Point2D" contains two value definitions: "x" and "y".
data InputValueDefinition data InputValueDefinition
= InputValueDefinition Description Name Type (Maybe Value) [Directive] = InputValueDefinition Description Name Type (Maybe Value) [Directive]
deriving (Eq, Show) deriving (Eq, Show)
-- ** Unions -- ** Unions
-- | List of types forming a union.
--
-- @
-- union SearchResult = Person | Photo
-- @
--
-- "Person" and "Photo" are member types of the union "SearchResult".
newtype UnionMemberTypes t = UnionMemberTypes (t NamedType) newtype UnionMemberTypes t = UnionMemberTypes (t NamedType)
instance Foldable t => Eq (UnionMemberTypes t) where instance Foldable t => Eq (UnionMemberTypes t) where
@ -360,5 +469,18 @@ instance Foldable t => Show (UnionMemberTypes t) where
-- ** Enums -- ** Enums
-- | Single value in an enum definition.
--
-- @
-- enum Direction {
-- NORTH
-- EAST
-- SOUTH
-- WEST
-- }
-- @
--
-- "NORTH, "EAST", "SOUTH", and "WEST" are value definitions of an enum type
-- definition "Direction".
data EnumValueDefinition = EnumValueDefinition Description Name [Directive] data EnumValueDefinition = EnumValueDefinition Description Name [Directive]
deriving (Eq, Show) deriving (Eq, Show)

View File

@ -1,4 +1,4 @@
resolver: lts-14.22 resolver: lts-14.25
packages: packages:
- . - .