added docs; constified what's possible

Author: iliabylich

.depend

@@ -2,7 +2,8 @@ target/debug/byte_ptr.o: src/byte_ptr.cpp src/byte_ptr.h
 
 target/debug/bytes.o: src/bytes.cpp src/bytes.h src/byte_ptr.h
 
-target/debug/comment.o: src/comment.cpp src/comment.h src/comment_type.h
+target/debug/comment.o: src/comment.cpp src/comment.h src/comment_type.h \
+  src/loc.h src/bytes.h src/byte_ptr.h src/input.h
 
 target/debug/custom_decoder.o: src/custom_decoder.cpp \
   src/custom_decoder.h src/bytes.h src/byte_ptr.h src/helpers.h
@@ -35,7 +36,17 @@ target/debug/low_level.o: src/low_level.cpp src/low_level.h \
   src/node.h
 
 target/debug/magic_comment.o: src/magic_comment.cpp src/magic_comment.h \
-  src/magic_comment_kind.h
+  src/magic_comment_kind.h src/loc.h src/bytes.h src/byte_ptr.h \
+  src/input.h
+
+target/debug/message.o: src/message.cpp src/message.h \
+  src/gen/messages/variant.h src/gen/messages/classes.h \
+  src/gen/messages/../../bytes.h src/byte_ptr.h
+
+target/debug/node.o: src/node.cpp src/node.h src/gen/nodes/variant.h \
+  src/gen/nodes/classes.h src/gen/nodes/../../loc.h src/bytes.h \
+  src/byte_ptr.h src/input.h src/gen/nodes/../../bytes.h \
+  src/gen/nodes/../../node.h
 
 target/debug/parser_options.o: src/parser_options.cpp \
   src/parser_options.h src/custom_decoder.h src/bytes.h src/byte_ptr.h \

README.md

@@ -1,12 +1,12 @@
 # C++ bindings for `lib-ruby-parser`
 
-tldr; You can find examples in `test.c`. Valgrind and ASAN give no errors.
+tldr; You can find examples in `test/test.cpp`. Valgrind and ASAN give no errors.
 
 ## API
 
 All classes/methods are defined in the `lib_ruby_parser` namespace.
 
-1. `ParserResult::from_source(std::string source)`
+1. `ParserResult::from_source(Bytes source, ParserOptions options)`
 
     Parses given input into `ParserResult`, has the following fields:
     ```cpp
@@ -26,7 +26,7 @@ All classes/methods are defined in the `lib_ruby_parser` namespace.
     std::vector<MagicComment> magic_comments;
 
     // Decoded input
-    std::string input;
+    Input input;
     ```
 
 2. `Node::is<T>` where `T` is one of the ~100 node types.
@@ -61,10 +61,12 @@ All classes/methods are defined in the `lib_ruby_parser` namespace.
 
     ```cpp
     ErrorLevel level; // enum with WARNING and ERROR values
-    std::string message;
+    std::unique_ptr<DiagnosticMessage> message;
     std::unique_ptr<Loc> loc;
     ```
 
+    can be rendered either using `render_message()` or `render(const Bytes &)`
+
 7. `Comment` has the following fields:
 
     ```cpp
@@ -77,7 +79,7 @@ All classes/methods are defined in the `lib_ruby_parser` namespace.
     ```cpp
     uint32_t begin;
     uint32_t end;
-    std::string source(const std::string &input);
+    std::string source(Input &input);
     ```
 
     `input` is what you get from `ParserResult::from`. It can be different from your original source if it has magic encoding comment.

lib-ruby-parser-cpp-bindings/build.rs

@@ -60,6 +60,7 @@ fn build_bindings() {
         .whitelist_type("lib_ruby_parser::Node")
         .opaque_type("lib_ruby_parser::Node")
         .blacklist_function("lib_ruby_parser::Node::.*")
+        .blacklist_function("lib_ruby_parser::Node_Node")
         // C++ class Loc
         .whitelist_type("lib_ruby_parser::Loc")
         .opaque_type("lib_ruby_parser::Loc")

lib-ruby-parser-cpp-bindings/gen/cpp/messages/render_cpp.rs

@@ -29,7 +29,7 @@ namespace lib_ruby_parser {{
 
 extern \"C\" {{
 
-BytePtr render_message_diagnostic(Diagnostic *diagnostic)
+BytePtr render_message_diagnostic(const Diagnostic *diagnostic)
 {{
     return std::visit([diagnostic](auto &&message) {{
         using MessageT = std::decay_t<decltype(message)>;
@@ -38,7 +38,7 @@ BytePtr render_message_diagnostic(Diagnostic *diagnostic)
     }}, diagnostic->message->variant);
 }}
 
-BytePtr render_diagnostic(Diagnostic *diagnostic, BytePtr input)
+BytePtr render_diagnostic(const Diagnostic *diagnostic, BytePtr input)
 {{
     return std::visit([diagnostic, input](auto &&message) {{
         using MessageT = std::decay_t<decltype(message)>;

lib-ruby-parser-cpp-bindings/gen/cpp/messages/render_h.rs

@@ -36,8 +36,8 @@ extern \"C\" {{
 
 {render_fns}
 
-BytePtr render_message_diagnostic(Diagnostic *diagnostic);
-BytePtr render_diagnostic(Diagnostic *diagnostic, BytePtr input);
+BytePtr render_message_diagnostic(const Diagnostic *diagnostic);
+BytePtr render_diagnostic(const Diagnostic *diagnostic, BytePtr input);
 
 }}
 

src/byte_ptr.cpp

@@ -32,20 +32,20 @@ namespace lib_ruby_parser
         }
     }
 
-    std::string byte_ptr_to_owned_string(BytePtr byte_ptr)
+    std::string byte_ptr_to_owned_string(const BytePtr &byte_ptr)
     {
         auto result = std::string(byte_ptr.ptr, byte_ptr.size);
         free_byte_ptr(byte_ptr);
         return result;
     }
 
-    std::string byte_ptr_to_utf8_lossy_string(BytePtr byte_ptr)
+    std::string byte_ptr_to_utf8_lossy_string(const BytePtr &byte_ptr)
     {
         auto utf8_byte_ptr = byte_ptr_to_utf8_lossy_byte_ptr(byte_ptr);
         return byte_ptr_to_owned_string(utf8_byte_ptr);
     }
 
-    std::vector<char> byte_ptr_to_vec(BytePtr byte_ptr)
+    std::vector<char> byte_ptr_to_vec(const BytePtr &byte_ptr)
     {
         auto vec = std::vector<char>();
         vec.reserve(byte_ptr.size);

src/byte_ptr.h

@@ -9,23 +9,46 @@ namespace lib_ruby_parser
 {
     extern "C"
     {
+        // Low-level data structure that is used in Rust <-> C++ communications.
+        // Represents a sequence of bytes.
         struct BytePtr
         {
         public:
+            // Pointer to beginning of the byte sequence
             char *ptr;
+
+            // Size of the byte sequence
             uint32_t size;
         };
 
+        // Constructor of the BytePtr
         BytePtr make_byte_ptr(const char *ptr, uint32_t size);
+
+        // Destructor of the BytePtr
         void free_byte_ptr(BytePtr byte_ptr);
 
-        // Defined in Rust
+        // Converts given `byte_ptr` into a UTF-8-valid BytePtr.
+        // It doesn't modify or drop given `byte_ptr`.
         BytePtr byte_ptr_to_utf8_lossy_byte_ptr(BytePtr byte_ptr);
     }
 
-    std::string byte_ptr_to_owned_string(BytePtr byte_ptr);
-    std::string byte_ptr_to_owned_string_lossy(BytePtr byte_ptr);
-    std::vector<char> byte_ptr_to_vec(BytePtr byte_ptr);
+    // Converts given BytePtr to a string.
+    // This function doesn't care about UTF-8-incompatible byte sequences,
+    // and so resulting string can be invalid in UTF-8.
+    // It doesn't modify or drop given `byte_ptr`.
+    std::string byte_ptr_to_owned_string(const BytePtr &byte_ptr);
+
+    // Converts given BytePtr to a string.
+    // All UTF-8-incompatible byte sub-sequences in the given BytePtr
+    // are substituted with a special REPLACEMENT char.
+    // It doesn't modify or drop given `byte_ptr`.
+    std::string byte_ptr_to_owned_string_lossy(const BytePtr &byte_ptr);
+
+    // Converts given BytePtr to a vector of bytes.
+    // This function doesn't care about UTF-8-incompatible byte sequences,
+    // and so resulting vector can be invalid in UTF-8.
+    // It doesn't modify or drop given `byte_ptr`.
+    std::vector<char> byte_ptr_to_vec(const BytePtr &byte_ptr);
 } // namespace lib_ruby_parser
 
 #endif // LIB_RUBY_PARSER_BYTE_PTR_H

src/bytes.h

@@ -8,31 +8,65 @@
 
 namespace lib_ruby_parser
 {
+    // A sequence of Bytes, potentially invalid in UTF-8
     class Bytes
     {
+        // Pointer to beginning of the byte sequence
         char *bytes_;
+
+        // Size of the byte sequence
         uint32_t size_;
+
+        // Indicates that Bytes are "borrowed",
+        // when set to true disables cleanup in destructor.
+        // TODO: remove this hack by making a cleanup on all call sites.
         bool borrowed = false;
 
     public:
+        // Destructor
         ~Bytes();
 
+        // Constructs Bytes from a string (by copying)
         explicit Bytes(std::string s);
+
+        // Constructs Bytes from a given ptr and size (by taking ownership)
         explicit Bytes(char *ptr, uint32_t size);
+
+        // Constructs Bytes from a BytePtr (by taking ownership)
         explicit Bytes(BytePtr byte_ptr);
 
         Bytes(Bytes &&);
         Bytes(const Bytes &) = delete;
         Bytes &operator=(Bytes &&other);
 
+        // Returns a BytePtr that shares data with initial Bytes
+        // Deleting returned BytePtr will cause a segfault.
         BytePtr borrow_ptr() const;
+
+        // Consumes `this` and returns a BytePtr with own data.
         BytePtr into_ptr();
+
+        // Returns size of the byte sequence
         uint32_t size() const;
+
+        // Returns a copy of `this`
         Bytes clone() const;
+
+        // Returns a byte at the given index
         char at(uint32_t idx) const;
+
+        // Returns a sub-sequence at the given range
         Bytes range(uint32_t begin, uint32_t end) const;
+
+        // Returns a string that contains the same byte sequence (by copying)
         std::string to_string() const;
+
+        // Returns a UTF-8 valid string that contains the same byte sequence.
+        // Invalid UTF-8 bytes are replaced with a special REPLACEMENT char.
         std::string to_string_lossy() const;
+
+        // Marks `this` as borrowed, so that destructor will not free the inner pointer.
+        // TODO: remove this hack.
         void mark_borrowed();
 
         bool operator==(const Bytes &other);

src/comment.cpp

@@ -2,12 +2,8 @@
 
 namespace lib_ruby_parser
 {
-    class Loc
-    {
-    public:
-        bool operator==(const Loc &other);
-    };
-
+    Comment::Comment(CommentType kind, std::unique_ptr<Loc> location) : kind(kind),
+                                                                        location(std::move(location)) {}
     bool Comment::operator==(const Comment &other)
     {
         return (kind == other.kind) && (*location == *(other.location));

src/comment.h

@@ -3,22 +3,25 @@
 
 #include <memory>
 #include "comment_type.h"
+#include "loc.h"
 
 namespace lib_ruby_parser
 {
-    class Loc;
-
+    // Representation of the comment in source code
     class Comment
     {
     public:
+        // Kind of the comment
         CommentType kind;
+
+        // Location of the comment
         std::unique_ptr<Loc> location;
 
         Comment() = delete;
         Comment(Comment &&) = default;
         Comment(const Comment &) = delete;
-        explicit Comment(CommentType kind, std::unique_ptr<Loc> location) : kind(kind),
-                                                                            location(std::move(location)){};
+
+        explicit Comment(CommentType kind, std::unique_ptr<Loc> location);
 
         bool operator==(const Comment &other);
         bool operator!=(const Comment &other);