core

package
v7.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2022 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package core 提供基础的核心功能

Index

Constants

View Source 
const (
	// Name 程序的正式名称
	Name = "apidoc"

	// RepoURL 源码仓库地址
	RepoURL = "https://github.com/caixw/apidoc"

	// OfficialURL 官网
	OfficialURL = "https://apidoc.tools"

	// XMLNamespace 定义 xml 命名空间的 URI
	XMLNamespace = "https://apidoc.tools/v6/XMLSchema"
)
View Source 
const (
	SchemeFile  = "file"
	SchemeHTTP  = "http"
	SchemeHTTPS = "https"
)

目前 URI 支持的协议

Variables

This section is empty.

Functions

func FullVersion 

func FullVersion() string

FullVersion 完整的版本号

会包含版本号、构建日期和最后的提交 ID，大致格式如下： 

version+buildDate.commitHash

func Version 

func Version() string

Version 程序的版本号

遵守 https://semver.org/lang/zh-CN/ 规则。 程序不兼容或是文档格式不兼容时，需要提升主版本号。

Types

type Block 

type Block struct {
	Location Location
	Data     []byte
}

Block 最基本的代码单位

一般从注释提取的一个完整注释作为 Block 实例。

type Error added in v7.2.0 

type Error struct {
	Err      error                // 具体的错误信息
	Location Location             // 错误的详细定位
	Field    string               // 出错的字段
	Types    []ErrorType          // 该错误的类型
	Related  []RelatedInformation // 与此错误关联的一些信息
}

Error 用于描述 apidoc 中的大部分错误信息

无论是配置文件的错误，还是文档的语法错误，都将返回此错误。

func NewError added in v7.2.0 

func NewError(key message.Reference, v ...interface{}) *Error

NewError 返回 *Error 实例

func WithError added in v7.2.0 

func WithError(err error) *Error

WithError 采用 err 实例 *Error 实例

func (*Error) AddTypes added in v7.2.0 

func (err *Error) AddTypes(t ...ErrorType) *Error

AddTypes 为语法错误添加错误类型

func (*Error) Error added in v7.2.0 

func (err *Error) Error() string

func (*Error) Is added in v7.2.0 

func (err *Error) Is(target error) bool

Is 实现 errors.Is 接口

func (*Error) Relate added in v7.2.0 

func (err *Error) Relate(loc Location, msg string) *Error

Relate 添加关联的错误信息

func (*Error) Unwrap added in v7.2.0 

func (err *Error) Unwrap() error

Unwrap 实现 errors.Unwrap 接口

func (*Error) WithField added in v7.2.0 

func (err *Error) WithField(field string) *Error

WithField 为语法错误修改或添加具体的错误字段

func (*Error) WithLocation added in v7.2.0 

func (err *Error) WithLocation(loc Location) *Error

WithLocation 为语法错误添加定位信息

type ErrorType added in v7.2.0 

type ErrorType int

ErrorType 语法错误的类型 

const (
	ErrorTypeDeprecated ErrorType = iota + 1
	ErrorTypeUnused
)

语法错误类型可用的枚举值

type HTTPError 

type HTTPError struct {
	locale.Err
	Code int
}

HTTPError 表示 HTTP 状态码的错误

func NewHTTPError 

func NewHTTPError(code int, key message.Reference, v ...interface{}) *HTTPError

NewHTTPError 声明 HTTPError 实例

type HandlerFunc 

type HandlerFunc func(*Message)

HandlerFunc 错误处理函数

type Location 

type Location struct {
	URI   URI   `json:"uri" apidoc:"-"`
	Range Range `json:"range" apidoc:"-"`
}

Location 用于描述一段内容的定位

兼容 LSP https://microsoft.github.io/language-server-protocol/specifications/specification-current/#location

func (Location) Contains added in v7.2.0 

func (l Location) Contains(uri URI, pos Position) bool

Contains l 是否包含 pos 这个点

func (Location) Equal added in v7.1.0 

func (l Location) Equal(v Location) bool

Equal 判断与 v 是否相等

所有字段都相同即返回 true。

func (Location) IsEmpty added in v7.2.0 

func (l Location) IsEmpty() bool

IsEmpty 表示 Location 未指向任何位置

func (Location) Loc added in v7.2.0 

func (l Location) Loc() Location

Loc 返回当前的范围

func (Location) NewError added in v7.2.0 

func (l Location) NewError(key message.Reference, v ...interface{}) *Error

NewError 在当前位置生成语法错误信息

其中的 msg 和 val 会被转换成本地化的内容保存。

func (Location) String 

func (l Location) String() string

func (Location) WithError added in v7.2.0 

func (l Location) WithError(err error) *Error

WithError 在当前位置生成语法错误信息

若 err 本身就是 *Error 类型，则会更新其 location 和 Field 两个字段的信息。

type Message 

type Message struct {
	Type    MessageType
	Message interface{}
}

Message 输出消息的具体结构

type MessageHandler 

type MessageHandler struct {
	// contains filtered or unexported fields
}

MessageHandler 异步的消息处理机制

包含了本地化的信息，输出时，会以指定的本地化内容输出

func NewMessageHandler 

func NewMessageHandler(f HandlerFunc) *MessageHandler

NewMessageHandler 声明新的 MessageHandler 实例

func (*MessageHandler) Error 

func (h *MessageHandler) Error(err interface{})

Error 发送错误类型的值

func (*MessageHandler) Info 

func (h *MessageHandler) Info(err interface{})

Info 发送错误类型的值

func (*MessageHandler) Locale 

func (h *MessageHandler) Locale(t MessageType, key message.Reference, val ...interface{})

Locale 发送普通的文本信息

func (*MessageHandler) Message 

func (h *MessageHandler) Message(t MessageType, msg interface{})

Message 发送消息

func (*MessageHandler) Stop 

func (h *MessageHandler) Stop()

Stop 停止处理错误内容

只有在消息处理完成之后，才会返回。

func (*MessageHandler) Success 

func (h *MessageHandler) Success(err interface{})

Success 发送错误类型的值

func (*MessageHandler) Warning 

func (h *MessageHandler) Warning(err interface{})

Warning 发送错误类型的值

type MessageType 

type MessageType int8

MessageType 表示消息的类型 

const (
	Erro MessageType = iota
	Warn
	Info
	Succ
)

消息的分类

func (MessageType) String 

func (t MessageType) String() string

type Position 

type Position struct {
	Line      int `json:"line" apidoc:"-"`
	Character int `json:"character" apidoc:"-"`
}

Position 用于描述字符在文件中的定位

兼容 LSP https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position

func (Position) Equal 

func (p Position) Equal(v Position) bool

Equal 判断与 v 是否相同

type Range 

type Range struct {
	Start Position `json:"start" apidoc:"-"`
	End   Position `json:"end" apidoc:"-"`
}

Range 用于描述文档中的一段范围

兼容 LSP https://microsoft.github.io/language-server-protocol/specifications/specification-current/#range

func (Range) Contains 

func (r Range) Contains(p Position) bool

Contains 是否包含了 p 这个点

func (Range) Equal added in v7.1.0 

func (r Range) Equal(v Range) bool

Equal 判断与 v 是否相同

func (Range) IsEmpty 

func (r Range) IsEmpty() bool

IsEmpty 表示 Range 表示的范围长度为空

type RelatedInformation added in v7.2.0 

type RelatedInformation struct {
	Location Location `json:"location"`
	Message  string   `json:"message"`
}

RelatedInformation 错误信息的关联内容

兼容 LSP 中的 DiagnosticRelatedInformation 的相关定义

https://microsoft.github.io/language-server-protocol/specifications/specification-3-16/#diagnostic

type Searcher added in v7.2.0 

type Searcher interface {
	Contains(URI, Position) bool
	Loc() Location
}

Searcher 实现了搜索的基本方法集合

所有内嵌 Location 的对象都可以使用此接口判断是否内嵌 Location。

type URI 

type URI string

URI 定义 URI

http://tools.ietf.org/html/rfc3986 

  foo://example.com:8042/over/there?name=ferret#nose
  \_/   \______________/\_________/ \_________/ \__/
   |           |            |            |        |
scheme     authority       path        query   fragment
   |   _____________________|__
  / \ /                        \
  urn:example:animal:ferret:nose

如果是本地相对路径，也可以直接使用 `./path/file` 的形式表示， 不需要指定协议。

NOTE: 并非完整的 URI 实现，仅作为了 file:// 和 http:// 支持， 也提供对 windows 路径的支持。

func FileURI 

func FileURI(path string) URI

FileURI 根据本地文件路径构建 URI 实例

如果已经存在协议，则不作任何改变返回。

func (URI) Append 

func (uri URI) Append(path string) URI

Append 追加 path 至 URI 生成新的 URI

func (URI) Exists 

func (uri URI) Exists() (bool, error)

Exists 判断 uri 指向的内容是否存在

如果是非本地文件，通过 http 的状态码是否为 400 以内加以判断。

func (URI) File 

func (uri URI) File() (string, error)

File 返回 file:// 协议关联的文件路径

func (URI) Parse 

func (uri URI) Parse() (schema, path string)

Parse 分析 uri，获取其各个部分的内容

func (URI) ReadAll 

func (uri URI) ReadAll(enc encoding.Encoding) ([]byte, error)

ReadAll 以 enc 编码读取 uri 的内容

目前仅支持 file、http 和 https 协议

func (URI) String 

func (uri URI) String() string

func (*URI) UnmarshalJSON added in v7.2.0 

func (uri *URI) UnmarshalJSON(v []byte) error

UnmarshalJSON 实现对非 ascii 字符的解码

func (URI) WriteAll 

func (uri URI) WriteAll(data []byte) error

WriteAll 写入内容至 uri

Source Files

View all Source files

Directories

Path Synopsis
Package messagetest 提供测试生成 message 相关的测试工具
 Package messagetest 提供测试生成 message 相关的测试工具

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.