{"id":13339947,"url":"https://github.com/Tinkoff/uri-template","last_synced_at":"2025-03-11T15:31:58.815Z","repository":{"id":43782046,"uuid":"346658200","full_name":"Tinkoff/uri-template","owner":"Tinkoff","description":"URI Templates expansion and reverse-matching for C++","archived":true,"fork":false,"pushed_at":"2022-11-29T08:46:34.000Z","size":700,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2024-10-24T02:35:42.172Z","etag":null,"topics":["cpp","cpp-library","cpp17","rfc-6570","uri-template","url-template"],"latest_commit_sha":null,"homepage":"https://tinkoff.github.io/uri-template/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tinkoff.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2021-03-11T10:08:34.000Z","updated_at":"2023-09-08T18:19:38.000Z","dependencies_parsed_at":"2023-01-22T00:49:58.561Z","dependency_job_id":null,"html_url":"https://github.com/Tinkoff/uri-template","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinkoff%2Furi-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinkoff%2Furi-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinkoff%2Furi-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinkoff%2Furi-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tinkoff","download_url":"https://codeload.github.com/Tinkoff/uri-template/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243059723,"owners_count":20229623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","cpp-library","cpp17","rfc-6570","uri-template","url-template"],"created_at":"2024-07-29T19:21:23.019Z","updated_at":"2025-03-11T15:31:55.859Z","avatar_url":"https://github.com/Tinkoff.png","language":"C++","readme":"# URI-template\n\n[![Language C++](https://img.shields.io/badge/language-c++-blue.svg?logo=c%2B%2B)](https://isocpp.org)\n[![Github releases](https://img.shields.io/github/release/TinkoffCreditSystems/uri-template.svg)](https://github.com/TinkoffCreditSystems/uri-template/releases)\n[![Coverage Status](https://codecov.io/gh/Tinkoff/uri-template/branch/develop/graph/badge.svg?token=EV4QTP0R59)](https://codecov.io/gh/Tinkoff/uri-template)\n[![Conan Package](https://img.shields.io/badge/Conan-package-blueviolet)](https://conan.io/center/tcsbank-uri-template)\n[![License](https://img.shields.io/github/license/TinkoffCreditSystems/uri-template.svg)](./LICENSE)\n\nThis library implements [URI Template](https://tools.ietf.org/html/rfc6570) with full support up to Level 4 providing **expansion** and **match** capabilities. It requires c++17 compiler support and has no dependencies.\n\n## What?\n\nURI templates are a convenient way to describe a range of possible URI by making some parts of it variable. For example, a variety of resources:\n* `http://example.com/~fred/`\n* `http://example.com/~mark/`\n* `http://example.com/~admin/`\n* `http://example.com/~guest/`\n* `http://example.com/~elephant/`\n\nCould be described by simple template – `http://example.com/~{username}/`.\n\nOr, resources:\n* `http://example.com/search?q=cat\u0026lang=en`\n* `http://example.com/search?q=chien\u0026lang=fr`\n\nCould be described by – `http://example.com/search{?q,lang}`.\n\nA template is transformed into a URI by replacing each delimited expression with its value as defined by expansion rules and the values of variables.\n\nURI Templates can also be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variables. It only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, otherwise, some ambiguity is present. For example, a template `http://example.com/{foo}{bar}` matches `http://example.com/foobar`, but is is impossible to distinguish if:\n* `foo='foobar'` and `bar` is undefined; or\n* `foo` is undefined and `bar='foobar'`\n\nAlthough, if you only interested if a template matches some URI with at least one possible set of values and does not care about values itself, then it is ok.\n\nThere is more to it. For better understanding please refer to [RFC 6570](https://tools.ietf.org/html/rfc6570).\n\n## Quickstart\n\nURI Templates are presented as instances of `URI::Template::Template` class. It is basically a vector of parts, which can be either `URI::Template::Literal` or `URI::Template::Expression`. To make one you can use `URI::Template::ParseTemplate()` function or construct it by hand using:\n* `URI::Template::Operator`\n* `URI::Template::Variable`\n* `URI::Template::Modifier`\n\nclasses.\n\nFrom there you can provide values for template variables with `URI::Template::VarValue` objects and expand it, or use `URI::Template::MatchURI()` to test if some URI matches a template, i.e. if it can be expanded from a template with correct values provided.\n\n### Example\n\nHere is basic example how to parse, match and expand URI template:\n```c++\n#include \u003curi-template/uri-template.h\u003e\n#include \u003ciostream\u003e\n\nint main() {\n    const std::string uri = \"http://example.com/search?q=cat\u0026lang=en\";\n    // Parse the template\n    const URI::Template::Template uri_template = URI::Template::ParseTemplate(\"http://example.com/search{?q,lang}\");\n\n    // Match it to the URI\n    // \u0026matched_values can be nullptr if you don't care about values.\n    std::unordered_map\u003cstd::string, URI::Template::VarValue\u003e matched_values;\n    bool matched = URI::Template::MatchURI(uri_template, uri, \u0026matched_values);\n\n    // Print results\n    std::cout \u003c\u003c std::boolalpha;\n    std::cout \u003c\u003c \"Template matched: \" \u003c\u003c matched \u003c\u003c std::endl;\n    for (const auto\u0026 [name, value] : matched_values) {\n        std::cout \u003c\u003c name \u003c\u003c \"=\" \u003c\u003c value \u003c\u003c std::endl;\n    }\n\n    // Expand\n    const std::string expanded_uri = URI::Template::ExpandTemplate(uri_template, matched_values);\n    std::cout \u003c\u003c \"Template expanded: \" \u003c\u003c expanded_uri \u003c\u003c std::endl;\n}\n```\n\n```bash\ng++ -std=c++17 example.cpp -luri-template\n```\nOutput:\n```\nTemplate matched: true\nlang=en\nq=cat\nTemplate expanded: http://example.com/search?q=cat\u0026lang=en\n```\n\n## Detailed description\n\nFor full API reference look here – https://tinkoff.github.io/uri-template/\n\n## How to use in your project\n\nGenerally, to use this library you need to tell your compiler where to lookup for its' headers and library. For gcc/clang it can be done via `-I` and `-l` flags. Any particular situation depends on what you are using to build your project.\n\n### Use installed\n\nEasiest way is to install this library onto your system. To do so, execute these commands from `uri-template` folder (sudo may be required):\n\n```bash\ncmake -H. -Bbuild -DUCONFIG_BUILD_TESTING=OFF -DUCONFIG_BUILD_DOCS=OFF\ncmake --build ./build --target install\n```\n\nThis will put uri-template headers into system default folder. From there you should be able to use it like any other library (`#include \u003curi-template/uri-template.h\u003e` and so on).\n\n### Manually\n\nIf you [have installed](#use-installed) uri-template then you only need to link with it via `-luri-template`. If you don't want to install, pass an `-I` flag with path to uri-template include folder and `-l` with path to library binary. For example, if you cloned it into `~/uri-template/` and build it there, then use `-I~/uri-template/include -l~/uri-template/build/liburi-template.a` when calling gcc or clang.\n\n### Cmake\n\nIf you [have installed](#use-installed) uri-template then use `find_package(uri-template REQUIRED)` and `target_link_libraries(\u003cyour target\u003e uri-template::uri-template)`. Alternatively, you can use cmake's [`add_subdirectory`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html), [`ExternalProject`](https://cmake.org/cmake/help/latest/module/ExternalProject.html), [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html) to bring it and include in configure stage of you project.\n\nAlso, this may be helpful - https://cliutils.gitlab.io/modern-cmake/\n\n## How to build\n\nThis library supposed to be somewhat multi-platform, however, it was tested and mainly used on ubuntu and macOS. \u003c/br\u003e\nPrefer [out-of-source](https://gitlab.kitware.com/cmake/community/-/wikis/FAQ#what-is-an-out-of-source-build) building:\n\n```bash\ncmake -H. -Bbuild\ncmake --build ./build\n```\n\nTo install (sudo may be required):\n```bash\ncmake -H. -Bbuild -DUCONFIG_BUILD_TESTING=OFF -DUCONFIG_BUILD_DOCS=OFF\ncmake --build ./build --target install\n```\n\nOr test:\n```bash\ncmake -H. -Bbuild -DUCONFIG_BUILD_TESTING=ON\ncmake --build ./build\ncmake -E chdir ./build ctest --output-on-failure\n```\n\n*All these commands assume you are in uconfig root folder*\n\n### Cmake options\n\n* **CMAKE_BUILD_TYPE** – [build type](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). `RelWithDebInfo` by default.\n* **BUILD_SHARED_LIBS** – [build shared or static library](https://cmake.org/cmake/help/v3.0/variable/BUILD_SHARED_LIBS.html). `OFF` by default.\n* **UCONFIG_BUILD_TESTING** – build included unit-tests. `OFF` by default.\n* **UCONFIG_BUILD_DOCS** – build html (sphinx) reference docs. `OFF` by default.\n\n## License\n\nDeveloped at **Tinkoff.ru** in 2021.\\\nDistibuted under **Apache License 2.0** [LICENSE](./LICENSE). You may also obtain this license at https://www.apache.org/licenses/LICENSE-2.0.\n\n## Contacts\n\nAuthor - i.s.vovk@tinkoff.ru\\\nCurrent maintainer - i.s.vovk@tinkoff.ru\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTinkoff%2Furi-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTinkoff%2Furi-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTinkoff%2Furi-template/lists"}