github.com/sandwich-go/boost@v1.3.29/misc/annotation/annotation.go (about)

     1  package annotation
     2  
     3  import "errors"
     4  
     5  var ErrNoAnnotation = errors.New("no annotation")
     6  
     7  // Annotation 注释
     8  type Annotation interface {
     9  	// Name 注释名
    10  	// 如，'// annotation@X( a = "A" )' 的注释名为 'X'
    11  	Name() string
    12  
    13  	// Line 注释文本内容
    14  	Line() string
    15  
    16  	// Contains 是否包含指定 key
    17  	// 如，'// annotation@X( a = "A" )' 的包含 'a'
    18  	Contains(key string) bool
    19  
    20  	// String 指定 key 对应的字符串类型 value
    21  	// 如，'// annotation@X( a = "A" )' 中 key 为 'a' 的 value 为 'A'
    22  	String(key string, defaultVal ...string) string
    23  
    24  	// Int8 指定 key 对应的 int8 类型 value
    25  	Int8(key string, defaultVal ...int8) (int8, error)
    26  
    27  	// Int16 指定 key 对应的 int16 类型 value
    28  	Int16(key string, defaultVal ...int16) (int16, error)
    29  
    30  	// Int32 指定 key 对应的 int32 类型 value
    31  	Int32(key string, defaultVal ...int32) (int32, error)
    32  
    33  	// Int64 指定 key 对应的 int64 类型 value
    34  	Int64(key string, defaultVal ...int64) (int64, error)
    35  
    36  	// Uint8 指定 key 对应的 uint8 类型 value
    37  	Uint8(key string, defaultVal ...uint8) (uint8, error)
    38  
    39  	// Uint16 指定 key 对应的 uint16 类型 value
    40  	Uint16(key string, defaultVal ...uint16) (uint16, error)
    41  
    42  	// Uint32 指定 key 对应的 uint32 类型 value
    43  	Uint32(key string, defaultVal ...uint32) (uint32, error)
    44  
    45  	// Uint64 指定 key 对应的 uint64 类型 value
    46  	Uint64(key string, defaultVal ...uint64) (uint64, error)
    47  
    48  	// Int 指定 key 对应的 int 类型 value
    49  	Int(key string, defaultVal ...int) (int, error)
    50  
    51  	// Float32 指定 key 对应的 float32 类型 value
    52  	Float32(key string, defaultVal ...float32) (float32, error)
    53  
    54  	// Float64 指定 key 对应的 float64 类型 value
    55  	Float64(key string, defaultVal ...float64) (float64, error)
    56  
    57  	// Bool 指定 key 对应的 bool 类型 value
    58  	Bool(key string, defaultVal ...bool) (bool, error)
    59  }
    60  
    61  // Descriptor 描述，可以规定萃取的注释名，以及判断萃取的注释是否合法
    62  type Descriptor struct {
    63  	Name      string
    64  	Validator func(Annotation) bool
    65  }
    66  
    67  // Resolver 解析器
    68  type Resolver interface {
    69  	// Resolve 解析一行注释
    70  	// 若未解析成功，则返回 ErrNoAnnotation 错误
    71  	Resolve(line string) (Annotation, error)
    72  
    73  	// ResolveWithName 解析多行注释，但要求 Annotation.Name 是指定的 name 参数
    74  	// 否则返回 ErrNoAnnotation 错误
    75  	ResolveWithName(name string, lines ...string) (Annotation, error)
    76  
    77  	// ResolveMany 解析多行注释
    78  	// 该接口会忽略 ErrNoAnnotation 错误
    79  	ResolveMany(lines ...string) ([]Annotation, error)
    80  
    81  	// ResolveNoDuplicate 解析多行注释，但不允许有重复的 Annotation.Name
    82  	// 否则返回错误
    83  	// 该接口会忽略 ErrNoAnnotation 错误
    84  	ResolveNoDuplicate(lines ...string) ([]Annotation, error)
    85  }
    86  
    87  // Default 默认的解析器，只有包含 'annotation@' 的行，才能萃取到注释
    88  var Default = New()
    89  
    90  // Resolve 使用默认的解析器 Default 解析一行注释
    91  // 若未解析成功，则返回 ErrNoAnnotation 错误
    92  func Resolve(line string) (Annotation, error) { return Default.Resolve(line) }
    93  
    94  // ResolveMany 使用默认的解析器 Default 解析多行注释
    95  // 该接口会忽略 ErrNoAnnotation 错误
    96  func ResolveMany(lines ...string) ([]Annotation, error) { return Default.ResolveMany(lines...) }
    97  
    98  // ResolveWithName 使用默认的解析器 Default 解析多行注释，但要求 Annotation.Name 是指定的 name 参数
    99  // 否则返回 ErrNoAnnotation 错误
   100  func ResolveWithName(name string, lines ...string) (Annotation, error) {
   101  	return Default.ResolveWithName(name, lines...)
   102  }
   103  
   104  // ResolveNoDuplicate 使用默认的解析器 Default 解析多行注释，但不允许有重复的 Annotation.Name
   105  // 否则返回错误
   106  // 该接口会忽略 ErrNoAnnotation 错误
   107  func ResolveNoDuplicate(lines ...string) ([]Annotation, error) {
   108  	return Default.ResolveNoDuplicate(lines...)
   109  }