001/*
002 *  Copyright 2019 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.plugins.core.ui.script;
017
018import java.util.ArrayList;
019import java.util.Collection;
020import java.util.HashMap;
021import java.util.List;
022import java.util.Map;
023import java.util.stream.Collectors;
024
025import org.ametys.runtime.i18n.I18nizableText;
026
027/**
028 * A class that hold the documentation of one function or one variable
029 */
030public class ScriptBindingDocumentation
031{
032    private I18nizableText _name;
033    private I18nizableText _text;
034    private Signature _signature;
035    private List<Example> _examples;
036
037    /**
038     * Creates a documentation object
039     * @param name The name of the documented stuff
040     * @param text The description
041     * @param signature The signature
042     * @param examples The examples
043     */
044    public ScriptBindingDocumentation(I18nizableText name, I18nizableText text, Signature signature, List<Example> examples)
045    {
046        _name = name;
047        _text = text;
048        _signature = signature;
049        _examples = examples;
050    }
051    
052    /**
053     * The documentation as a map
054     * @return The documentation as a map
055     */
056    public Map<String, Object> asMap()
057    {
058        Map<String, Object> m = new HashMap<>();
059        
060        m.put("name", getName());
061        m.put("description", getText());
062        m.put("signature", getSignature().asMap());
063        m.put("examples", getExamples() != null ? getExamples().stream().map(Example::asMap).collect(Collectors.toList()) : null);
064        
065        return m;
066    }
067    
068    /**
069     * The documentation name
070     * @return The documentation name
071     */
072    public I18nizableText getName()
073    {
074        return _name;
075    }
076    
077    /**
078     * The description
079     * @return The description
080     */
081    public I18nizableText getText()
082    {
083        return _text;
084    }
085    
086    /**
087     * The signature
088     * @return The signature
089     */
090    public Signature getSignature()
091    {
092        return _signature;
093    }
094    
095    /**
096     * The examples
097     * @return The examples
098     */
099    public List<Example> getExamples()
100    {
101        return _examples;
102    }
103    
104    /**
105     * A signature. 
106     */
107    public static class Signature
108    {
109        private String _returnType;
110        private List<Argument> _returnSubtype;
111        private I18nizableText _returnText;
112        private List<Argument> _arguments;
113
114        /**
115         * Builds a signature
116         * @param returnType The type or return type for a function
117         * @param signatureSubtype Description of the type when it is an object. null otherwise
118         * @param returnText The text
119         * @param arguments The arguments for a function
120         */
121        public Signature(String returnType, List<Argument> signatureSubtype, I18nizableText returnText, List<Argument> arguments)
122        {
123            _returnType = returnType;
124            _returnSubtype = signatureSubtype;
125            _returnText = returnText;
126            _arguments = arguments;
127        }
128        
129        /**
130         * The signature as map
131         * @return The signature as map
132         */
133        public Map<String, Object> asMap()
134        {
135            Map<String, Object> m = new HashMap<>();
136            
137            m.put("type", getType());
138            
139            List<Argument> subtype = getSubtype();
140            if (subtype != null)
141            {
142                Collection<Object> subm = new ArrayList<>();
143                for (Argument argument : getSubtype())
144                {
145                    subm.add(argument.asMap());
146                }
147                m.put("subtype", subm);
148            }
149            
150            m.put("text", getText());
151            m.put("arguments", getArguments() != null ? getArguments().stream().map(Argument::asMap).collect(Collectors.toList()) : null);
152            
153            return m;
154        }
155
156        /**
157         * The type (or return type for a function)
158         * @return The type (or return type for a function)
159         */
160        public String getType()
161        {
162            return _returnType;
163        }
164        
165        /**
166         * The description of the type when it is an object.
167         * @return Description or null.
168         */
169        public List<Argument> getSubtype()
170        {
171            return _returnSubtype;
172        }
173        
174        /**
175         * The description
176         * @return The description
177         */
178        public I18nizableText getText()
179        {
180            return _returnText;
181        }
182        
183        /**
184         * The arguments (when a function)
185         * @return The arguments (when a function)
186         */
187        public List<Argument> getArguments()
188        {
189            return _arguments;
190        }
191    }
192    
193    /**
194     * Describes an argument when a function is documented 
195     */
196    public static class Argument
197    {
198        private String _argumentName;
199        private String _argumentType;
200        private List<Argument> _argumentSubtype;
201        private I18nizableText _argumentText;
202        private String _argumentOptionalValue;
203
204        /**
205         * Builds an argument
206         * @param argumentName The name
207         * @param argumentType The type
208         * @param argumentSubtype Description of the type when it is an object. null otherwise 
209         * @param argumentText The description
210         * @param optionalValue Null if the argument is mandatory, the default value otherwise such as "null" or "\"default\""
211         */
212        public Argument(String argumentName, String argumentType, List<Argument> argumentSubtype, I18nizableText argumentText, String optionalValue)
213        {
214            _argumentName = argumentName;
215            _argumentType = argumentType;
216            _argumentSubtype = argumentSubtype;
217            _argumentText = argumentText;
218            _argumentOptionalValue = optionalValue;
219        }
220        
221        /**
222         * The argument as map
223         * @return The argument as map
224         */
225        public Map<String, Object> asMap()
226        {
227            Map<String, Object> m = new HashMap<>();
228            
229            m.put("name", getName());
230            m.put("type", getType());
231
232            List<Argument> subtype = getSubtype();
233            if (subtype != null)
234            {
235                Collection<Object> subm = new ArrayList<>();
236                for (Argument argument : getSubtype())
237                {
238                    subm.add(argument.asMap());
239                }
240                m.put("subtype", subm);
241            }
242            
243            m.put("text", getText());
244            m.put("optional", getOptionalValue());
245            
246            return m;
247        }
248
249        /**
250         * The name of the argument
251         * @return The name of the argument
252         */
253        public String getName()
254        {
255            return _argumentName;
256        }
257        
258        /**
259         * The type/class name of the argument
260         * @return The type/class name of the argument
261         */
262        public String getType()
263        {
264            return _argumentType;
265        }
266        
267        /**
268         * Description of the type when it is an object.
269         * @return Description or null otherwise
270         */
271        public List<Argument> getSubtype()
272        {
273            return _argumentSubtype;
274        }
275        
276        /**
277         * The description of the argument
278         * @return The description of the argument
279         */
280        public I18nizableText getText()
281        {
282            return _argumentText;
283        }
284        
285        /**
286         * The type/class name of the argument
287         * @return The type/class name of the argument
288         */
289        public String getOptionalValue()
290        {
291            return _argumentOptionalValue;
292        }
293    }
294    
295    /**
296     * Example 
297     */
298    public static class Example 
299    {
300        private String _code;
301        private I18nizableText _exampleText;
302
303        /**
304         * Creates an exemple
305         * @param code Code
306         * @param text Associated text
307         */
308        public Example(String code, I18nizableText text)
309        {
310            _code = code;
311            _exampleText = text;
312        }
313        
314        /**
315         * The example as map
316         * @return The example as map
317         */
318        public Map<String, Object> asMap()
319        {
320            Map<String, Object> m = new HashMap<>();
321            
322            m.put("code", getCode());
323            m.put("text", getText());
324            
325            return m;
326        }
327        
328        /**
329         * The code
330         * @return The code
331         */
332        public String getCode()
333        {
334            return _code;
335        }
336        
337        /**
338         * Get the text
339         * @return the text
340         */
341        public I18nizableText getText()
342        {
343            return _exampleText;
344        }
345    }
346}