feat: add c bindings (#372)

* feat: add C bindings

* some fixes to the C API (#375)

* fix linting errors

* add ada_c.h to release script

---------

Co-authored-by: Daniel Lemire <daniel@lemire.me>

Author: anonrig

.gitignore

@@ -16,6 +16,7 @@ docs/theme
 benchmark_result.json
 
 singleheader/ada.h
+singleheader/ada_c.h
 singleheader/ada.cpp
 singleheader/singleheader.zip
 

CMakeLists.txt

@@ -75,7 +75,7 @@ if(NOT ADA_COVERAGE)
 endif()
 
 install(
-  FILES include/ada.h
+  FILES include/ada.h include/ada_c.h
   DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
   COMPONENT ada_development
 )

README.md

@@ -9,6 +9,8 @@ Ada is a fast and spec-compliant URL parser written in C++.
 Specification for URL parser can be found from the
 [WHATWG](https://url.spec.whatwg.org/#url-parsing) website.
 
+We also include a C wrapper for portability.
+
 The Ada library passes the full range of tests from the specification,
 across a wide range of platforms (e.g., Windows, Linux, macOS). It fully
 supports the relevant [Unicode Technical Standard](https://www.unicode.org/reports/tr46/#ToUnicode).
@@ -122,6 +124,53 @@ url->set_hash("is-this-the-real-life");
 // url->get_hash() will return "#is-this-the-real-life"
 ```
 
+### C wrapper
+
+See the file `include/ada_c.h` for our C interface.
+
+```C
+#include "ada_c.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdbool.h>
+
+static void ada_print(ada_string string) {
+  printf("%.*s\n", (int)string.length, string.data);
+}
+
+int main(int c, char *arg[] ) {
+  ada_url url = ada_parse("https://username:password@www.google.com:8080/"
+      "pathname?query=true#hash-exists");
+  if(!ada_is_valid(url)) { puts("failure"); return EXIT_FAILURE; }
+  ada_print(ada_get_href(url)); // prints https://username:password@host:8080/pathname?query=true#hash-exists
+  ada_print(ada_get_protocol(url)); // prints https:
+  ada_print(ada_get_username(url)); // prints username
+  ada_set_href(url, "https://www.yagiz.co");
+  if(!ada_is_valid(url)) { puts("failure"); return EXIT_FAILURE; }
+  ada_set_hash(url, "new-hash");
+  ada_set_hostname(url, "new-host");
+  ada_set_host(url, "changed-host:9090");
+  ada_set_pathname(url, "new-pathname");
+  ada_set_search(url, "new-search");
+  ada_set_protocol(url, "wss");
+  ada_print(ada_get_href(url)); // will print wss://changed-host:9090/new-pathname?new-search#new-hash
+  ada_free(url);
+  return EXIT_SUCCESS;
+}
+```
+
+When linking against the ada library from C++, be minding that ada requires access to the standard
+C++ library. E.g., you may link with the C++ compiler.
+
+E.g., if you grab our single-header C++ files (`ada.cpp` and `ada.h`), as well as the C header (`ada_c.h`),
+you can often compile a C program (`demo.c`) as follows under Linux/macOS systems:
+
+```
+c++ -c ada.cpp -std=c++17
+cc -c demo.c
+c++ demo.o ada.o -o cdemo
+./cdemo
+```
 
 ### CMake dependency
 
@@ -159,5 +208,4 @@ You may amalgamate all source files into only two files (`ada.h` and `ada.cpp`)
 
 This code is made available under the Apache License 2.0 as well as the MIT license. 
 
-Our tests include third-party code and data. The benchmarking code includes third-party code: 
-it is provided for research purposes only and not part of the library.
+Our tests include third-party code and data. The benchmarking code includes third-party code: it is provided for research purposes only and not part of the library.

include/ada_c.h

@@ -0,0 +1,92 @@
+/**
+ * @file ada_c.h
+ * @brief Includes the C definitions for Ada. This is a C file, not C++.
+ */
+#ifndef ADA_C_H
+#define ADA_C_H
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stddef.h>
+
+// string that is owned by the ada_url instance
+typedef struct {
+  const char* data;
+  size_t length;
+} ada_string;
+
+// string that must be freed by the caller
+typedef struct {
+  const char* data;
+  size_t length;
+} ada_owned_string;
+
+typedef struct {
+  uint32_t protocol_end;
+  uint32_t username_end;
+  uint32_t host_start;
+  uint32_t host_end;
+  uint32_t port;
+  uint32_t pathname_start;
+  uint32_t search_start;
+  uint32_t hash_start;
+} ada_url_components;
+
+typedef void* ada_url;
+
+// input should be a null terminated C string
+// you must call ada_free on the returned pointer
+ada_url ada_parse(const char* string);
+
+// input and base should be a null terminated C strings
+bool ada_can_parse(const char* input, const char* base);
+
+void ada_free(ada_url result);
+
+bool ada_is_valid(ada_url result);
+
+// url_aggregator getters
+// if ada_is_valid(result)) is false, an empty string is returned
+ada_owned_string ada_get_origin(ada_url result);
+void ada_free_owned_string(ada_owned_string owned);
+ada_string ada_get_href(ada_url result);
+ada_string ada_get_username(ada_url result);
+ada_string ada_get_password(ada_url result);
+ada_string ada_get_port(ada_url result);
+ada_string ada_get_hash(ada_url result);
+ada_string ada_get_host(ada_url result);
+ada_string ada_get_hostname(ada_url result);
+ada_string ada_get_pathname(ada_url result);
+ada_string ada_get_search(ada_url result);
+ada_string ada_get_protocol(ada_url result);
+
+// url_aggregator setters
+// if ada_is_valid(result)) is false, the setters have no effect
+// input should be a null terminated C string
+bool ada_set_href(ada_url result, const char* input);
+bool ada_set_host(ada_url result, const char* input);
+bool ada_set_hostname(ada_url result, const char* input);
+bool ada_set_protocol(ada_url result, const char* input);
+bool ada_set_username(ada_url result, const char* input);
+bool ada_set_password(ada_url result, const char* input);
+bool ada_set_port(ada_url result, const char* input);
+bool ada_set_pathname(ada_url result, const char* input);
+void ada_set_search(ada_url result, const char* input);
+void ada_set_hash(ada_url result, const char* input);
+
+// url_aggregator functions
+// if ada_is_valid(result) is false, functions below will return false
+bool ada_has_credentials(ada_url result);
+bool ada_has_empty_hostname(ada_url result);
+bool ada_has_hostname(ada_url result);
+bool ada_has_non_empty_username(ada_url result);
+bool ada_has_non_empty_password(ada_url result);
+bool ada_has_port(ada_url result);
+bool ada_has_password(ada_url result);
+bool ada_has_hash(ada_url result);
+bool ada_has_search(ada_url result);
+
+// returns a pointer to the internal url_aggregator::url_components
+const ada_url_components* ada_get_components(ada_url result);
+
+#endif  // ADA_C_H

singleheader/CMakeLists.txt

@@ -4,7 +4,9 @@
 set(SINGLEHEADER_FILES
   ${CMAKE_CURRENT_BINARY_DIR}/ada.cpp
   ${CMAKE_CURRENT_BINARY_DIR}/ada.h
+  ${CMAKE_CURRENT_BINARY_DIR}/ada_c.h
   ${CMAKE_CURRENT_BINARY_DIR}/demo.cpp
+  ${CMAKE_CURRENT_BINARY_DIR}/demo.c
   ${CMAKE_CURRENT_BINARY_DIR}/README.md
 )
 set_source_files_properties(${SINGLEHEADER_FILES} PROPERTIES GENERATED TRUE)
@@ -52,6 +54,11 @@ if (Python3_Interpreter_FOUND)
     target_link_libraries(demo ada-singleheader-include-source)
 
     add_test(demo demo)
+
+    add_executable(cdemo $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/demo.c>)
+    target_link_libraries(cdemo ada)
+
+    add_test(cdemo cdemo)
   endif()
 else()
   MESSAGE( STATUS "Python not found, we are unable to test amalgamate.py." )

singleheader/README.md

@@ -22,3 +22,15 @@ c++ -std=c++17 -o demo demo.cpp
 ```
 
 You may build and link using CMake (--target demo), because CMake can configure all the necessary flags.
+
+
+### C Demo
+
+You may also build a C executable.
+
+```
+c++ -c ada.cpp -std=c++17
+cc -c demo.c
+c++ demo.o ada.o -o cdemo
+./cdemo
+```

singleheader/amalgamate.py

@@ -128,11 +128,15 @@ def dofile(fid: str, prepath: str, filename: str) -> None:
 # copy the README and DEMOCPP
 if SCRIPTPATH != AMALGAMATE_OUTPUT_PATH:
   shutil.copy2(os.path.join(SCRIPTPATH,"demo.cpp"),AMALGAMATE_OUTPUT_PATH)
+  shutil.copy2(os.path.join(SCRIPTPATH,"demo.c"),AMALGAMATE_OUTPUT_PATH)
   shutil.copy2(os.path.join(SCRIPTPATH,"README.md"),AMALGAMATE_OUTPUT_PATH)
 
+shutil.copy2(os.path.join(AMALGAMATE_INCLUDE_PATH,"ada_c.h"),AMALGAMATE_OUTPUT_PATH)
+
 zf = zipfile.ZipFile(os.path.join(AMALGAMATE_OUTPUT_PATH,'singleheader.zip'), 'w', zipfile.ZIP_DEFLATED)
 zf.write(os.path.join(AMALGAMATE_OUTPUT_PATH,"ada.cpp"), "ada.cpp")
 zf.write(os.path.join(AMALGAMATE_OUTPUT_PATH,"ada.h"), "ada.h")
+zf.write(os.path.join(AMALGAMATE_INCLUDE_PATH,"ada_c.h"), "ada_c.h")
 
 
 print("Done with all files generation.")

singleheader/demo.c

@@ -0,0 +1,39 @@
+#include "ada_c.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdbool.h>
+
+static void ada_print(ada_string string) {
+  printf("%.*s\n", (int)string.length, string.data);
+}
+
+int main(int c, char *arg[]) {
+  ada_url url = ada_parse(
+      "https://username:password@www.google.com:8080/"
+      "pathname?query=true#hash-exists");
+  if (!ada_is_valid(url)) {
+    puts("failure");
+    return EXIT_FAILURE;
+  }
+  ada_print(ada_get_href(
+      url));  // prints
+              // https://username:password@host:8080/pathname?query=true#hash-exists
+  ada_print(ada_get_protocol(url));  // prints https:
+  ada_print(ada_get_username(url));  // prints username
+  ada_set_href(url, "https://www.yagiz.co");
+  if (!ada_is_valid(url)) {
+    puts("failure");
+    return EXIT_FAILURE;
+  }
+  ada_set_hash(url, "new-hash");
+  ada_set_hostname(url, "new-host");
+  ada_set_host(url, "changed-host:9090");
+  ada_set_pathname(url, "new-pathname");
+  ada_set_search(url, "new-search");
+  ada_set_protocol(url, "wss");
+  ada_print(ada_get_href(
+      url));  // will print
+              // wss://changed-host:9090/new-pathname?new-search#new-hash
+  ada_free(url);
+  return EXIT_SUCCESS;
+}

src/ada.cpp

@@ -9,4 +9,5 @@
 #include "url-setters.cpp"
 #include "parser.cpp"
 #include "url_components.cpp"
-#include "url_aggregator.cpp"
+#include "url_aggregator.cpp"
+#include "ada_c.cpp"