001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.mappaint.mapcss;
003
004import java.awt.Color;
005import java.lang.annotation.ElementType;
006import java.lang.annotation.Retention;
007import java.lang.annotation.RetentionPolicy;
008import java.lang.annotation.Target;
009import java.lang.reflect.Array;
010import java.lang.reflect.InvocationTargetException;
011import java.lang.reflect.Method;
012import java.nio.charset.StandardCharsets;
013import java.util.ArrayList;
014import java.util.Arrays;
015import java.util.Collection;
016import java.util.Collections;
017import java.util.List;
018import java.util.Locale;
019import java.util.Objects;
020import java.util.TreeSet;
021import java.util.function.Function;
022import java.util.regex.Matcher;
023import java.util.regex.Pattern;
024import java.util.zip.CRC32;
025
026import org.openstreetmap.josm.data.coor.LatLon;
027import org.openstreetmap.josm.data.osm.IPrimitive;
028import org.openstreetmap.josm.data.osm.Node;
029import org.openstreetmap.josm.data.osm.Way;
030import org.openstreetmap.josm.data.osm.search.SearchCompiler;
031import org.openstreetmap.josm.data.osm.search.SearchCompiler.Match;
032import org.openstreetmap.josm.data.osm.search.SearchParseError;
033import org.openstreetmap.josm.gui.mappaint.Cascade;
034import org.openstreetmap.josm.gui.mappaint.Environment;
035import org.openstreetmap.josm.gui.mappaint.MapPaintStyles;
036import org.openstreetmap.josm.io.XmlWriter;
037import org.openstreetmap.josm.tools.AlphanumComparator;
038import org.openstreetmap.josm.tools.ColorHelper;
039import org.openstreetmap.josm.tools.Geometry;
040import org.openstreetmap.josm.tools.JosmRuntimeException;
041import org.openstreetmap.josm.tools.Logging;
042import org.openstreetmap.josm.tools.RightAndLefthandTraffic;
043import org.openstreetmap.josm.tools.RotationAngle;
044import org.openstreetmap.josm.tools.SubclassFilteredCollection;
045import org.openstreetmap.josm.tools.Territories;
046import org.openstreetmap.josm.tools.Utils;
047
048/**
049 * Factory to generate {@link Expression}s.
050 * <p>
051 * See {@link #createFunctionExpression}.
052 */
053public final class ExpressionFactory {
054
055    /**
056     * Marks functions which should be executed also when one or more arguments are null.
057     */
058    @Target(ElementType.METHOD)
059    @Retention(RetentionPolicy.RUNTIME)
060    @interface NullableArguments {}
061
062    private static final List<Method> arrayFunctions = new ArrayList<>();
063    private static final List<Method> parameterFunctions = new ArrayList<>();
064    private static final List<Method> parameterFunctionsEnv = new ArrayList<>();
065
066    static {
067        for (Method m : Functions.class.getDeclaredMethods()) {
068            Class<?>[] paramTypes = m.getParameterTypes();
069            if (paramTypes.length == 1 && paramTypes[0].isArray()) {
070                arrayFunctions.add(m);
071            } else if (paramTypes.length >= 1 && paramTypes[0].equals(Environment.class)) {
072                parameterFunctionsEnv.add(m);
073            } else {
074                parameterFunctions.add(m);
075            }
076        }
077        try {
078            parameterFunctions.add(Math.class.getMethod("abs", float.class));
079            parameterFunctions.add(Math.class.getMethod("acos", double.class));
080            parameterFunctions.add(Math.class.getMethod("asin", double.class));
081            parameterFunctions.add(Math.class.getMethod("atan", double.class));
082            parameterFunctions.add(Math.class.getMethod("atan2", double.class, double.class));
083            parameterFunctions.add(Math.class.getMethod("ceil", double.class));
084            parameterFunctions.add(Math.class.getMethod("cos", double.class));
085            parameterFunctions.add(Math.class.getMethod("cosh", double.class));
086            parameterFunctions.add(Math.class.getMethod("exp", double.class));
087            parameterFunctions.add(Math.class.getMethod("floor", double.class));
088            parameterFunctions.add(Math.class.getMethod("log", double.class));
089            parameterFunctions.add(Math.class.getMethod("max", float.class, float.class));
090            parameterFunctions.add(Math.class.getMethod("min", float.class, float.class));
091            parameterFunctions.add(Math.class.getMethod("random"));
092            parameterFunctions.add(Math.class.getMethod("round", float.class));
093            parameterFunctions.add(Math.class.getMethod("signum", double.class));
094            parameterFunctions.add(Math.class.getMethod("sin", double.class));
095            parameterFunctions.add(Math.class.getMethod("sinh", double.class));
096            parameterFunctions.add(Math.class.getMethod("sqrt", double.class));
097            parameterFunctions.add(Math.class.getMethod("tan", double.class));
098            parameterFunctions.add(Math.class.getMethod("tanh", double.class));
099        } catch (NoSuchMethodException | SecurityException ex) {
100            throw new JosmRuntimeException(ex);
101        }
102    }
103
104    private ExpressionFactory() {
105        // Hide default constructor for utils classes
106    }
107
108    /**
109     * List of functions that can be used in MapCSS expressions.
110     *
111     * First parameter can be of type {@link Environment} (if needed). This is
112     * automatically filled in by JOSM and the user only sees the remaining arguments.
113     * When one of the user supplied arguments cannot be converted the
114     * expected type or is null, the function is not called and it returns null
115     * immediately. Add the annotation {@link NullableArguments} to allow null arguments.
116     * Every method must be static.
117     */
118    @SuppressWarnings("UnusedDeclaration")
119    public static final class Functions {
120
121        private Functions() {
122            // Hide implicit public constructor for utility classes
123        }
124
125        /**
126         * Identity function for compatibility with MapCSS specification.
127         * @param o any object
128         * @return {@code o} unchanged
129         */
130        public static Object eval(Object o) { // NO_UCD (unused code)
131            return o;
132        }
133
134        /**
135         * Function associated to the numeric "+" operator.
136         * @param args arguments
137         * @return Sum of arguments
138         */
139        public static float plus(float... args) { // NO_UCD (unused code)
140            float res = 0;
141            for (float f : args) {
142                res += f;
143            }
144            return res;
145        }
146
147        /**
148         * Function associated to the numeric "-" operator.
149         * @param args arguments
150         * @return Substraction of arguments
151         */
152        public static Float minus(float... args) { // NO_UCD (unused code)
153            if (args.length == 0) {
154                return 0.0F;
155            }
156            if (args.length == 1) {
157                return -args[0];
158            }
159            float res = args[0];
160            for (int i = 1; i < args.length; ++i) {
161                res -= args[i];
162            }
163            return res;
164        }
165
166        /**
167         * Function associated to the numeric "*" operator.
168         * @param args arguments
169         * @return Multiplication of arguments
170         */
171        public static float times(float... args) { // NO_UCD (unused code)
172            float res = 1;
173            for (float f : args) {
174                res *= f;
175            }
176            return res;
177        }
178
179        /**
180         * Function associated to the numeric "/" operator.
181         * @param args arguments
182         * @return Division of arguments
183         */
184        public static Float divided_by(float... args) { // NO_UCD (unused code)
185            if (args.length == 0) {
186                return 1.0F;
187            }
188            float res = args[0];
189            for (int i = 1; i < args.length; ++i) {
190                if (args[i] == 0) {
191                    return null;
192                }
193                res /= args[i];
194            }
195            return res;
196        }
197
198        /**
199         * Creates a list of values, e.g., for the {@code dashes} property.
200         * @param args The values to put in a list
201         * @return list of values
202         * @see Arrays#asList(Object[])
203         */
204        public static List<Object> list(Object... args) { // NO_UCD (unused code)
205            return Arrays.asList(args);
206        }
207
208        /**
209         * Returns the number of elements in a list.
210         * @param lst the list
211         * @return length of the list
212         */
213        public static Integer count(List<?> lst) { // NO_UCD (unused code)
214            return lst.size();
215        }
216
217        /**
218         * Returns the first non-null object.
219         * The name originates from <a href="http://wiki.openstreetmap.org/wiki/MapCSS/0.2/eval">MapCSS standard</a>.
220         * @param args arguments
221         * @return the first non-null object
222         * @see Utils#firstNonNull(Object[])
223         */
224        @NullableArguments
225        public static Object any(Object... args) { // NO_UCD (unused code)
226            return Utils.firstNonNull(args);
227        }
228
229        /**
230         * Get the {@code n}th element of the list {@code lst} (counting starts at 0).
231         * @param lst list
232         * @param n index
233         * @return {@code n}th element of the list, or {@code null} if index out of range
234         * @since 5699
235         */
236        public static Object get(List<?> lst, float n) { // NO_UCD (unused code)
237            int idx = Math.round(n);
238            if (idx >= 0 && idx < lst.size()) {
239                return lst.get(idx);
240            }
241            return null;
242        }
243
244        /**
245         * Splits string {@code toSplit} at occurrences of the separator string {@code sep} and returns a list of matches.
246         * @param sep separator string
247         * @param toSplit string to split
248         * @return list of matches
249         * @see String#split(String)
250         * @since 5699
251         */
252        public static List<String> split(String sep, String toSplit) { // NO_UCD (unused code)
253            return Arrays.asList(toSplit.split(Pattern.quote(sep), -1));
254        }
255
256        /**
257         * Creates a color value with the specified amounts of {@code r}ed, {@code g}reen, {@code b}lue (arguments from 0.0 to 1.0)
258         * @param r the red component
259         * @param g the green component
260         * @param b the blue component
261         * @return color matching the given components
262         * @see Color#Color(float, float, float)
263         */
264        public static Color rgb(float r, float g, float b) { // NO_UCD (unused code)
265            try {
266                return new Color(r, g, b);
267            } catch (IllegalArgumentException e) {
268                Logging.trace(e);
269                return null;
270            }
271        }
272
273        /**
274         * Creates a color value with the specified amounts of {@code r}ed, {@code g}reen, {@code b}lue, {@code alpha}
275         * (arguments from 0.0 to 1.0)
276         * @param r the red component
277         * @param g the green component
278         * @param b the blue component
279         * @param alpha the alpha component
280         * @return color matching the given components
281         * @see Color#Color(float, float, float, float)
282         */
283        public static Color rgba(float r, float g, float b, float alpha) { // NO_UCD (unused code)
284            try {
285                return new Color(r, g, b, alpha);
286            } catch (IllegalArgumentException e) {
287                Logging.trace(e);
288                return null;
289            }
290        }
291
292        /**
293         * Create color from hsb color model. (arguments form 0.0 to 1.0)
294         * @param h hue
295         * @param s saturation
296         * @param b brightness
297         * @return the corresponding color
298         */
299        public static Color hsb_color(float h, float s, float b) { // NO_UCD (unused code)
300            try {
301                return Color.getHSBColor(h, s, b);
302            } catch (IllegalArgumentException e) {
303                Logging.trace(e);
304                return null;
305            }
306        }
307
308        /**
309         * Creates a color value from an HTML notation, i.e., {@code #rrggbb}.
310         * @param html HTML notation
311         * @return color matching the given notation
312         */
313        public static Color html2color(String html) { // NO_UCD (unused code)
314            return ColorHelper.html2color(html);
315        }
316
317        /**
318         * Computes the HTML notation ({@code #rrggbb}) for a color value).
319         * @param c color
320         * @return HTML notation matching the given color
321         */
322        public static String color2html(Color c) { // NO_UCD (unused code)
323            return ColorHelper.color2html(c);
324        }
325
326        /**
327         * Get the value of the red color channel in the rgb color model
328         * @param c color
329         * @return the red color channel in the range [0;1]
330         * @see java.awt.Color#getRed()
331         */
332        public static float red(Color c) { // NO_UCD (unused code)
333            return Utils.colorInt2float(c.getRed());
334        }
335
336        /**
337         * Get the value of the green color channel in the rgb color model
338         * @param c color
339         * @return the green color channel in the range [0;1]
340         * @see java.awt.Color#getGreen()
341         */
342        public static float green(Color c) { // NO_UCD (unused code)
343            return Utils.colorInt2float(c.getGreen());
344        }
345
346        /**
347         * Get the value of the blue color channel in the rgb color model
348         * @param c color
349         * @return the blue color channel in the range [0;1]
350         * @see java.awt.Color#getBlue()
351         */
352        public static float blue(Color c) { // NO_UCD (unused code)
353            return Utils.colorInt2float(c.getBlue());
354        }
355
356        /**
357         * Get the value of the alpha channel in the rgba color model
358         * @param c color
359         * @return the alpha channel in the range [0;1]
360         * @see java.awt.Color#getAlpha()
361         */
362        public static float alpha(Color c) { // NO_UCD (unused code)
363            return Utils.colorInt2float(c.getAlpha());
364        }
365
366        /**
367         * Assembles the strings to one.
368         * @param args arguments
369         * @return assembled string
370         * @see Utils#join
371         */
372        @NullableArguments
373        public static String concat(Object... args) { // NO_UCD (unused code)
374            return Utils.join("", Arrays.asList(args));
375        }
376
377        /**
378         * Assembles the strings to one, where the first entry is used as separator.
379         * @param args arguments. First one is used as separator
380         * @return assembled string
381         * @see Utils#join
382         */
383        @NullableArguments
384        public static String join(String... args) { // NO_UCD (unused code)
385            return Utils.join(args[0], Arrays.asList(args).subList(1, args.length));
386        }
387
388        /**
389         * Joins a list of {@code values} into a single string with fields separated by {@code separator}.
390         * @param separator the separator
391         * @param values collection of objects
392         * @return assembled string
393         * @see Utils#join
394         */
395        public static String join_list(final String separator, final List<String> values) { // NO_UCD (unused code)
396            return Utils.join(separator, values);
397        }
398
399        /**
400         * Returns the value of the property {@code key}, e.g., {@code prop("width")}.
401         * @param env the environment
402         * @param key the property key
403         * @return the property value
404         */
405        public static Object prop(final Environment env, String key) { // NO_UCD (unused code)
406            return prop(env, key, null);
407        }
408
409        /**
410         * Returns the value of the property {@code key} from layer {@code layer}.
411         * @param env the environment
412         * @param key the property key
413         * @param layer layer
414         * @return the property value
415         */
416        public static Object prop(final Environment env, String key, String layer) {
417            return env.getCascade(layer).get(key);
418        }
419
420        /**
421         * Determines whether property {@code key} is set.
422         * @param env the environment
423         * @param key the property key
424         * @return {@code true} if the property is set, {@code false} otherwise
425         */
426        public static Boolean is_prop_set(final Environment env, String key) { // NO_UCD (unused code)
427            return is_prop_set(env, key, null);
428        }
429
430        /**
431         * Determines whether property {@code key} is set on layer {@code layer}.
432         * @param env the environment
433         * @param key the property key
434         * @param layer layer
435         * @return {@code true} if the property is set, {@code false} otherwise
436         */
437        public static Boolean is_prop_set(final Environment env, String key, String layer) {
438            return env.getCascade(layer).containsKey(key);
439        }
440
441        /**
442         * Gets the value of the key {@code key} from the object in question.
443         * @param env the environment
444         * @param key the OSM key
445         * @return the value for given key
446         */
447        public static String tag(final Environment env, String key) { // NO_UCD (unused code)
448            return env.osm == null ? null : env.osm.get(key);
449        }
450
451        /**
452         * Gets the first non-null value of the key {@code key} from the object's parent(s).
453         * @param env the environment
454         * @param key the OSM key
455         * @return first non-null value of the key {@code key} from the object's parent(s)
456         */
457        public static String parent_tag(final Environment env, String key) { // NO_UCD (unused code)
458            if (env.parent == null) {
459                if (env.osm != null) {
460                    // we don't have a matched parent, so just search all referrers
461                    for (IPrimitive parent : env.osm.getReferrers()) {
462                        String value = parent.get(key);
463                        if (value != null) {
464                            return value;
465                        }
466                    }
467                }
468                return null;
469            }
470            return env.parent.get(key);
471        }
472
473        /**
474         * Gets a list of all non-null values of the key {@code key} from the object's parent(s).
475         *
476         * The values are sorted according to {@link AlphanumComparator}.
477         * @param env the environment
478         * @param key the OSM key
479         * @return a list of non-null values of the key {@code key} from the object's parent(s)
480         */
481        public static List<String> parent_tags(final Environment env, String key) { // NO_UCD (unused code)
482            if (env.parent == null) {
483                if (env.osm != null) {
484                    final Collection<String> tags = new TreeSet<>(AlphanumComparator.getInstance());
485                    // we don't have a matched parent, so just search all referrers
486                    for (IPrimitive parent : env.osm.getReferrers()) {
487                        String value = parent.get(key);
488                        if (value != null) {
489                            tags.add(value);
490                        }
491                    }
492                    return new ArrayList<>(tags);
493                }
494                return Collections.emptyList();
495            }
496            return Collections.singletonList(env.parent.get(key));
497        }
498
499        /**
500         * Gets the value of the key {@code key} from the object's child.
501         * @param env the environment
502         * @param key the OSM key
503         * @return the value of the key {@code key} from the object's child, or {@code null} if there is no child
504         */
505        public static String child_tag(final Environment env, String key) { // NO_UCD (unused code)
506            return env.child == null ? null : env.child.get(key);
507        }
508
509        /**
510         * Returns the OSM id of the object's parent.
511         * <p>
512         * Parent must be matched by child selector.
513         * @param env the environment
514         * @return the OSM id of the object's parent, if available, or {@code null}
515         * @see IPrimitive#getUniqueId()
516         */
517        public static Long parent_osm_id(final Environment env) { // NO_UCD (unused code)
518            return env.parent == null ? null : env.parent.getUniqueId();
519        }
520
521        /**
522         * Determines whether the object has a tag with the given key.
523         * @param env the environment
524         * @param key the OSM key
525         * @return {@code true} if the object has a tag with the given key, {@code false} otherwise
526         */
527        public static boolean has_tag_key(final Environment env, String key) { // NO_UCD (unused code)
528            return env.osm.hasKey(key);
529        }
530
531        /**
532         * Returns the index of node in parent way or member in parent relation.
533         * @param env the environment
534         * @return the index as float. Starts at 1
535         */
536        public static Float index(final Environment env) { // NO_UCD (unused code)
537            if (env.index == null) {
538                return null;
539            }
540            return Float.valueOf(env.index + 1f);
541        }
542
543        /**
544         * Returns the role of current object in parent relation, or role of child if current object is a relation.
545         * @param env the environment
546         * @return role of current object in parent relation, or role of child if current object is a relation
547         * @see Environment#getRole()
548         */
549        public static String role(final Environment env) { // NO_UCD (unused code)
550            return env.getRole();
551        }
552
553        /**
554         * Returns the area of a closed way or multipolygon in square meters or {@code null}.
555         * @param env the environment
556         * @return the area of a closed way or multipolygon in square meters or {@code null}
557         * @see Geometry#computeArea(IPrimitive)
558         */
559        public static Float areasize(final Environment env) { // NO_UCD (unused code)
560            final Double area = Geometry.computeArea(env.osm);
561            return area == null ? null : area.floatValue();
562        }
563
564        /**
565         * Returns the length of the way in metres or {@code null}.
566         * @param env the environment
567         * @return the length of the way in metres or {@code null}.
568         * @see Way#getLength()
569         */
570        public static Float waylength(final Environment env) { // NO_UCD (unused code)
571            if (env.osm instanceof Way) {
572                return (float) ((Way) env.osm).getLength();
573            } else {
574                return null;
575            }
576        }
577
578        /**
579         * Function associated to the logical "!" operator.
580         * @param b boolean value
581         * @return {@code true} if {@code !b}
582         */
583        public static boolean not(boolean b) { // NO_UCD (unused code)
584            return !b;
585        }
586
587        /**
588         * Function associated to the logical "&gt;=" operator.
589         * @param a first value
590         * @param b second value
591         * @return {@code true} if {@code a &gt;= b}
592         */
593        public static boolean greater_equal(float a, float b) { // NO_UCD (unused code)
594            return a >= b;
595        }
596
597        /**
598         * Function associated to the logical "&lt;=" operator.
599         * @param a first value
600         * @param b second value
601         * @return {@code true} if {@code a &lt;= b}
602         */
603        public static boolean less_equal(float a, float b) { // NO_UCD (unused code)
604            return a <= b;
605        }
606
607        /**
608         * Function associated to the logical "&gt;" operator.
609         * @param a first value
610         * @param b second value
611         * @return {@code true} if {@code a &gt; b}
612         */
613        public static boolean greater(float a, float b) { // NO_UCD (unused code)
614            return a > b;
615        }
616
617        /**
618         * Function associated to the logical "&lt;" operator.
619         * @param a first value
620         * @param b second value
621         * @return {@code true} if {@code a &lt; b}
622         */
623        public static boolean less(float a, float b) { // NO_UCD (unused code)
624            return a < b;
625        }
626
627        /**
628         * Converts an angle in degrees to radians.
629         * @param degree the angle in degrees
630         * @return the angle in radians
631         * @see Math#toRadians(double)
632         */
633        public static double degree_to_radians(double degree) { // NO_UCD (unused code)
634            return Utils.toRadians(degree);
635        }
636
637        /**
638         * Converts an angle diven in cardinal directions to radians.
639         * The following values are supported: {@code n}, {@code north}, {@code ne}, {@code northeast},
640         * {@code e}, {@code east}, {@code se}, {@code southeast}, {@code s}, {@code south},
641         * {@code sw}, {@code southwest}, {@code w}, {@code west}, {@code nw}, {@code northwest}.
642         * @param cardinal the angle in cardinal directions.
643         * @return the angle in radians
644         * @see RotationAngle#parseCardinalRotation(String)
645         */
646        public static Double cardinal_to_radians(String cardinal) { // NO_UCD (unused code)
647            try {
648                return RotationAngle.parseCardinalRotation(cardinal);
649            } catch (IllegalArgumentException ignore) {
650                Logging.trace(ignore);
651                return null;
652            }
653        }
654
655        /**
656         * Determines if the objects {@code a} and {@code b} are equal.
657         * @param a First object
658         * @param b Second object
659         * @return {@code true} if objects are equal, {@code false} otherwise
660         * @see Object#equals(Object)
661         */
662        public static boolean equal(Object a, Object b) {
663            if (a.getClass() == b.getClass()) return a.equals(b);
664            if (a.equals(Cascade.convertTo(b, a.getClass()))) return true;
665            return b.equals(Cascade.convertTo(a, b.getClass()));
666        }
667
668        /**
669         * Determines if the objects {@code a} and {@code b} are not equal.
670         * @param a First object
671         * @param b Second object
672         * @return {@code false} if objects are equal, {@code true} otherwise
673         * @see Object#equals(Object)
674         */
675        public static boolean not_equal(Object a, Object b) { // NO_UCD (unused code)
676            return !equal(a, b);
677        }
678
679        /**
680         * Determines whether the JOSM search with {@code searchStr} applies to the object.
681         * @param env the environment
682         * @param searchStr the search string
683         * @return {@code true} if the JOSM search with {@code searchStr} applies to the object
684         * @see SearchCompiler
685         */
686        public static Boolean JOSM_search(final Environment env, String searchStr) { // NO_UCD (unused code)
687            Match m;
688            try {
689                m = SearchCompiler.compile(searchStr);
690            } catch (SearchParseError ex) {
691                Logging.trace(ex);
692                return null;
693            }
694            return m.match(env.osm);
695        }
696
697        /**
698         * Obtains the JOSM'key {@link org.openstreetmap.josm.data.Preferences} string for key {@code key},
699         * and defaults to {@code def} if that is null.
700         * @param env the environment
701         * @param key Key in JOSM preference
702         * @param def Default value
703         * @return value for key, or default value if not found
704         */
705        public static String JOSM_pref(Environment env, String key, String def) { // NO_UCD (unused code)
706            return MapPaintStyles.getStyles().getPreferenceCached(key, def);
707        }
708
709        /**
710         * Tests if string {@code target} matches pattern {@code pattern}
711         * @param pattern The regex expression
712         * @param target The character sequence to be matched
713         * @return {@code true} if, and only if, the entire region sequence matches the pattern
714         * @see Pattern#matches(String, CharSequence)
715         * @since 5699
716         */
717        public static boolean regexp_test(String pattern, String target) { // NO_UCD (unused code)
718            return Pattern.matches(pattern, target);
719        }
720
721        /**
722         * Tests if string {@code target} matches pattern {@code pattern}
723         * @param pattern The regex expression
724         * @param target The character sequence to be matched
725         * @param flags a string that may contain "i" (case insensitive), "m" (multiline) and "s" ("dot all")
726         * @return {@code true} if, and only if, the entire region sequence matches the pattern
727         * @see Pattern#CASE_INSENSITIVE
728         * @see Pattern#DOTALL
729         * @see Pattern#MULTILINE
730         * @since 5699
731         */
732        public static boolean regexp_test(String pattern, String target, String flags) { // NO_UCD (unused code)
733            int f = 0;
734            if (flags.contains("i")) {
735                f |= Pattern.CASE_INSENSITIVE;
736            }
737            if (flags.contains("s")) {
738                f |= Pattern.DOTALL;
739            }
740            if (flags.contains("m")) {
741                f |= Pattern.MULTILINE;
742            }
743            return Pattern.compile(pattern, f).matcher(target).matches();
744        }
745
746        /**
747         * Tries to match string against pattern regexp and returns a list of capture groups in case of success.
748         * The first element (index 0) is the complete match (i.e. string).
749         * Further elements correspond to the bracketed parts of the regular expression.
750         * @param pattern The regex expression
751         * @param target The character sequence to be matched
752         * @param flags a string that may contain "i" (case insensitive), "m" (multiline) and "s" ("dot all")
753         * @return a list of capture groups if {@link Matcher#matches()}, or {@code null}.
754         * @see Pattern#CASE_INSENSITIVE
755         * @see Pattern#DOTALL
756         * @see Pattern#MULTILINE
757         * @since 5701
758         */
759        public static List<String> regexp_match(String pattern, String target, String flags) { // NO_UCD (unused code)
760            int f = 0;
761            if (flags.contains("i")) {
762                f |= Pattern.CASE_INSENSITIVE;
763            }
764            if (flags.contains("s")) {
765                f |= Pattern.DOTALL;
766            }
767            if (flags.contains("m")) {
768                f |= Pattern.MULTILINE;
769            }
770            return Utils.getMatches(Pattern.compile(pattern, f).matcher(target));
771        }
772
773        /**
774         * Tries to match string against pattern regexp and returns a list of capture groups in case of success.
775         * The first element (index 0) is the complete match (i.e. string).
776         * Further elements correspond to the bracketed parts of the regular expression.
777         * @param pattern The regex expression
778         * @param target The character sequence to be matched
779         * @return a list of capture groups if {@link Matcher#matches()}, or {@code null}.
780         * @since 5701
781         */
782        public static List<String> regexp_match(String pattern, String target) { // NO_UCD (unused code)
783            return Utils.getMatches(Pattern.compile(pattern).matcher(target));
784        }
785
786        /**
787         * Returns the OSM id of the current object.
788         * @param env the environment
789         * @return the OSM id of the current object
790         * @see IPrimitive#getUniqueId()
791         */
792        public static long osm_id(final Environment env) { // NO_UCD (unused code)
793            return env.osm.getUniqueId();
794        }
795
796        /**
797         * Translates some text for the current locale. The first argument is the text to translate,
798         * and the subsequent arguments are parameters for the string indicated by <code>{0}</code>, <code>{1}</code>, …
799         * @param args arguments
800         * @return the translated string
801         */
802        @NullableArguments
803        public static String tr(String... args) { // NO_UCD (unused code)
804            final String text = args[0];
805            System.arraycopy(args, 1, args, 0, args.length - 1);
806            return org.openstreetmap.josm.tools.I18n.tr(text, (Object[]) args);
807        }
808
809        /**
810         * Returns the substring of {@code s} starting at index {@code begin} (inclusive, 0-indexed).
811         * @param s The base string
812         * @param begin The start index
813         * @return the substring
814         * @see String#substring(int)
815         */
816        public static String substring(String s, /* due to missing Cascade.convertTo for int*/ float begin) { // NO_UCD (unused code)
817            return s == null ? null : s.substring((int) begin);
818        }
819
820        /**
821         * Returns the substring of {@code s} starting at index {@code begin} (inclusive)
822         * and ending at index {@code end}, (exclusive, 0-indexed).
823         * @param s The base string
824         * @param begin The start index
825         * @param end The end index
826         * @return the substring
827         * @see String#substring(int, int)
828         */
829        public static String substring(String s, float begin, float end) { // NO_UCD (unused code)
830            return s == null ? null : s.substring((int) begin, (int) end);
831        }
832
833        /**
834         * Replaces in {@code s} every {@code} target} substring by {@code replacement}.
835         * @param s The source string
836         * @param target The sequence of char values to be replaced
837         * @param replacement The replacement sequence of char values
838         * @return The resulting string
839         * @see String#replace(CharSequence, CharSequence)
840         */
841        public static String replace(String s, String target, String replacement) { // NO_UCD (unused code)
842            return s == null ? null : s.replace(target, replacement);
843        }
844
845        /**
846         * Converts string {@code s} to uppercase.
847         * @param s The source string
848         * @return The resulting string
849         * @see String#toUpperCase(Locale)
850         * @since 11756
851         */
852        public static String upper(String s) {
853            return s == null ? null : s.toUpperCase(Locale.ENGLISH);
854        }
855
856        /**
857         * Converts string {@code s} to lowercase.
858         * @param s The source string
859         * @return The resulting string
860         * @see String#toLowerCase(Locale)
861         * @since 11756
862         */
863        public static String lower(String s) {
864            return s == null ? null : s.toLowerCase(Locale.ENGLISH);
865        }
866
867        /**
868         * Trim whitespaces from the string {@code s}.
869         * @param s The source string
870         * @return The resulting string
871         * @see Utils#strip
872         * @since 11756
873         */
874        public static String trim(String s) {
875            return Utils.strip(s);
876        }
877
878        /**
879         * Percent-decode a string. (See https://en.wikipedia.org/wiki/Percent-encoding)
880         * This is especially useful for wikipedia titles
881         * @param s url-encoded string
882         * @return the decoded string, or original in case of an error
883         * @since 11756
884         */
885        public static String URL_decode(String s) {
886            if (s == null) return null;
887            try {
888                return Utils.decodeUrl(s);
889            } catch (IllegalStateException e) {
890                Logging.debug(e);
891                return s;
892            }
893        }
894
895        /**
896         * Percent-encode a string. (See https://en.wikipedia.org/wiki/Percent-encoding)
897         * This is especially useful for data urls, e.g.
898         * <code>concat("data:image/svg+xml,", URL_encode("&lt;svg&gt;...&lt;/svg&gt;"));</code>
899         * @param s arbitrary string
900         * @return the encoded string
901         */
902        public static String URL_encode(String s) { // NO_UCD (unused code)
903            return s == null ? null : Utils.encodeUrl(s);
904        }
905
906        /**
907         * XML-encode a string.
908         *
909         * Escapes special characters in xml. Alternative to using &lt;![CDATA[ ... ]]&gt; blocks.
910         * @param s arbitrary string
911         * @return the encoded string
912         */
913        public static String XML_encode(String s) { // NO_UCD (unused code)
914            return s == null ? null : XmlWriter.encode(s);
915        }
916
917        /**
918         * Calculates the CRC32 checksum from a string (based on RFC 1952).
919         * @param s the string
920         * @return long value from 0 to 2^32-1
921         */
922        public static long CRC32_checksum(String s) { // NO_UCD (unused code)
923            CRC32 cs = new CRC32();
924            cs.update(s.getBytes(StandardCharsets.UTF_8));
925            return cs.getValue();
926        }
927
928        /**
929         * check if there is right-hand traffic at the current location
930         * @param env the environment
931         * @return true if there is right-hand traffic
932         * @since 7193
933         */
934        public static boolean is_right_hand_traffic(Environment env) {
935            return RightAndLefthandTraffic.isRightHandTraffic(center(env));
936        }
937
938        /**
939         * Determines whether the way is {@link Geometry#isClockwise closed and oriented clockwise},
940         * or non-closed and the {@link Geometry#angleIsClockwise 1st, 2nd and last node are in clockwise order}.
941         *
942         * @param env the environment
943         * @return true if the way is closed and oriented clockwise
944         */
945        public static boolean is_clockwise(Environment env) {
946            if (!(env.osm instanceof Way)) {
947                return false;
948            }
949            final Way way = (Way) env.osm;
950            return (way.isClosed() && Geometry.isClockwise(way))
951                || (!way.isClosed() && way.getNodesCount() > 2 && Geometry.angleIsClockwise(way.getNode(0), way.getNode(1), way.lastNode()));
952        }
953
954        /**
955         * Determines whether the way is {@link Geometry#isClockwise closed and oriented anticlockwise},
956         * or non-closed and the {@link Geometry#angleIsClockwise 1st, 2nd and last node are in anticlockwise order}.
957         *
958         * @param env the environment
959         * @return true if the way is closed and oriented clockwise
960         */
961        public static boolean is_anticlockwise(Environment env) {
962            if (!(env.osm instanceof Way)) {
963                return false;
964            }
965            final Way way = (Way) env.osm;
966            return (way.isClosed() && !Geometry.isClockwise(way))
967                || (!way.isClosed() && way.getNodesCount() > 2 && !Geometry.angleIsClockwise(way.getNode(0), way.getNode(1), way.lastNode()));
968        }
969
970        /**
971         * Prints the object to the command line (for debugging purpose).
972         * @param o the object
973         * @return the same object, unchanged
974         */
975        @NullableArguments
976        public static Object print(Object o) { // NO_UCD (unused code)
977            System.out.print(o == null ? "none" : o.toString());
978            return o;
979        }
980
981        /**
982         * Prints the object to the command line, with new line at the end
983         * (for debugging purpose).
984         * @param o the object
985         * @return the same object, unchanged
986         */
987        @NullableArguments
988        public static Object println(Object o) { // NO_UCD (unused code)
989            System.out.println(o == null ? "none" : o.toString());
990            return o;
991        }
992
993        /**
994         * Get the number of tags for the current primitive.
995         * @param env the environment
996         * @return number of tags
997         */
998        public static int number_of_tags(Environment env) { // NO_UCD (unused code)
999            return env.osm.getNumKeys();
1000        }
1001
1002        /**
1003         * Get value of a setting.
1004         * @param env the environment
1005         * @param key setting key (given as layer identifier, e.g. setting::mykey {...})
1006         * @return the value of the setting (calculated when the style is loaded)
1007         */
1008        public static Object setting(Environment env, String key) { // NO_UCD (unused code)
1009            return env.source.settingValues.get(key);
1010        }
1011
1012        /**
1013         * Returns the center of the environment OSM primitive.
1014         * @param env the environment
1015         * @return the center of the environment OSM primitive
1016         * @since 11247
1017         */
1018        public static LatLon center(Environment env) { // NO_UCD (unused code)
1019            return env.osm instanceof Node ? ((Node) env.osm).getCoor() : env.osm.getBBox().getCenter();
1020        }
1021
1022        /**
1023         * Determines if the object is inside territories matching given ISO3166 codes.
1024         * @param env the environment
1025         * @param codes comma-separated list of ISO3166-1-alpha2 or ISO3166-2 country/subdivision codes
1026         * @return {@code true} if the object is inside territory matching given ISO3166 codes
1027         * @since 11247
1028         */
1029        public static boolean inside(Environment env, String codes) { // NO_UCD (unused code)
1030            for (String code : codes.toUpperCase(Locale.ENGLISH).split(",")) {
1031                if (Territories.isIso3166Code(code.trim(), center(env))) {
1032                    return true;
1033                }
1034            }
1035            return false;
1036        }
1037
1038        /**
1039         * Determines if the object is outside territories matching given ISO3166 codes.
1040         * @param env the environment
1041         * @param codes comma-separated list of ISO3166-1-alpha2 or ISO3166-2 country/subdivision codes
1042         * @return {@code true} if the object is outside territory matching given ISO3166 codes
1043         * @since 11247
1044         */
1045        public static boolean outside(Environment env, String codes) { // NO_UCD (unused code)
1046            return !inside(env, codes);
1047        }
1048
1049        /**
1050         * Determines if the object centroid lies at given lat/lon coordinates.
1051         * @param env the environment
1052         * @param lat latitude, i.e., the north-south position in degrees
1053         * @param lon longitude, i.e., the east-west position in degrees
1054         * @return {@code true} if the object centroid lies at given lat/lon coordinates
1055         * @since 12514
1056         */
1057        public static boolean at(Environment env, double lat, double lon) { // NO_UCD (unused code)
1058            return new LatLon(lat, lon).equalsEpsilon(center(env));
1059        }
1060    }
1061
1062    /**
1063     * Main method to create an function-like expression.
1064     *
1065     * @param name the name of the function or operator
1066     * @param args the list of arguments (as expressions)
1067     * @return the generated Expression. If no suitable function can be found,
1068     * returns {@link NullExpression#INSTANCE}.
1069     */
1070    public static Expression createFunctionExpression(String name, List<Expression> args) {
1071        if ("cond".equals(name) && args.size() == 3)
1072            return new CondOperator(args.get(0), args.get(1), args.get(2));
1073        else if ("and".equals(name))
1074            return new AndOperator(args);
1075        else if ("or".equals(name))
1076            return new OrOperator(args);
1077        else if ("length".equals(name) && args.size() == 1)
1078            return new LengthFunction(args.get(0));
1079        else if ("max".equals(name) && !args.isEmpty())
1080            return new MinMaxFunction(args, true);
1081        else if ("min".equals(name) && !args.isEmpty())
1082            return new MinMaxFunction(args, false);
1083
1084        for (Method m : arrayFunctions) {
1085            if (m.getName().equals(name))
1086                return new ArrayFunction(m, args);
1087        }
1088        for (Method m : parameterFunctions) {
1089            if (m.getName().equals(name) && args.size() == m.getParameterTypes().length)
1090                return new ParameterFunction(m, args, false);
1091        }
1092        for (Method m : parameterFunctionsEnv) {
1093            if (m.getName().equals(name) && args.size() == m.getParameterTypes().length-1)
1094                return new ParameterFunction(m, args, true);
1095        }
1096        return NullExpression.INSTANCE;
1097    }
1098
1099    /**
1100     * Expression that always evaluates to null.
1101     */
1102    public static class NullExpression implements Expression {
1103
1104        /**
1105         * The unique instance.
1106         */
1107        public static final NullExpression INSTANCE = new NullExpression();
1108
1109        @Override
1110        public Object evaluate(Environment env) {
1111            return null;
1112        }
1113    }
1114
1115    /**
1116     * Conditional operator.
1117     */
1118    public static class CondOperator implements Expression {
1119
1120        private final Expression condition, firstOption, secondOption;
1121
1122        /**
1123         * Constructs a new {@code CondOperator}.
1124         * @param condition condition
1125         * @param firstOption first option
1126         * @param secondOption second option
1127         */
1128        public CondOperator(Expression condition, Expression firstOption, Expression secondOption) {
1129            this.condition = condition;
1130            this.firstOption = firstOption;
1131            this.secondOption = secondOption;
1132        }
1133
1134        @Override
1135        public Object evaluate(Environment env) {
1136            Boolean b = Cascade.convertTo(condition.evaluate(env), boolean.class);
1137            if (b != null && b)
1138                return firstOption.evaluate(env);
1139            else
1140                return secondOption.evaluate(env);
1141        }
1142    }
1143
1144    /**
1145     * "And" logical operator.
1146     */
1147    public static class AndOperator implements Expression {
1148
1149        private final List<Expression> args;
1150
1151        /**
1152         * Constructs a new {@code AndOperator}.
1153         * @param args arguments
1154         */
1155        public AndOperator(List<Expression> args) {
1156            this.args = args;
1157        }
1158
1159        @Override
1160        public Object evaluate(Environment env) {
1161            for (Expression arg : args) {
1162                Boolean b = Cascade.convertTo(arg.evaluate(env), boolean.class);
1163                if (b == null || !b) {
1164                    return Boolean.FALSE;
1165                }
1166            }
1167            return Boolean.TRUE;
1168        }
1169    }
1170
1171    /**
1172     * "Or" logical operator.
1173     */
1174    public static class OrOperator implements Expression {
1175
1176        private final List<Expression> args;
1177
1178        /**
1179         * Constructs a new {@code OrOperator}.
1180         * @param args arguments
1181         */
1182        public OrOperator(List<Expression> args) {
1183            this.args = args;
1184        }
1185
1186        @Override
1187        public Object evaluate(Environment env) {
1188            for (Expression arg : args) {
1189                Boolean b = Cascade.convertTo(arg.evaluate(env), boolean.class);
1190                if (b != null && b) {
1191                    return Boolean.TRUE;
1192                }
1193            }
1194            return Boolean.FALSE;
1195        }
1196    }
1197
1198    /**
1199     * Function to calculate the length of a string or list in a MapCSS eval expression.
1200     *
1201     * Separate implementation to support overloading for different argument types.
1202     *
1203     * The use for calculating the length of a list is deprecated, use
1204     * {@link Functions#count(java.util.List)} instead (see #10061).
1205     */
1206    public static class LengthFunction implements Expression {
1207
1208        private final Expression arg;
1209
1210        /**
1211         * Constructs a new {@code LengthFunction}.
1212         * @param args arguments
1213         */
1214        public LengthFunction(Expression args) {
1215            this.arg = args;
1216        }
1217
1218        @Override
1219        public Object evaluate(Environment env) {
1220            List<?> l = Cascade.convertTo(arg.evaluate(env), List.class);
1221            if (l != null)
1222                return l.size();
1223            String s = Cascade.convertTo(arg.evaluate(env), String.class);
1224            if (s != null)
1225                return s.length();
1226            return null;
1227        }
1228    }
1229
1230    /**
1231     * Computes the maximum/minimum value an arbitrary number of floats, or a list of floats.
1232     */
1233    public static class MinMaxFunction implements Expression {
1234
1235        private final List<Expression> args;
1236        private final boolean computeMax;
1237
1238        /**
1239         * Constructs a new {@code MinMaxFunction}.
1240         * @param args arguments
1241         * @param computeMax if {@code true}, compute max. If {@code false}, compute min
1242         */
1243        public MinMaxFunction(final List<Expression> args, final boolean computeMax) {
1244            this.args = args;
1245            this.computeMax = computeMax;
1246        }
1247
1248        /**
1249         * Compute the minimum / maximum over the list
1250         * @param lst The list
1251         * @return The minimum or maximum depending on {@link #computeMax}
1252         */
1253        public Float aggregateList(List<?> lst) {
1254            final List<Float> floats = Utils.transform(lst, (Function<Object, Float>) x -> Cascade.convertTo(x, float.class));
1255            final Collection<Float> nonNullList = SubclassFilteredCollection.filter(floats, Objects::nonNull);
1256            return nonNullList.isEmpty() ? (Float) Float.NaN : computeMax ? Collections.max(nonNullList) : Collections.min(nonNullList);
1257        }
1258
1259        @Override
1260        public Object evaluate(final Environment env) {
1261            List<?> l = Cascade.convertTo(args.get(0).evaluate(env), List.class);
1262            if (args.size() != 1 || l == null)
1263                l = Utils.transform(args, (Function<Expression, Object>) x -> x.evaluate(env));
1264            return aggregateList(l);
1265        }
1266    }
1267
1268    /**
1269     * Function that takes a certain number of argument with specific type.
1270     *
1271     * Implementation is based on a Method object.
1272     * If any of the arguments evaluate to null, the result will also be null.
1273     */
1274    public static class ParameterFunction implements Expression {
1275
1276        private final Method m;
1277        private final boolean nullable;
1278        private final List<Expression> args;
1279        private final Class<?>[] expectedParameterTypes;
1280        private final boolean needsEnvironment;
1281
1282        /**
1283         * Constructs a new {@code ParameterFunction}.
1284         * @param m method
1285         * @param args arguments
1286         * @param needsEnvironment whether function needs environment
1287         */
1288        public ParameterFunction(Method m, List<Expression> args, boolean needsEnvironment) {
1289            this.m = m;
1290            this.nullable = m.getAnnotation(NullableArguments.class) != null;
1291            this.args = args;
1292            this.expectedParameterTypes = m.getParameterTypes();
1293            this.needsEnvironment = needsEnvironment;
1294        }
1295
1296        @Override
1297        public Object evaluate(Environment env) {
1298            Object[] convertedArgs;
1299
1300            if (needsEnvironment) {
1301                convertedArgs = new Object[args.size()+1];
1302                convertedArgs[0] = env;
1303                for (int i = 1; i < convertedArgs.length; ++i) {
1304                    convertedArgs[i] = Cascade.convertTo(args.get(i-1).evaluate(env), expectedParameterTypes[i]);
1305                    if (convertedArgs[i] == null && !nullable) {
1306                        return null;
1307                    }
1308                }
1309            } else {
1310                convertedArgs = new Object[args.size()];
1311                for (int i = 0; i < convertedArgs.length; ++i) {
1312                    convertedArgs[i] = Cascade.convertTo(args.get(i).evaluate(env), expectedParameterTypes[i]);
1313                    if (convertedArgs[i] == null && !nullable) {
1314                        return null;
1315                    }
1316                }
1317            }
1318            Object result = null;
1319            try {
1320                result = m.invoke(null, convertedArgs);
1321            } catch (IllegalAccessException | IllegalArgumentException ex) {
1322                throw new JosmRuntimeException(ex);
1323            } catch (InvocationTargetException ex) {
1324                Logging.error(ex);
1325                return null;
1326            }
1327            return result;
1328        }
1329
1330        @Override
1331        public String toString() {
1332            StringBuilder b = new StringBuilder("ParameterFunction~");
1333            b.append(m.getName()).append('(');
1334            for (int i = 0; i < expectedParameterTypes.length; ++i) {
1335                if (i > 0) b.append(',');
1336                b.append(expectedParameterTypes[i]);
1337                if (!needsEnvironment) {
1338                    b.append(' ').append(args.get(i));
1339                } else if (i > 0) {
1340                    b.append(' ').append(args.get(i-1));
1341                }
1342            }
1343            b.append(')');
1344            return b.toString();
1345        }
1346    }
1347
1348    /**
1349     * Function that takes an arbitrary number of arguments.
1350     *
1351     * Currently, all array functions are static, so there is no need to
1352     * provide the environment, like it is done in {@link ParameterFunction}.
1353     * If any of the arguments evaluate to null, the result will also be null.
1354     */
1355    public static class ArrayFunction implements Expression {
1356
1357        private final Method m;
1358        private final boolean nullable;
1359        private final List<Expression> args;
1360        private final Class<?>[] expectedParameterTypes;
1361        private final Class<?> arrayComponentType;
1362
1363        /**
1364         * Constructs a new {@code ArrayFunction}.
1365         * @param m method
1366         * @param args arguments
1367         */
1368        public ArrayFunction(Method m, List<Expression> args) {
1369            this.m = m;
1370            this.nullable = m.getAnnotation(NullableArguments.class) != null;
1371            this.args = args;
1372            this.expectedParameterTypes = m.getParameterTypes();
1373            this.arrayComponentType = expectedParameterTypes[0].getComponentType();
1374        }
1375
1376        @Override
1377        public Object evaluate(Environment env) {
1378            Object[] convertedArgs = new Object[expectedParameterTypes.length];
1379            Object arrayArg = Array.newInstance(arrayComponentType, args.size());
1380            for (int i = 0; i < args.size(); ++i) {
1381                Object o = Cascade.convertTo(args.get(i).evaluate(env), arrayComponentType);
1382                if (o == null && !nullable) {
1383                    return null;
1384                }
1385                Array.set(arrayArg, i, o);
1386            }
1387            convertedArgs[0] = arrayArg;
1388
1389            Object result = null;
1390            try {
1391                result = m.invoke(null, convertedArgs);
1392            } catch (IllegalAccessException | IllegalArgumentException ex) {
1393                throw new JosmRuntimeException(ex);
1394            } catch (InvocationTargetException ex) {
1395                Logging.error(ex);
1396                return null;
1397            }
1398            return result;
1399        }
1400
1401        @Override
1402        public String toString() {
1403            StringBuilder b = new StringBuilder("ArrayFunction~");
1404            b.append(m.getName()).append('(');
1405            for (int i = 0; i < args.size(); ++i) {
1406                if (i > 0) b.append(',');
1407                b.append(arrayComponentType).append(' ').append(args.get(i));
1408            }
1409            b.append(')');
1410            return b.toString();
1411        }
1412    }
1413}