android: shared_llvm.mk: add libLLVMOrcJIT to llvm_device_static_libraries

[android-x86/external-llvm.git] / docs / YamlIO.rst

diff --git a/docs/YamlIO.rst b/docs/YamlIO.rst
index ab8b19a..ac4f8d1 100644 (file)
--- a/docs/YamlIO.rst
+++ b/docs/YamlIO.rst
@@ -456,17 +456,68 @@ looks like:
 
     template <>
     struct ScalarTraits<MyCustomType> {
-      static void output(const T &value, void*, llvm::raw_ostream &out) {
+      static void output(const MyCustomType &value, void*,
+                         llvm::raw_ostream &out) {
         out << value;  // do custom formatting here
       }
-      static StringRef input(StringRef scalar, void*, T &value) {
+      static StringRef input(StringRef scalar, void*, MyCustomType &value) {
         // do custom parsing here.  Return the empty string on success,
         // or an error message on failure.
         return StringRef();
       }
       // Determine if this scalar needs quotes.
-      static bool mustQuote(StringRef) { return true; }
+      static QuotingType mustQuote(StringRef) { return QuotingType::Single; }
     };
+
+Block Scalars
+-------------
+
+YAML block scalars are string literals that are represented in YAML using the
+literal block notation, just like the example shown below:
+
+.. code-block:: yaml
+
+    text: |
+      First line
+      Second line
+
+The YAML I/O library provides support for translating between YAML block scalars
+and specific C++ types by allowing you to specialize BlockScalarTraits<> on
+your data type. The library doesn't provide any built-in support for block
+scalar I/O for types like std::string and llvm::StringRef as they are already
+supported by YAML I/O and use the ordinary scalar notation by default.
+
+BlockScalarTraits specializations are very similar to the
+ScalarTraits specialization - YAML I/O will provide the native type and your
+specialization must create a temporary llvm::StringRef when writing, and
+it will also provide an llvm::StringRef that has the value of that block scalar
+and your specialization must convert that to your native data type when reading.
+An example of a custom type with an appropriate specialization of
+BlockScalarTraits is shown below:
+
+.. code-block:: c++
+
+    using llvm::yaml::BlockScalarTraits;
+    using llvm::yaml::IO;
+
+    struct MyStringType {
+      std::string Str;
+    };
+
+    template <>
+    struct BlockScalarTraits<MyStringType> {
+      static void output(const MyStringType &Value, void *Ctxt,
+                         llvm::raw_ostream &OS) {
+        OS << Value.Str;
+      }
+
+      static StringRef input(StringRef Scalar, void *Ctxt,
+                             MyStringType &Value) {
+        Value.Str = Scalar.str();
+        return StringRef();
+      }
+    };
+
     
 
 Mappings
@@ -680,7 +731,7 @@ it is parsed. This allows dynamic types of nodes.  But the YAML I/O model uses
 static typing, so there are limits to how you can use tags with the YAML I/O
 model. Recently, we added support to YAML I/O for checking/setting the optional 
 tag on a map. Using this functionality it is even possbile to support different 
-mappings, as long as they are convertable.  
+mappings, as long as they are convertible.  
 
 To check a tag, inside your mapping() method you can use io.mapTag() to specify
 what the tag should be.  This will also add that tag when writing yaml.
@@ -748,6 +799,8 @@ add "static const bool flow = true;". For instance:
       static const bool flow = true;
     }
 
+Flow mappings are subject to line wrapping according to the Output object
+configuration.
 
 Sequence
 ========
@@ -795,6 +848,8 @@ With the above, if you used MyList as the data type in your native data
 structures, then when converted to YAML, a flow sequence of integers 
 will be used (e.g. [ 10, -3, 4 ]).
 
+Flow sequences are subject to line wrapping according to the Output object
+configuration.
 
 Utility Macros
 --------------
@@ -858,14 +913,14 @@ Output
 
 The llvm::yaml::Output class is used to generate a YAML document from your 
 in-memory data structures, using traits defined on your data types.  
-To instantiate an Output object you need an llvm::raw_ostream, and optionally 
-a context pointer:
+To instantiate an Output object you need an llvm::raw_ostream, an optional 
+context pointer and an optional wrapping column:
 
 .. code-block:: c++
 
       class Output : public IO {
       public:
-        Output(llvm::raw_ostream &, void *context=NULL);
+        Output(llvm::raw_ostream &, void *context = NULL, int WrapColumn = 70);
     
 Once you have an Output object, you can use the C++ stream operator on it
 to write your native data as YAML. One thing to recall is that a YAML file
@@ -874,6 +929,10 @@ streaming as YAML is a mapping, scalar, or sequence, then Output assumes you
 are generating one document and wraps the mapping output 
 with  "``---``" and trailing "``...``".  
 
+The WrapColumn parameter will cause the flow mappings and sequences to
+line-wrap when they go over the supplied column. Pass 0 to completely
+suppress the wrapping.
+
 .. code-block:: c++
    
     using llvm::yaml::Output;
@@ -961,7 +1020,7 @@ object.  For example:
      // Reading multiple documents in one file
      using llvm::yaml::Input;
 
-     LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(std::vector<MyDocType>)
+     LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(MyDocType)
      
      Input yin(mb.getBuffer());