GraphQL.JS 文档
graphql/语言

graphql/language

graphql/language 模块负责对 GraphQL 语言进行解析和操作。你可以从 graphql/language 模块或根 graphql 模块导入。例如:

¥The graphql/language module is responsible for parsing and operating on the GraphQL language. You can import either from the graphql/language module, or from the root graphql module. For example:

import { Source } from "graphql" // ES6
var { Source } = require("graphql") // CommonJS

概述

¥Overview

来源

¥Source

词法分析器

¥Lexer

解析器

¥Parser

访客

¥Visitor

打印机

¥Printer

来源

¥Source

来源

¥Source

export class Source {
  constructor(body: string, name?: string)
}

GraphQL 的源输入的表示。该名称是可选的,但对于在源文件中存储 GraphQL 文档的客户来说最有用;例如,如果 GraphQL 输入位于文件 Foo.graphql 中,则名称为 “Foo.graphql” 可能会很有用。

¥A representation of source input to GraphQL. The name is optional, but is mostly useful for clients who store GraphQL documents in source files; for example, if the GraphQL input is in a file Foo.graphql, it might be useful for name to be “Foo.graphql”.

getLocation

function getLocation(source: Source, position: number): SourceLocation
 
type SourceLocation = {
  line: number;
  column: number;
}

获取 Source 和 UTF-8 字符偏移量,并返回相应的行和列作为 SourceLocation。

¥Takes a Source and a UTF-8 character offset, and returns the corresponding line and column as a SourceLocation.

词法分析器

¥Lexer

lex

function lex(source: Source): Lexer;
 
type Lexer = (resetPosition?: number) => Token;
 
export type Token = {
  kind: number;
  start: number;
  end: number;
  value: string;
};

给定一个 Source 对象,这将返回该源的词法分析器。Lexer 是一个类似于生成器的函数,每次调用它时,它都会返回 Source 中的下一个标记。假设源词法分析器,词法分析器发出的最终令牌将是 EOF 类型,之后每当调用时,词法分析器都会重复返回 EOF 标记。

¥Given a Source object, this returns a Lexer for that source. A Lexer is a function that acts like a generator in that every time it is called, it returns the next token in the Source. Assuming the source lexes, the final Token emitted by the lexer will be of kind EOF, after which the lexer will repeatedly return EOF tokens whenever called.

词法分析器函数的参数是可选的,可用于将词法分析器快退或快进到源中的新位置。

¥The argument to the lexer function is optional, and can be used to rewind or fast forward the lexer to a new position in the source.

解析器

¥Parser

parse

export function parse(
  source: Source | string,
  options?: ParseOptions
): Document

给定 GraphQL 源,将其解析为文档。

¥Given a GraphQL source, parses it into a Document.

如果遇到语法错误,则抛出 GraphQLError。

¥Throws GraphQLError if a syntax error is encountered.

parseValue

export function parseValue(
  source: Source | string,
  options?: ParseOptions
): Value

给定一个包含 GraphQL 值的字符串,解析该值的 AST。

¥Given a string containing a GraphQL value, parse the AST for that value.

如果遇到语法错误,则抛出 GraphQLError。

¥Throws GraphQLError if a syntax error is encountered.

这在直接操作 GraphQL 值并独立于完整 GraphQL 文档的工具中非常有用。

¥This is useful within tools that operate upon GraphQL Values directly and in isolation of complete GraphQL documents.

Kind

描述不同类型 AST 节点的枚举。

¥An enum that describes the different kinds of AST nodes.

访客

¥Visitor

visit

function visit(root, visitor, keyMap)

Visit() 将使用深度优先遍历来遍历 AST,在遍历中的每个节点调用访问者的 Enter 函数,并在访问该节点及其所有子节点后调用 Leave 函数。

¥visit() will walk through an AST using a depth first traversal, calling the visitor’s enter function at each node in the traversal, and calling the leave function after visiting that node and all of its child nodes.

通过从进入和离开函数返回不同的值,可以改变访问者的行为,包括跳过 AST 的子树(通过返回 false)、通过返回值或 null 来删除值来编辑 AST, 或者通过返回 BREAK 来停止整个遍历。

¥By returning different values from the enter and leave functions, the behavior of the visitor can be altered, including skipping over a sub-tree of the AST (by returning false), editing the AST by returning a value or null to remove the value, or to stop the whole traversal by returning BREAK.

当使用 visit()编辑 AST 时,原始 AST 不会被修改,并且应用了更改的 AST 的新版本将从 visit 函数返回。

¥When using visit() to edit an AST, the original AST will not be modified, and a new version of the AST with the changes applied will be returned from the visit function.

var editedAST = visit(ast, {
  enter(node, key, parent, path, ancestors) {
    // @return
    //   undefined: no action
    //   false: skip visiting this node
    //   visitor.BREAK: stop visiting altogether
    //   null: delete this node
    //   any value: replace this node with the returned value
  },
  leave(node, key, parent, path, ancestors) {
    // @return
    //   undefined: no action
    //   false: no action
    //   visitor.BREAK: stop visiting altogether
    //   null: delete this node
    //   any value: replace this node with the returned value
  },
})

除了提供 Enter() 和 Leave() 函数之外,访问者还可以提供与 AST 节点类型相同的命名函数,或者通过指定键进入/离开访问者,从而导致访问者 API 的四种排列:

¥Alternatively to providing enter() and leave() functions, a visitor can instead provide functions named the same as the kinds of AST nodes, or enter/leave visitors at a named key, leading to four permutations of visitor API:

  1. 指定访问者在进入特定类型的节点时触发。

    ¥Named visitors triggered when entering a node a specific kind.

visit(ast, {
  Kind(node) {
    // enter the "Kind" node
  },
})
  1. 在进入和离开特定类型的节点时触发的命名访问者。

    ¥Named visitors that trigger upon entering and leaving a node of a specific kind.

visit(ast, {
  Kind: {
    enter(node) {
      // enter the "Kind" node
    },
    leave(node) {
      // leave the "Kind" node
    }
  }
})
  1. 进入和离开任何节点时触发的通用访问者。

    ¥Generic visitors that trigger upon entering and leaving any node.

visit(ast, {
  enter(node) {
    // enter any node
  },
  leave(node) {
    // leave any node
  },
})
  1. 用于进入和离开特定类型节点的并行访问者。

    ¥Parallel visitors for entering and leaving nodes of a specific kind.

visit(ast, {
  enter: {
    Kind(node) {
      // enter the "Kind" node
    },
  },
  leave: {
    Kind(node) {
      // leave the "Kind" node
    },
  },
})

BREAK

哨兵 BREAK 值在 visitor 的文档中描述。

¥The sentinel BREAK value described in the documentation of visitor.

打印机

¥Printer

print

function print(ast): string

使用一组合理的格式化规则将 AST 转换为字符串。

¥Converts an AST into a string, using one set of reasonable formatting rules.