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 protected:
175  Item
176  getItem( Arguments_t const &args, unsigned pos ) const;
177 };
178 
179 
180 /**************************************************************************//**
181  The NonContextualExternalFunction class serves as the base of subclasses that
182  represent the implementation of non contextual external functions.
183 
184  For each external function, an application must provide a concrete subclass
185  of this class and "store" an instance of the subclass inside an ExternalModule
186  object, as described <a href="../../zorba/html/external_functions.html">
187  here</a>.
188 *******************************************************************************/
189 class ZORBA_DLL_PUBLIC NonContextualExternalFunction : public ExternalFunction
190 {
191  public:
193 
194  virtual ItemSequence_t
195  evaluate(const Arguments_t&) const = 0;
196 
197  bool
198  isContextual() const { return false; }
199 };
200 
201 
202 /**************************************************************************//**
203  The ContextualExternalFunction class serves as the base of subclasses that
204  represent the implementation of contextual external functions.
205 
206  For each external function, an application must provide a concrete subclass
207  of this class and "store" an instance of the subclass inside an ExternalModule
208  object, as described <a href="../../zorba/html/external_functions.html">
209  here</a>.
210 *******************************************************************************/
211 class ZORBA_DLL_PUBLIC ContextualExternalFunction : public ExternalFunction
212 {
213  public:
215 
216  virtual ItemSequence_t
217  evaluate(
218  const Arguments_t&,
219  const StaticContext*,
220  const DynamicContext*) const = 0;
221 
222  bool
223  isContextual() const { return true; }
224 };
225 
226 
227 } /* namespace zorba */
228 #endif
229 
230 /*
231  * Local variables:
232  * mode: c++
233  * End:
234  */
235 /* vim:set et sw=2 ts=2: */