Describe query AST format in validate.lua

Author: Totktonada

graphql/core/parse.lua

@@ -100,6 +100,10 @@ local function cField(...)
   local field = { kind = 'field' }
 
   for i = 1, #tokens do
+    -- key ~= nil => result['selectionSet'] = <...>
+    --            or result['alias'] = <...>
+    -- key == nil => result['arguments'] = <...>
+    --            or result['directives'] = <...>
     local key = tokens[i].kind
     if not key then
       if tokens[i][1].kind == 'argument' then
@@ -145,6 +149,9 @@ local function cOperation(...)
     }
 
     for i = 2, #args do
+      -- key ~= nil => result['selectionSet'] = <...>
+      -- key == nil => result['variableDefinitions'] = <...>
+      --            or result['directives'] = <...>
       local key = args[i].kind
       if not key then
         if args[i][1].kind == 'variableDefinition' then
@@ -316,3 +323,5 @@ return function(str)
   line, lastLinePos = 1, 1
   return graphQL:match(str) or error('Syntax error near line ' .. line, 2)
 end
+
+-- vim: set ts=2 sw=2 et:

graphql/core/validate.lua

@@ -19,6 +19,17 @@ local function getParentField(context, name, count)
 end
 
 local visitors = {
+  -- <document>
+  --
+  -- {
+  --   kind = 'document',
+  --   definitions = list of <definition>,
+  -- }
+  --
+  -- <definition> is one of the following:
+  --
+  -- * <operation>
+  -- * <fragmentDefinition>
   document = {
     enter = function(node, context)
       for _, definition in ipairs(node.definitions) do
@@ -35,6 +46,47 @@ local visitors = {
     rules = { rules.uniqueFragmentNames, exit = { rules.noUnusedFragments } }
   },
 
+  -- <operation>
+  --
+  -- {
+  --   kind = 'operation',
+  --   operation = 'query' or 'mutation',
+  --   selectionSet = <selectionSet>,
+  --   variableDefinitions = list of <variableDefinition> (optional),
+  --   directives = list of <directive> (optional),
+  -- }
+  --
+  -- <variableDefinition>
+  --
+  -- {
+  --   kind = 'variableDefinition',
+  --   variable = <variable>,
+  --   type = <type>,
+  --   defaultValue = <value> (optional)
+  -- }
+  --
+  -- <type> is one of the following:
+  --
+  -- * <namedType>
+  -- * <listType>
+  -- * <nonNullType>
+  --
+  -- <namedType>
+  --
+  -- {
+  --   kind = 'namedType',
+  --   name = {
+  --     kind = 'name',
+  --     value = <string>,
+  --   },
+  -- }
+  --
+  -- <listType>, <nonNullType>
+  --
+  -- {
+  --   kind = one of ('listType', 'nonNullType'),
+  --   type = <type>,
+  -- }
   operation = {
     enter = function(node, context)
       table.insert(context.objects, context.schema[node.operation])
@@ -65,6 +117,18 @@ local visitors = {
     }
   },
 
+  -- <selectionSet>
+  --
+  -- {
+  --   kind = 'selectionSet',
+  --   selections = list of <selection>,
+  -- }
+  --
+  -- <selection> is one of the following:
+  --
+  -- * <field>
+  -- * <fragmentSpread>
+  -- * <inlineFragment>
   selectionSet = {
     children = function(node)
       return node.selections
@@ -73,6 +137,22 @@ local visitors = {
     rules = { rules.unambiguousSelections }
   },
 
+  -- <field>
+  --
+  -- {
+  --   kind = 'field',
+  --   selectionSet = <selectionSet> (optional),
+  --   alias = <alias> (optional),
+  --   arguments = list of <argument> (optional),
+  --   directives = list of <directive> (optional),
+  -- }
+  --
+  -- <alias>
+  --
+  -- {
+  --   kind = 'alias',
+  --   name = <string>,
+  -- }
   field = {
     enter = function(node, context)
       local name = node.name.value
@@ -125,6 +205,14 @@ local visitors = {
     }
   },
 
+  -- <inlineFragment>
+  --
+  -- {
+  --   kind = 'inlineFragment',
+  --   selectionSet = <selectionSet>,
+  --   typeCondition = <namedType> (optional),
+  --   directives = list of <directive> (optional),
+  -- }
   inlineFragment = {
     enter = function(node, context)
       local kind = false
@@ -153,6 +241,16 @@ local visitors = {
     }
   },
 
+  -- <fragmentSpread>
+  --
+  -- {
+  --   kind = 'fragmentSpread',
+  --   name = {
+  --     kind = 'name',
+  --     value = <string>,
+  --   },
+  --   directives = list of <directive> (optional),
+  -- }
   fragmentSpread = {
     enter = function(node, context)
       context.usedFragments[node.name.value] = true
@@ -218,6 +316,17 @@ local visitors = {
     }
   },
 
+  -- <fragmentDefinition>
+  --
+  -- {
+  --   kind = 'fragmentDefinition',
+  --   name = {
+  --     kind = 'name',
+  --     value = <string>,
+  --   },
+  --   typeCondition = <namedType>,
+  --   selectionSet = <selectionSet>,
+  -- }
   fragmentDefinition = {
     enter = function(node, context)
       local kind = context.schema:getType(node.typeCondition.name.value) or false
@@ -245,6 +354,41 @@ local visitors = {
     }
   },
 
+  -- <argument>
+  --
+  -- {
+  --   kind = 'argument',
+  --   name = {
+  --     kind = 'name',
+  --     value = <string>,
+  --   },
+  --   value = <value>,
+  -- }
+  --
+  -- <value> is one of the following:
+  --
+  -- * <variable>
+  -- * <inputObject>
+  -- * <list>
+  -- * <enum>
+  -- * <string>
+  -- * <boolean>
+  -- * <float>
+  -- * <int>
+  --
+  -- <list>
+  --
+  -- {
+  --   kind = 'list',
+  --   values = list of <value>,
+  -- }
+  --
+  -- <enum>, <string>, <boolean>, <float>, <int>
+  --
+  -- {
+  --   kind = one of ('enum', 'string', 'boolean', 'float', 'int'),
+  --   value = <string>,
+  -- }
   argument = {
     enter = function(node, context)
       if context.currentOperation then
@@ -268,6 +412,15 @@ local visitors = {
     rules = { rules.uniqueInputObjectFields }
   },
 
+  -- <inputObject>
+  --
+  -- {
+  --   kind = 'inputObject',
+  --   values = list of {
+  --     name = <string>,
+  --     value = <value>,
+  --   }
+  -- }
   inputObject = {
     children = function(node)
       return util.map(node.values or {}, function(value)
@@ -278,12 +431,31 @@ local visitors = {
     rules = { rules.uniqueInputObjectFields }
   },
 
+  -- <variable>
+  --
+  -- {
+  --   kind = 'variable',
+  --   name = {
+  --     kind = 'name',
+  --     value = <string>,
+  --   }
+  -- }
   variable = {
     enter = function(node, context)
       context.variableReferences[node.name.value] = true
     end
   },
 
+  -- <directive>
+  --
+  -- {
+  --   kind = 'directive',
+  --   name = {
+  --     kind = 'name',
+  --     value = <string>,
+  --   },
+  --   arguments = list of <argument> (optional),
+  -- }
   directive = {
     children = function(node, context)
       return node.arguments
@@ -340,3 +512,5 @@ return function(schema, tree)
 
   return visit(tree)
 end
+
+-- vim: set ts=2 sw=2 et: