1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
// Copyright 2014 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.devtools.build.lib.skylarkinterface;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* An annotation to mark built-in keyword argument methods accessible from Skylark.
*
* <p>Use this annotation around a {@link com.google.devtools.build.lib.syntax.BuiltinFunction} or
* a {@link com.google.devtools.build.lib.syntax.BuiltinFunction.Factory}. The annotated function
* should expect the arguments described by {@link #parameters()}, {@link #extraPositionals()},
* and {@link #extraKeywords()}. It should also expect the following extraneous arguments:
*
* <ul>
* <li>
* {@link com.google.devtools.build.lib.events.Location} if {@link #useLocation()} is
* true.
* </li>
* <li>{@link com.google.devtools.build.lib.syntax.ASTNode} if {@link #useAst()} is true.</li>
* <li>
* {@link com.google.devtools.build.lib.syntax.Environment} if {@link #useEnvironment()} )}
* is true.
* </li>
* </ul>
*/
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface SkylarkSignature {
// TODO(bazel-team): parse most everything from single string specifying the signature
// in Skylark syntax, e.g.: signature = "foo(a: string, b: ListOf(int)) -> NoneType"
// String signature() default "";
/**
* Name of the method as exposed to Skylark.
*/
String name();
/**
* General documentation block of the method. See the skylark documentation at
* http://www.bazel.build/docs/skylark/.
*/
String doc() default "";
/**
* List of parameters for calling this method. Named only parameters are expected to be last.
*/
Param[] parameters() default {};
/**
* Defines a catch all positional parameters. By default, it is an error to define more
* positional parameters that specified but by defining an extraPositionals argument, one can
* catch those. See python's <code>*args</code>
* (http://thepythonguru.com/python-args-and-kwargs/).
*/
Param extraPositionals() default @Param(name = "");
/**
* Defines a catch all named parameters. By default, it is an error to define more
* named parameters that specified but by defining an extraKeywords argument, one can catch those.
* See python's <code>**kwargs</code> (http://thepythonguru.com/python-args-and-kwargs/).
*/
Param extraKeywords() default @Param(name = "");
/**
* Set <code>documented</code> to <code>false</code> if this method should not be mentioned
* in the documentation of Skylark. This is generally used for experimental APIs or duplicate
* methods already documented on another call.
*/
boolean documented() default true;
/**
* Type of the object associated to that function. If this field is
* <code>Object.class</code>, then the function will be considered as an object method.
* For example, to add a function to the string object, set it to <code>String.class</code>.
*/
Class<?> objectType() default Object.class;
/**
* Return type of the function. Use {@link com.google.devtools.build.lib.syntax.Runtime.NoneType}
* for a void function.
*/
Class<?> returnType() default Object.class;
// TODO(bazel-team): determine this way whether to accept mutable Lists
// boolean mutableLists() default false;
/**
* If true the location of the call site will be passed as an argument of the annotated function.
*/
boolean useLocation() default false;
/**
* If true the AST of the call site will be passed as an argument of the annotated function.
*/
boolean useAst() default false;
/**
* If true the AST of the Skylark Environment
* ({@link com.google.devtools.build.lib.syntax.Environment}) will be passed as an argument of the
* annotated function.
*/
boolean useEnvironment() default false;
}
|
