serialize-text.h (3613B)
1 // Copyright (c) 2015 Philip Quinn. 2 // Licensed under the MIT License: 3 // 4 // Permission is hereby granted, free of charge, to any person obtaining a copy 5 // of this software and associated documentation files (the "Software"), to deal 6 // in the Software without restriction, including without limitation the rights 7 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 8 // copies of the Software, and to permit persons to whom the Software is 9 // furnished to do so, subject to the following conditions: 10 // 11 // The above copyright notice and this permission notice shall be included in 12 // all copies or substantial portions of the Software. 13 // 14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 20 // THE SOFTWARE. 21 22 #pragma once 23 24 #include <kj/string.h> 25 #include "dynamic.h" 26 #include "orphan.h" 27 #include "schema.h" 28 29 CAPNP_BEGIN_HEADER 30 31 namespace capnp { 32 33 class TextCodec { 34 // Reads and writes Cap'n Proto objects in a plain text format (as used in the schema 35 // language for constants, and read/written by the 'decode' and 'encode' commands of 36 // the capnp tool). 37 // 38 // This format is useful for debugging or human input, but it is not a robust alternative 39 // to the binary format. Changes to a schema's types or names that are permitted in a 40 // schema's binary evolution will likely break messages stored in this format. 41 // 42 // Note that definitions or references (to constants, other fields, or files) are not 43 // permitted in this format. To evaluate declarations with the full expressiveness of the 44 // schema language, see `capnp::SchemaParser`. 45 // 46 // Requires linking with the capnpc library. 47 48 public: 49 TextCodec(); 50 ~TextCodec() noexcept(true); 51 52 void setPrettyPrint(bool enabled); 53 // If enabled, pads the output of `encode()` with spaces and newlines to make it more 54 // human-readable. 55 56 template <typename T> 57 kj::String encode(T&& value) const; 58 kj::String encode(DynamicValue::Reader value) const; 59 // Encode any Cap'n Proto value. 60 61 template <typename T> 62 Orphan<T> decode(kj::StringPtr input, Orphanage orphanage) const; 63 // Decode a text message into a Cap'n Proto object of type T, allocated in the given 64 // orphanage. Any errors parsing the input or assigning the fields of T are thrown as 65 // exceptions. 66 67 void decode(kj::StringPtr input, DynamicStruct::Builder output) const; 68 // Decode a text message for a struct into the given builder. Any errors parsing the 69 // input or assigning the fields of the output are thrown as exceptions. 70 71 // TODO(someday): expose some control over the error handling? 72 private: 73 Orphan<DynamicValue> decode(kj::StringPtr input, Type type, Orphanage orphanage) const; 74 75 bool prettyPrint; 76 }; 77 78 // ======================================================================================= 79 // inline stuff 80 81 template <typename T> 82 inline kj::String TextCodec::encode(T&& value) const { 83 return encode(DynamicValue::Reader(ReaderFor<FromAny<T>>(kj::fwd<T>(value)))); 84 } 85 86 template <typename T> 87 inline Orphan<T> TextCodec::decode(kj::StringPtr input, Orphanage orphanage) const { 88 return decode(input, Type::from<T>(), orphanage).template releaseAs<T>(); 89 } 90 91 } // namespace capnp 92 93 CAPNP_END_HEADER