gitee.com/sy_183/go-common@v1.0.5-0.20231205030221-958cfe129b47/parser/parser.go

package parser

// Parser 解析器用于将输入的数据解析成输出的数据
//
// 输入的数据类型为[I any]，输出的数据类型为[O any]，解析器的输入对象和输出对象应当不总是一一对
// 应的
type Parser[I, O any] interface {
	// Input 向解析器中输入数据
	//
	// 调用者应当在首次解析或 Parse 方法返回 ErrNotEnough 时调用此方法向解析器中输入数据，调
	// 用者不应当在 Parse 方法没有返回 ErrNotEnough 时调用此方法，此接口的实现可以选择并推荐
	// 当调用者在 Parse 方法没有返回 ErrNotEnough 并调用此此方法时，使用 panic抛出
	// ErrNotNeedInput 错误。
	//
	// 此方法需要解析器将输入的数据保存到自身示例，以便 Parse 方法解析此数据。
	Input(input I)

	// Parser 解析解析器中的数据
	//
	// 解析的数据是由 Input 方法输入的数据，数据类型为[T any]。此方法返回两个参数为 ok 和 err，
	// 当 ok 为真时，代表解析器已经将输入解析成了一个[O any]类型的数据，可以使用 Get 方法或
	// Take 方法获取到解析完成的数据。当 err 不为 nil 时，说明解析出现了错误，或解析的数据不
	// 足够解析成输出类型的元素(当返回 ErrNotEnough 时)。
	//
	// 如果 Parse 方法返回错误时，并不代表 ok 不为真，因为有可能已经解析完一个输出对象，此时依
	// 然可以通过 Get 或 Take 方法拿到这个数据，通常也会在返回 ErrNotEnough 时返回的 ok 为
	// 真。
	Parse() (ok bool, err error)

	// Get 方法获取解析完成的数据
	//
	// 调用此方法时，如果解析器没有解析出任何输出对象，那么此接口的实现可以返回一个零值或其他有代
	// 表意义的值。
	//
	// 此方法可以在调用一次后再调用应当还可以获取到上次解析完成的数据，因此此方法一般是不会改变解
	// 析器的状态的。
	Get() O

	// Take 方法获取并清空解析完成的数据
	//
	// 与 Get 方法类似，都可以获取解析完成的数据，但是 Take 方法会在返回后清空解析完的数据，再
	// 次获取时应当获取不到任何数据，因此此方法一般是会改变解析器的状态的。
	//
	// Take 方法和 Get 方法在输出类型包含引用计数时通常会变得非常有用，实现者可以在调用 Get 方
	// 法时将输出对象的引用增加，但是调用 Take 方法时则不需要，因为解析器将不再持有此输出对象。
	Take() O

	// Complete 完成解析器最后的解析
	//
	// 此方法将解析器中缓存的数据尽可能解析成最后的输出对象，此处需要注意的是，缓存的数据不应指的
	// 是 Input 方法输入的数据，因此应当在 Parse 方法返回 ErrNotEnough 并且再没有输入的数据
	// 后调用此方法。
	//
	// 此方法的返回值与 Parse 方法的意义一样。
	Complete() (ok bool, err error)

	// Reset 重置解析器
	//
	// 重置解析器会重置解析器的所有状态，并清除解析完成的数据，使得解析器和刚刚初始化的状态一置，
	// 通常用于解析器的复用。
	//
	// 此方法应当等同于正确的执行了 Complete 方法再执行 Take 方法后的效果。
	Reset()
}