From c2e887c080014a2d17e2e715e6cf6b6990014738 Mon Sep 17 00:00:00 2001 From: Kevin Zuniga Cuellar Date: Sun, 18 Aug 2024 21:35:06 -0400 Subject: [PATCH 1/2] add docs for supported langs --- astro.config.mts | 25 +++++ astro/content/docs/cli/performance.md | 4 +- astro/content/docs/clients/cpp.mdx | 148 ++++++++++++++++++++++++++ astro/content/docs/clients/go.mdx | 6 ++ astro/content/docs/clients/luajit.md | 65 +++++++++++ astro/content/docs/clients/python.mdx | 89 ++++++++++++++++ astro/content/docs/clients/rust.md | 45 ++++++++ astro/content/docs/introduction.md | 1 - 8 files changed, 380 insertions(+), 3 deletions(-) create mode 100644 astro/content/docs/clients/cpp.mdx create mode 100644 astro/content/docs/clients/go.mdx create mode 100644 astro/content/docs/clients/luajit.md create mode 100644 astro/content/docs/clients/python.mdx create mode 100644 astro/content/docs/clients/rust.md diff --git a/astro.config.mts b/astro.config.mts index 218f622..4e5539a 100644 --- a/astro.config.mts +++ b/astro.config.mts @@ -37,6 +37,31 @@ export default defineConfig({ }, ], }, + { + label: 'Supported Languages', + items: [ + { + label: 'C++ client', + slug: 'clients/cpp', + }, + { + label: 'Rust client', + slug: 'clients/rust', + }, + { + label: 'Python client', + slug: 'clients/python', + }, + { + label: 'Go client', + slug: 'clients/go', + }, + { + label: 'LuaJIT client', + slug: 'clients/luajit', + }, + ], + }, ], }), ], diff --git a/astro/content/docs/cli/performance.md b/astro/content/docs/cli/performance.md index ee469d1..502d862 100644 --- a/astro/content/docs/cli/performance.md +++ b/astro/content/docs/cli/performance.md @@ -12,7 +12,7 @@ compare against [trurl](https://github.com/curl/trurl) version 0.6 (libcurl/7.87
-**wikipedia_100k dataset**, adaparse can parse URLs **three times faster than trurl**. +wikipedia_100k dataset, adaparse can parse URLs three times faster than trurl. ```bash @@ -28,7 +28,7 @@ compare against [trurl](https://github.com/curl/trurl) version 0.6 (libcurl/7.87
-Using **top100 dataset**, adaparse is **twice as fast as the trurl**. +Using top100 dataset, adaparse is twice as fast as the trurl. ```bash diff --git a/astro/content/docs/clients/cpp.mdx b/astro/content/docs/clients/cpp.mdx new file mode 100644 index 0000000..76cae81 --- /dev/null +++ b/astro/content/docs/clients/cpp.mdx @@ -0,0 +1,148 @@ +--- +title: C++ +description: How to install and use Ada in a C++ project +--- +import { Steps } from '@astrojs/starlight/components'; + +More information about the API can be found from [C++ API Reference](https://cpp-api.ada-url.com). + +## Requirements + +The project is self-contained and has no dependency. +A recent C++ compiler supporting C++17. We test GCC 9 or better, LLVM 10 or better and Microsoft Visual Studio 2022. + +## Building + +Ada uses **cmake** as a build system. It's recommended to have cmake available in your system. +Run the following commands to compile and build Ada locally. + + + + 1. **Prepare** + + ```bash + cmake -B build + ``` + + 2. **Build** + + ```bash + cmake --build build + ``` + + + +## Usage + +Use the following code to run and test Ada. + +```cpp +#include "ada.h" +#include + +int main(int , char *[]) { + ada::result url = ada::parse("https://www.google.com"); + url->set_protocol("http"); + std::cout << url->get_protocol() << std::endl; + std::cout << url->get_host() << std::endl; + return EXIT_SUCCESS; +} +``` + +### Parsing & Validation + +- Parse and validate a URL from an ASCII or UTF-8 string + +```cpp +ada::result url = + ada::parse("https://www.google.com"); +if (url) { /* URL is valid */ } +``` + +After calling **parse** function, you *must* check that the result is valid before +accessing it when you are not sure that it will succeed. The following +code is unsafe: + +```cpp +ada::result url = + ada::parse("some bad url"); +url->get_href(); +``` + +You should do... + +```cpp +ada::result url = + ada::parse("some bad url"); +if(url) { + // next line is now safe: + url->get_href(); +} else { + // report a parsing failure +} +``` + +For simplicity, in the examples below, we skip the check because +we know that parsing succeeds. + + +## Examples + +### Credentials + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_username("username"); +url->set_password("password"); +// ada->get_href() will return "https://username:password@www.google.com/" +``` + +### Protocol + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_protocol("wss"); +// url->get_protocol() will return "wss:" +// url->get_href() will return "wss://www.google.com/" +``` + +### Host + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_host("github.com"); +// url->get_host() will return "github.com" +// you can use `url.set_hostname` depending on your usage. +``` + +### Port + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_port("8080"); +// url->get_port() will return "8080" +``` + +### Pathname + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_pathname("/my-super-long-path") +// url->get_pathname() will return "/my-super-long-path" +``` + +### Search/Query + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_search("target=self"); +// url->get_search() will return "?target=self" +``` + +### Hash/Fragment + +```cpp +auto url = ada::parse("https://www.google.com"); +url->set_hash("is-this-the-real-life"); +// url->get_hash() will return "#is-this-the-real-life" +``` \ No newline at end of file diff --git a/astro/content/docs/clients/go.mdx b/astro/content/docs/clients/go.mdx new file mode 100644 index 0000000..6309aa6 --- /dev/null +++ b/astro/content/docs/clients/go.mdx @@ -0,0 +1,6 @@ +--- +title: Go +description: How to install and use Ada in a Go project +--- + +Ada has a Go client available on [Github](https://github.com/ada-url/goada). \ No newline at end of file diff --git a/astro/content/docs/clients/luajit.md b/astro/content/docs/clients/luajit.md new file mode 100644 index 0000000..9b5c7a1 --- /dev/null +++ b/astro/content/docs/clients/luajit.md @@ -0,0 +1,65 @@ +--- +title: LuaJIT +description: How to install and use Ada in a LuaJIT or OpenResty project +--- + +Ada has a LuaJIT / OpenResty client available on [Github][source-code], +and also on [luarocks.org][rock] and [https://opm.openresty.org/][opm]. + +## Installation + +### Using LuaRocks + +```bash +luarocks install lua-resty-ada +``` + +LuaRocks repository for `lua-resty-ada` is located at +[luarocks.org/modules/bungle/lua-resty-ada](https://luarocks.org/modules/bungle/lua-resty-session). + +### Using OpenResty Package Manager + +```bash +opm get bungle/lua-resty-ada +``` + +OPM repository for `lua-resty-ada` is located at +[opm.openresty.org/package/bungle/lua-resty-ada](https://opm.openresty.org/package/bungle/lua-resty-ada/). + +## Usage + +Please consult the [API documentation][documentation] for a more detailed information. + +### URL class + +The `resty.ada` can parse URL and return an instance of URL: + +```lua +local ada_url = require("resty.ada") +local url = ada_url.parse("https://example.org/path/file.txt") +local protocol = url:get_protocol() +url:free() -- explicit free (garbage collector would do it implicitly) +print(protocol) -- "https:" +``` + +### Static functions + +The library can also be used without creating instances: + +```lua +local ada_url = require("resty.ada") +local protocol = ada_url.get_protocol("https://example.org/path/file.txt") +print(protocol) -- "https:" +``` + +## Resources + +- [Source code][source-code] +- [LuaRocks][rock] +- [OpenResty Package Manager][opm] +- [Documentation][documentation] + +[rock]: https://luarocks.org/modules/bungle/lua-resty-ada +[opm]: https://opm.openresty.org/package/bungle/lua-resty-ada/ +[documentation]: https://bungle.github.io/lua-resty-ada/ +[source-code]: https://github.com/bungle/lua-resty-ada \ No newline at end of file diff --git a/astro/content/docs/clients/python.mdx b/astro/content/docs/clients/python.mdx new file mode 100644 index 0000000..0893fba --- /dev/null +++ b/astro/content/docs/clients/python.mdx @@ -0,0 +1,89 @@ +--- +title: Python +description: How to install and use Ada in a Python project +--- +import { Steps } from '@astrojs/starlight/components'; + +Ada has a Python client available on [Github](https://github.com/ada-url/ada-python). +For more details on the `ada_url` API, see the documentation at [Read the Docs](https://ada-url.readthedocs.io/en/latest/). + +## Installation + +### Installing pre-built binary wheels + +The easiest way to get started is to install `ada-url` from [PyPI](https://pypi.org/project/ada-url/). + +From within your virtual environment, run: + +```bash +python3 -m pip install ada-url +``` + +### Installing from source + +The `Makefile` in the [project root](https://github.com/ada-url/ada-python) will build a package for installation on your own machine. + +From within your virtual environment, run: + + + +1. **Prepare** + + ```bash + make requirements package + ``` + +2. **Install** + + ```bash + python3 -m install -e . + ``` + + + +## Usage + +### URL class + +The `ada_url` package defines a `URL` class that can parse URLs: + +```python3 +>>> import ada_url +>>> urlobj = ada_url.URL('https://example.org/path/file.txt') +>>> urlobj.protocol +'https:' +>>> urlobj.pathname +'/path/file.txt' +``` + +### High-level functions + +It also exposes some higher level functions for analyzing and manipulating URLs: + +#### parse_url + +```python3 +>>> import ada_url +>>> ada_url.parse_url('https://user:pass@example.org:80/api?q=1#2') +{ + 'href': 'https://user:pass@example.org:80/api?q=1#2', + 'username': 'user', + 'password': 'pass', + 'protocol': 'https:', + 'host': 'example.org:80', + 'port': '80', + 'hostname': 'example.org', + 'pathname': '/api', + 'search': '?q=1', + 'hash': '#2' +} +``` + +#### join_url + +```python3 +>>> import ada_url +>>> ada_url.join_url( +'https://example.org/dir/child.txt', '../parent.txt' +) +``` \ No newline at end of file diff --git a/astro/content/docs/clients/rust.md b/astro/content/docs/clients/rust.md new file mode 100644 index 0000000..1a649ff --- /dev/null +++ b/astro/content/docs/clients/rust.md @@ -0,0 +1,45 @@ +--- +title: Rust +description: How to install and use Ada in a Rust project +--- + +Ada has a Rust client available on [Github][source-code] and +also on [crates.io][crate]. + +## Installation + +Add the following as a dependency to your project (`Cargo.toml`): + +```toml +[dependencies] +ada-url = "1" +``` + +## Usage + +Here is an example illustrating a common usage: + +```rust +use ada_url::Url; +fn main() { + let mut u = Url::parse("http://www.google:8080/love#drug", None) + .expect("bad url"); + println!("port: {:?}", u.port()); + println!("hash: {:?}", u.hash()); + println!("pathname: {:?}", u.pathname()); + println!("href: {:?}", u.href()); + u.set_port("9999"); + println!("href: {:?}", u.href()); +} +``` + +## Resources + +- [Source code][source-code] +- [Crate - crates.io][crate] +- [Documentation - docs.rs][documentation] + + +[crate]: https://crates.io/crates/ada-url +[documentation]: https://docs.rs/ada-url/1.0.2/ada_url/ +[source-code]: https://github.com/ada-url/rust \ No newline at end of file diff --git a/astro/content/docs/introduction.md b/astro/content/docs/introduction.md index 83d073e..3ade617 100644 --- a/astro/content/docs/introduction.md +++ b/astro/content/docs/introduction.md @@ -20,7 +20,6 @@ The Ada library passes the full range of tests from the specification, across a The term WHATWG stands for **Web Hypertext Application Technology Working Group**. It is a community-driven organization that focuses on developing and maintaining web standards. - The WHATWG was initially formed in response to the divergence between the World Wide Web Consortium (W3C) and the browser vendors at the time, who felt that the W3C process was too slow to address the evolving needs of web developers.
From 642331e7844d6e8baa73737e2747274594e79e12 Mon Sep 17 00:00:00 2001 From: Kevin Zuniga Cuellar Date: Sun, 18 Aug 2024 21:42:03 -0400 Subject: [PATCH 2/2] fix syntax highlight and remove unused bullet point --- astro/content/docs/clients/cpp.mdx | 3 +-- astro/content/docs/clients/python.mdx | 6 +++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/astro/content/docs/clients/cpp.mdx b/astro/content/docs/clients/cpp.mdx index 76cae81..9557797 100644 --- a/astro/content/docs/clients/cpp.mdx +++ b/astro/content/docs/clients/cpp.mdx @@ -51,7 +51,7 @@ int main(int , char *[]) { ### Parsing & Validation -- Parse and validate a URL from an ASCII or UTF-8 string +Parse and validate a URL from an ASCII or UTF-8 string ```cpp ada::result url = @@ -85,7 +85,6 @@ if(url) { For simplicity, in the examples below, we skip the check because we know that parsing succeeds. - ## Examples ### Credentials diff --git a/astro/content/docs/clients/python.mdx b/astro/content/docs/clients/python.mdx index 0893fba..9bd5179 100644 --- a/astro/content/docs/clients/python.mdx +++ b/astro/content/docs/clients/python.mdx @@ -47,7 +47,7 @@ From within your virtual environment, run: The `ada_url` package defines a `URL` class that can parse URLs: -```python3 +```py >>> import ada_url >>> urlobj = ada_url.URL('https://example.org/path/file.txt') >>> urlobj.protocol @@ -62,7 +62,7 @@ It also exposes some higher level functions for analyzing and manipulating URLs: #### parse_url -```python3 +```py >>> import ada_url >>> ada_url.parse_url('https://user:pass@example.org:80/api?q=1#2') { @@ -81,7 +81,7 @@ It also exposes some higher level functions for analyzing and manipulating URLs: #### join_url -```python3 +```py >>> import ada_url >>> ada_url.join_url( 'https://example.org/dir/child.txt', '../parent.txt'