summaryrefslogtreecommitdiff
path: root/indra/llcommon/llsdutil.h
blob: cd68f938ea91ca0ff279221090b8c2918cdc40f8 (plain)
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
/** 
 * @file llsdutil.h
 * @author Phoenix
 * @date 2006-05-24
 * @brief Utility classes, functions, etc, for using structured data.
 *
 * $LicenseInfo:firstyear=2006&license=viewerlgpl$
 * Second Life Viewer Source Code
 * Copyright (C) 2010, Linden Research, Inc.
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License only.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 * $/LicenseInfo$
 */

#ifndef LL_LLSDUTIL_H
#define LL_LLSDUTIL_H

#include "apply.h"                  // LL::invoke()
#include "function_types.h"         // LL::function_arity
#include "llsd.h"
#include <boost/functional/hash.hpp>
#include <cassert>
#include <type_traits>

// U32
LL_COMMON_API LLSD ll_sd_from_U32(const U32);
LL_COMMON_API U32 ll_U32_from_sd(const LLSD& sd);

// U64
LL_COMMON_API LLSD ll_sd_from_U64(const U64);
LL_COMMON_API U64 ll_U64_from_sd(const LLSD& sd);

// IP Address
LL_COMMON_API LLSD ll_sd_from_ipaddr(const U32);
LL_COMMON_API U32 ll_ipaddr_from_sd(const LLSD& sd);

// Binary to string
LL_COMMON_API LLSD ll_string_from_binary(const LLSD& sd);

//String to binary
LL_COMMON_API LLSD ll_binary_from_string(const LLSD& sd);

// Serializes sd to static buffer and returns pointer, useful for gdb debugging.
LL_COMMON_API char* ll_print_sd(const LLSD& sd);

// Serializes sd to static buffer and returns pointer, using "pretty printing" mode.
LL_COMMON_API char* ll_pretty_print_sd_ptr(const LLSD* sd);
LL_COMMON_API char* ll_pretty_print_sd(const LLSD& sd);

LL_COMMON_API std::string ll_stream_notation_sd(const LLSD& sd);

//compares the structure of an LLSD to a template LLSD and stores the
//"valid" values in a 3rd LLSD. Default values
//are pulled from the template.  Extra keys/values in the test
//are ignored in the resultant LLSD.  Ordering of arrays matters
//Returns false if the test is of same type but values differ in type
//Otherwise, returns true

LL_COMMON_API BOOL compare_llsd_with_template(
	const LLSD& llsd_to_test,
	const LLSD& template_llsd,
	LLSD& resultant_llsd);

// filter_llsd_with_template() is a direct clone (copy-n-paste) of 
// compare_llsd_with_template with the following differences:
// (1) bool vs BOOL return types
// (2) A map with the key value "*" is a special value and maps any key in the
//     test llsd that doesn't have an explicitly matching key in the template.
// (3) The element of an array with exactly one element is taken as a template
//     for *all* the elements of the test array.  If the template array is of
//     different size, compare_llsd_with_template() semantics apply.
bool filter_llsd_with_template(
	const LLSD & llsd_to_test,
	const LLSD & template_llsd,
	LLSD & resultant_llsd);

/**
 * Recursively determine whether a given LLSD data block "matches" another
 * LLSD prototype. The returned string is empty() on success, non-empty() on
 * mismatch.
 *
 * This function tests structure (types) rather than data values. It is
 * intended for when a consumer expects an LLSD block with a particular
 * structure, and must succinctly detect whether the arriving block is
 * well-formed. For instance, a test of the form:
 * @code
 * if (! (data.has("request") && data.has("target") && data.has("modifier") ...))
 * @endcode
 * could instead be expressed by initializing a prototype LLSD map with the
 * required keys and writing:
 * @code
 * if (! llsd_matches(prototype, data).empty())
 * @endcode
 *
 * A non-empty return value is an error-message fragment intended to indicate
 * to (English-speaking) developers where in the prototype structure the
 * mismatch occurred.
 *
 * * If a slot in the prototype isUndefined(), then anything is valid at that
 *   place in the real object. (Passing prototype == LLSD() matches anything
 *   at all.)
 * * An array in the prototype must match a data array at least that large.
 *   (Additional entries in the data array are ignored.) Every isDefined()
 *   entry in the prototype array must match the corresponding entry in the
 *   data array.
 * * A map in the prototype must match a map in the data. Every key in the
 *   prototype map must match a corresponding key in the data map. (Additional
 *   keys in the data map are ignored.) Every isDefined() value in the
 *   prototype map must match the corresponding key's value in the data map.
 * * Scalar values in the prototype are tested for @em type rather than value.
 *   For instance, a String in the prototype matches any String at all. In
 *   effect, storing an Integer at a particular place in the prototype asserts
 *   that the caller intends to apply asInteger() to the corresponding slot in
 *   the data.
 * * A String in the prototype matches String, Boolean, Integer, Real, UUID,
 *   Date and URI, because asString() applied to any of these produces a
 *   meaningful result.
 * * Similarly, a Boolean, Integer or Real in the prototype can match any of
 *   Boolean, Integer or Real in the data -- or even String.
 * * UUID matches UUID or String.
 * * Date matches Date or String.
 * * URI matches URI or String.
 * * Binary in the prototype matches only Binary in the data.
 *
 * @TODO: when a Boolean, Integer or Real in the prototype matches a String in
 * the data, we should examine the String @em value to ensure it can be
 * meaningfully converted to the requested type. The same goes for UUID, Date
 * and URI.
 */
LL_COMMON_API std::string llsd_matches(const LLSD& prototype, const LLSD& data, const std::string& pfx="");

/// Deep equality. If you want to compare LLSD::Real values for approximate
/// equality rather than bitwise equality, pass @a bits as for
/// is_approx_equal_fraction().
LL_COMMON_API bool llsd_equals(const LLSD& lhs, const LLSD& rhs, int bits=-1);
/// If you don't care about LLSD::Real equality
inline bool operator==(const LLSD& lhs, const LLSD& rhs)
{
    return llsd_equals(lhs, rhs);
}
inline bool operator!=(const LLSD& lhs, const LLSD& rhs)
{
    // operator!=() should always be the negation of operator==()
    return ! (lhs == rhs);
}

// Simple function to copy data out of input & output iterators if
// there is no need for casting.
template<typename Input> LLSD llsd_copy_array(Input iter, Input end)
{
	LLSD dest;
	for (; iter != end; ++iter)
	{
		dest.append(*iter);
	}
	return dest;
}

namespace llsd
{

/**
 * Drill down to locate an element in 'blob' according to 'path', where 'path'
 * is one of the following:
 *
 * - LLSD::String: 'blob' is an LLSD::Map. Find the entry with key 'path'.
 * - LLSD::Integer: 'blob' is an LLSD::Array. Find the entry with index 'path'.
 * - Any other 'path' type will be interpreted as LLSD::Array, and 'blob' is a
 *   nested structure. For each element of 'path':
 *   - If it's an LLSD::Integer, select the entry with that index from an
 *     LLSD::Array at that level.
 *   - If it's an LLSD::String, select the entry with that key from an
 *     LLSD::Map at that level.
 *   - Anything else is an error.
 *
 * By implication, if path.isUndefined() or otherwise equivalent to an empty
 * LLSD::Array, drill[_ref]() returns 'blob' as is.
 */
LLSD  drill(const LLSD& blob, const LLSD& path);
LLSD& drill_ref(  LLSD& blob, const LLSD& path);

}

namespace llsd
{

/**
 * Construct an LLSD::Array inline, using modern C++ variadic arguments.
 */

// recursion tail
inline
void array_(LLSD&) {}

// recursive call
template <typename T0, typename... Ts>
void array_(LLSD& data, T0&& v0, Ts&&... vs)
{
    data.append(std::forward<T0>(v0));
    array_(data, std::forward<Ts>(vs)...);
}

// public interface
template <typename... Ts>
LLSD array(Ts&&... vs)
{
    LLSD data;
    array_(data, std::forward<Ts>(vs)...);
    return data;
}

} // namespace llsd

/*****************************************************************************
*   LLSDMap
*****************************************************************************/
/**
 * Construct an LLSD::Map inline, with implicit conversion to LLSD. Usage:
 *
 * @code
 * void somefunc(const LLSD&);
 * ...
 * somefunc(LLSDMap("alpha", "abc")("number", 17)("pi", 3.14));
 * @endcode
 *
 * For completeness, LLSDMap() with no args constructs an empty map, so
 * <tt>LLSDMap()("alpha", "abc")("number", 17)("pi", 3.14)</tt> produces a map
 * equivalent to the above. But for most purposes, LLSD() is already
 * equivalent to an empty map, and if you explicitly want an empty isMap(),
 * there's LLSD::emptyMap(). However, supporting a no-args LLSDMap()
 * constructor follows the principle of least astonishment.
 */
class LLSDMap
{
public:
    LLSDMap():
        _data(LLSD::emptyMap())
    {}
    LLSDMap(const LLSD::String& key, const LLSD& value):
        _data(LLSD::emptyMap())
    {
        _data[key] = value;
    }

    LLSDMap& operator()(const LLSD::String& key, const LLSD& value)
    {
        _data[key] = value;
        return *this;
    }

    operator LLSD() const { return _data; }
    LLSD get() const { return _data; }

private:
    LLSD _data;
};

namespace llsd
{

/**
 * Construct an LLSD::Map inline, using modern C++ variadic arguments.
 */

// recursion tail
inline
void map_(LLSD&) {}

// recursive call
template <typename T0, typename... Ts>
void map_(LLSD& data, const LLSD::String& k0, T0&& v0, Ts&&... vs)
{
    data[k0] = v0;
    map_(data, std::forward<Ts>(vs)...);
}

// public interface
template <typename... Ts>
LLSD map(Ts&&... vs)
{
    LLSD data;
    map_(data, std::forward<Ts>(vs)...);
    return data;
}

} // namespace llsd

/*****************************************************************************
*   LLSDParam
*****************************************************************************/
/**
 * LLSDParam is a customization point for passing LLSD values to function
 * parameters of more or less arbitrary type. LLSD provides a small set of
 * native conversions; but if a generic algorithm explicitly constructs an
 * LLSDParam object in the function's argument list, a consumer can provide
 * LLSDParam specializations to support more different parameter types than
 * LLSD's native conversions.
 *
 * Usage:
 *
 * @code
 * void somefunc(const paramtype&);
 * ...
 * somefunc(..., LLSDParam<paramtype>(someLLSD), ...);
 * @endcode
 */
template <typename T>
class LLSDParam
{
public:
    /**
     * Default implementation converts to T on construction, saves converted
     * value for later retrieval
     */
    LLSDParam(const LLSD& value):
        _value(value)
    {}

    operator T() const { return _value; }

private:
    T _value;
};

/**
 * LLSDParam<LLSD> is for when you don't already have the target parameter
 * type in hand. Instantiate LLSDParam<LLSD>(your LLSD object), and the
 * templated conversion operator will try to select a more specific LLSDParam
 * specialization.
 */
template <>
class LLSDParam<LLSD>
{
private:
    LLSD value_;

public:
    LLSDParam(const LLSD& value): value_(value) {}

    /// if we're literally being asked for an LLSD parameter, avoid infinite
    /// recursion
    operator LLSD() const { return value_; }

    /// otherwise, instantiate a more specific LLSDParam<T> to convert; that
    /// preserves the existing customization mechanism
    template <typename T>
    operator T() const { return LLSDParam<std::decay_t<T>>(value_); }
};

/**
 * Turns out that several target types could accept an LLSD param using any of
 * a few different conversions, e.g. LLUUID's constructor can accept LLUUID or
 * std::string. Therefore, the compiler can't decide which LLSD conversion
 * operator to choose, even though to us it seems obvious. But that's okay, we
 * can specialize LLSDParam for such target types, explicitly specifying the
 * desired conversion -- that's part of what LLSDParam is all about. Turns out
 * we have to do that enough to make it worthwhile generalizing. Use a macro
 * because I need to specify one of the asReal, etc., explicit conversion
 * methods as well as a type. If I'm overlooking a clever way to implement
 * that using a template instead, feel free to reimplement.
 */
#define LLSDParam_for(T, AS)                    \
template <>                                     \
class LLSDParam<T>                              \
{                                               \
public:                                         \
    LLSDParam(const LLSD& value):               \
        _value((T)value.AS())                   \
    {}                                          \
                                                \
    operator T() const { return _value; }       \
                                                \
private:                                        \
    T _value;                                   \
}

LLSDParam_for(float,        asReal);
LLSDParam_for(LLUUID,       asUUID);
LLSDParam_for(LLDate,       asDate);
LLSDParam_for(LLURI,        asURI);
LLSDParam_for(LLSD::Binary, asBinary);

/**
 * LLSDParam<const char*> is an example of the kind of conversion you can
 * support with LLSDParam beyond native LLSD conversions. Normally you can't
 * pass an LLSD object to a function accepting const char* -- but you can
 * safely pass an LLSDParam<const char*>(yourLLSD).
 */
template <>
class LLSDParam<const char*>
{
private:
    // The difference here is that we store a std::string rather than a const
    // char*. It's important that the LLSDParam object own the std::string.
    std::string _value;
    // We don't bother storing the incoming LLSD object, but we do have to
    // distinguish whether _value is an empty string because the LLSD object
    // contains an empty string or because it's isUndefined().
    bool _undefined;

public:
    LLSDParam(const LLSD& value):
        _value(value),
        _undefined(value.isUndefined())
    {}

    // The const char* we retrieve is for storage owned by our _value member.
    // That's how we guarantee that the const char* is valid for the lifetime
    // of this LLSDParam object. Constructing your LLSDParam in the argument
    // list should ensure that the LLSDParam object will persist for the
    // duration of the function call.
    operator const char*() const
    {
        if (_undefined)
        {
            // By default, an isUndefined() LLSD object's asString() method
            // will produce an empty string. But for a function accepting
            // const char*, it's often important to be able to pass NULL, and
            // isUndefined() seems like the best way. If you want to pass an
            // empty string, you can still pass LLSD(""). Without this special
            // case, though, no LLSD value could pass NULL.
            return NULL;
        }
        return _value.c_str();
    }
};

namespace llsd
{

/*****************************************************************************
*   BOOST_FOREACH() helpers for LLSD
*****************************************************************************/
/// Usage: BOOST_FOREACH(LLSD item, inArray(someLLSDarray)) { ... }
class inArray
{
public:
    inArray(const LLSD& array):
        _array(array)
    {}

    typedef LLSD::array_const_iterator const_iterator;
    typedef LLSD::array_iterator iterator;

    iterator begin() { return _array.beginArray(); }
    iterator end()   { return _array.endArray(); }
    const_iterator begin() const { return _array.beginArray(); }
    const_iterator end()   const { return _array.endArray(); }

private:
    LLSD _array;
};

/// MapEntry is what you get from dereferencing an LLSD::map_[const_]iterator.
typedef std::map<LLSD::String, LLSD>::value_type MapEntry;

/// Usage: BOOST_FOREACH([const] MapEntry& e, inMap(someLLSDmap)) { ... }
class inMap
{
public:
    inMap(const LLSD& map):
        _map(map)
    {}

    typedef LLSD::map_const_iterator const_iterator;
    typedef LLSD::map_iterator iterator;

    iterator begin() { return _map.beginMap(); }
    iterator end()   { return _map.endMap(); }
    const_iterator begin() const { return _map.beginMap(); }
    const_iterator end()   const { return _map.endMap(); }

private:
    LLSD _map;
};

} // namespace llsd


// Creates a deep clone of an LLSD object.  Maps, Arrays and binary objects 
// are duplicated, atomic primitives (Boolean, Integer, Real, etc) simply
// use a shared reference. 
// Optionally a filter may be specified to control what is duplicated. The 
// map takes the form "keyname/boolean".
// If the value is true the value will be duplicated otherwise it will be skipped 
// when encountered in a map. A key name of "*" can be specified as a wild card
// and will specify the default behavior.  If no wild card is given and the clone
// encounters a name not in the filter, that value will be skipped.
LLSD llsd_clone(LLSD value, LLSD filter = LLSD());

// Creates a shallow copy of a map or array.  If passed any other type of LLSD 
// object it simply returns that value.  See llsd_clone for a description of 
// the filter parameter.
LLSD llsd_shallow(LLSD value, LLSD filter = LLSD());

namespace llsd
{

// llsd namespace aliases
inline
LLSD clone  (LLSD value, LLSD filter=LLSD()) { return llsd_clone  (value, filter); }
inline
LLSD shallow(LLSD value, LLSD filter=LLSD()) { return llsd_shallow(value, filter); }

} // namespace llsd

// Specialization for generating a hash value from an LLSD block.
namespace boost
{
template <>
struct hash<LLSD>
{
    typedef LLSD argument_type;
    typedef std::size_t result_type;
    result_type operator()(argument_type const& s) const 
    {
        result_type seed(0);

        LLSD::Type stype = s.type();
        boost::hash_combine(seed, (S32)stype);

        switch (stype)
        {
        case LLSD::TypeBoolean:
            boost::hash_combine(seed, s.asBoolean());
            break;
        case LLSD::TypeInteger:
            boost::hash_combine(seed, s.asInteger());
            break;
        case LLSD::TypeReal:
            boost::hash_combine(seed, s.asReal());
            break;
        case LLSD::TypeURI:
        case LLSD::TypeString:
            boost::hash_combine(seed, s.asString());
            break;
        case LLSD::TypeUUID:
            boost::hash_combine(seed, s.asUUID());
            break;
        case LLSD::TypeDate:
            boost::hash_combine(seed, s.asDate().secondsSinceEpoch());
            break;
        case LLSD::TypeBinary:
        {
            const LLSD::Binary &b(s.asBinary());
            boost::hash_range(seed, b.begin(), b.end());
            break;
        }
        case LLSD::TypeMap:
        {
            for (LLSD::map_const_iterator itm = s.beginMap(); itm != s.endMap(); ++itm)
            {
                boost::hash_combine(seed, (*itm).first);
                boost::hash_combine(seed, (*itm).second);
            }
            break;
        }
        case LLSD::TypeArray:
            for (LLSD::array_const_iterator ita = s.beginArray(); ita != s.endArray(); ++ita)
            {
                boost::hash_combine(seed, (*ita));
            }
            break;
        case LLSD::TypeUndefined:
        default:
            break;
        }

        return seed;
    }
};
}

namespace LL
{

/*****************************************************************************
*   apply(function, LLSD array)
*****************************************************************************/
// validate incoming LLSD blob, and return an LLSD array suitable to pass to
// apply_impl()
LLSD apply_llsd_fix(size_t arity, const LLSD& args);

// Derived from https://stackoverflow.com/a/20441189
// and https://en.cppreference.com/w/cpp/utility/apply .
// We can't simply make a tuple from the LLSD array and then apply() that
// tuple to the function -- how would make_tuple() deduce the correct
// parameter type for each entry? We must go directly to the target function.
template <typename CALLABLE, std::size_t... I>
auto apply_impl(CALLABLE&& func, const LLSD& array, std::index_sequence<I...>)
{
    // call func(unpacked args), using generic LLSDParam<LLSD> to convert each
    // entry in 'array' to the target parameter type
    return std::forward<CALLABLE>(func)(LLSDParam<LLSD>(array[I])...);
}

// use apply_n<ARITY>(function, LLSD) to call a specific arity of a variadic
// function with (that many) items from the passed LLSD array
template <size_t ARITY, typename CALLABLE>
auto apply_n(CALLABLE&& func, const LLSD& args)
{
    return apply_impl(std::forward<CALLABLE>(func),
                      apply_llsd_fix(ARITY, args),
                      std::make_index_sequence<ARITY>());
}

/**
 * apply(function, LLSD) goes beyond C++17 std::apply(). For this case
 * @a function @emph cannot be variadic: the compiler must know at compile
 * time how many arguments to pass. This isn't Python. (But see apply_n() to
 * pass a specific number of args to a variadic function.)
 */
template <typename CALLABLE>
auto apply(CALLABLE&& func, const LLSD& args)
{
    // infer arity from the definition of func
    constexpr auto arity = function_arity<
        typename std::remove_reference<CALLABLE>::type>::value;
    // now that we have a compile-time arity, apply_n() works
    return apply_n<arity>(std::forward<CALLABLE>(func), args);
}

} // namespace LL

#endif // LL_LLSDUTIL_H