function.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef ZORBA_FUNCTION_API_H
17 #define ZORBA_FUNCTION_API_H
18 
19 #include <cstddef>
20 #include <vector>
21 
22 #include <zorba/config.h>
23 #include <zorba/api_shared_types.h>
24 #include <zorba/smart_ptr.h>
25 
26 namespace zorba {
27 
28 class ItemSequence;
29 
30 
31 /**************************************************************************//**
32  The Function class represents a function that is callable from XQuery code,
33  and it gives access to the various properties that are specified in the
34  declaration of the function within a Prolog.
35 
36  Instances of Function are returned by the StaticContext::findFunctions()
37  method. To be mopre precise, StaticContext::findFunctions() returns smart
38  pointers to Function objects. These smart pointers must be destroyed before
39  the StaticContext object they were obtained from is destroyed.
40 
41  Note: Builtin functions are not declared in the Prolog, but the same kind of
42  properties exist for them as well. So, the Function class works for builtin
43  functions as well.
44 *******************************************************************************/
45 class ZORBA_DLL_PUBLIC Function : public SmartObject
46 {
47  public:
48  /** \brief Destructor
49  */
50  virtual ~Function() {}
51 
52  /**
53  * @return True if the function is sequential; false otherwise.
54  */
55  virtual bool
56  isSequential() const = 0;
57 
58  /**
59  * @return True if the function is updating; false otherwise.
60  */
61  virtual bool
62  isUpdating() const = 0;
63 
64  /**
65  * @return True if the function is private; false otherwise.
66  */
67  virtual bool
68  isPrivate() const = 0;
69 
70  /**
71  * @return True if the function is deterministic; false otherwise.
72  */
73  virtual bool
74  isDeterministic() const = 0;
75 
76  /**
77  *
78  */
79  virtual void
80  getAnnotations(std::vector<Annotation_t>& annotations) const = 0;
81 
82  /**
83  * @return The expanded QName of the function
84  */
85  virtual Item
86  getQName() const = 0;
87 
88  /**
89  * @return The namespace URI of the function QName
90  */
91  virtual String
92  getURI() const = 0;
93 
94  /**
95  * @return The local name of the function QName
96  */
97  virtual String
98  getLocalName() const = 0;
99 
100  /**
101  * @return The arity of the function. If the function is variadic (which is
102  * possible only for builtin functions), the result of this method
103  * is non-deterministic.
104  */
105  virtual size_t
106  getArity() const = 0;
107 
108  /**
109  * @return True if the function is variadic; false otherwise
110  */
111  virtual bool
112  isVariadic() const = 0;
113 
114  /**
115  * @return True if the function is an external one; false otherwise
116  */
117  virtual bool
118  isExternal() const = 0;
119 
120  /**
121  * @return True if the function implementation is written in XQuery (or
122  * equivalently, it is a non-external function with a Prolog
123  * declaration); false otherwise
124  */
125  virtual bool
126  isXQuery() const = 0;
127 
128  /**
129  * @return True if the function is a builtin one (not declared in any prolog);
130  * false otherwise
131  */
132  virtual bool
133  isBuiltin() const = 0;
134 };
135 
136 
137 /**************************************************************************//**
138  The ExternalFunction class serves as the base of subclasses that represent
139  the implementation/body of external functions.
140 
141  Instances of ExternalFunction must provide an evaluate method that serves
142  as the implementation of the function. During its evaluation, an external
143  function may or may not need to access the static and/or dynamic context of
144  the invoking XQuery module. If the function implementation does need to
145  access either context, the function is referred to as "contextual"; otherwise,
146  it is "non-contextual".
147 *******************************************************************************/
148 class ZORBA_DLL_PUBLIC ExternalFunction
149 {
150 public:
151  typedef std::vector<ItemSequence*> Arguments_t;
152 
153  public:
154  virtual ~ExternalFunction() {}
155 
156  /**
157  * @return The namespace URI of the function QName
158  */
159  virtual String
160  getURI() const = 0;
161 
162  /**
163  * @return The local name of the function QName
164  */
165  virtual String
166  getLocalName() const = 0;
167 
168  /**
169  * @return True if the external function is contextual; false otherwise.
170  */
171  virtual bool
172  isContextual() const = 0;
173 };
174 
175 
176 /**************************************************************************//**
177  The NonContextualExternalFunction class serves as the base of subclasses that
178  represent the implementation of non contextual external functions.
179 
180  For each external function, an application must provide a concrete subclass
181  of this class and "store" an instance of the subclass inside an ExternalModule
182  object, as described <a href="../../zorba/html/external_functions.html">
183  here</a>.
184 *******************************************************************************/
185 class ZORBA_DLL_PUBLIC NonContextualExternalFunction : public ExternalFunction
186 {
187  public:
189 
190  virtual ItemSequence_t
191  evaluate(const Arguments_t&) const = 0;
192 
193  bool
194  isContextual() const { return false; }
195 };
196 
197 
198 /**************************************************************************//**
199  The ContextualExternalFunction class serves as the base of subclasses that
200  represent the implementation of contextual external functions.
201 
202  For each external function, an application must provide a concrete subclass
203  of this class and "store" an instance of the subclass inside an ExternalModule
204  object, as described <a href="../../zorba/html/external_functions.html">
205  here</a>.
206 *******************************************************************************/
207 class ZORBA_DLL_PUBLIC ContextualExternalFunction : public ExternalFunction
208 {
209  public:
211 
212  virtual ItemSequence_t
213  evaluate(
214  const Arguments_t&,
215  const StaticContext*,
216  const DynamicContext*) const = 0;
217 
218  bool
219  isContextual() const { return true; }
220 };
221 
222 
223 } /* namespace zorba */
224 #endif
225 
226 /*
227  * Local variables:
228  * mode: c++
229  * End:
230  */
231 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus