Awesome
<!-- markdownlint-disable MD001 MD013 MD034 MD033 MD051 -->giturlparser.lua
<p align="center"> <a href="https://luarocks.org/modules/linrongbin16/giturlparser"><img alt="luarocks" src="https://custom-icon-badges.demolab.com/luarocks/v/linrongbin16/giturlparser?label=LuaRocks&labelColor=2C2D72&logo=tag&logoColor=fff&color=blue" /></a> <a href="https://github.com/linrongbin16/giturlparser.lua/actions/workflows/ci.yml"><img alt="ci.yml" src="https://img.shields.io/github/actions/workflow/status/linrongbin16/giturlparser.lua/ci.yml?label=GitHub%20CI&labelColor=181717&logo=github&logoColor=fff" /></a> <a href="https://app.codecov.io/github/linrongbin16/giturlparser.lua"><img alt="codecov" src="https://img.shields.io/codecov/c/github/linrongbin16/giturlparser.lua?logo=codecov&logoColor=F01F7A&label=Codecov" /></a> </p> <p align="center"> Git url parsing library for lua, e.g. the output of <code>git remote get-url origin</code>. </p>Table of Contents
Requirements
- Lua >= 5.1, luajit >= 2.0.0.
Features
- Single file & zero dependency.
- Full Git Protocols support (see Patterns).
Install
luarocks install giturlparser
Patterns
There are (mainly) three types of git url pattern:
[!NOTE]
They are (just help to explain) written with a regex-like syntax:
- The
{}
contains parsed components returned fromgiturlparser.GitUrlInfo
.- The
[]
contains optional (0 or 1) component.- The
[]*
contains 0 or more component.- The
[]+
contains 1 or more component.- The
|
inside[]
is or operator.
Full Protocols
{protocol}://[[{user}[:{password}]@]{host}[:{port}]]/[{org}/]*{repo}
For example:
http://host.xyz/repo.git
https://git@127.0.0.1:12345/repo.git
ssh://username:password@host.xyz:port/path/to/the/repo.git
ssh://host.xyz:port/path/to/the/repo.git
file:///repo.git
file://user:passwd@host.xyz:port/path/to/the/repo.git
file://~/home/to/the/repo.git
SSH Omitted Protocols
[{user}[:{password}]@]{host}:[{org}/]*{repo}
For example:
git@host.xyz:repo.git
user:passwd@host.xyz:path/to/the/repo.git
Local File System
[[.|..|~]/][{org}/]*{repo}
For example:
repo.git
./repo.git
../path/to/the/repo.git
~/home/to/the/repo.git
/usr/home/to/the/repo.git
API
Types
giturlparser.GitUrlPos
The string position of a component.
--- @alias giturlparser.GitUrlPos {start_pos:integer?,end_pos:integer?}
It contains below fields:
start_pos
: Start string index.end_pos
: End string index.
giturlparser.GitUrlInfo
Parsed information.
--- @alias giturlparser.GitUrlInfo {protocol:string?,protocol_pos:giturlparser.GitUrlPos?,user:string?,user_pos:giturlparser.GitUrlPos?,password:string?,password_pos:giturlparser.GitUrlPos?,host:string?,host_pos:giturlparser.GitUrlPos?,org:string?,org_pos:giturlparser.GitUrlPos?,repo:string,repo_pos:giturlparser.GitUrlPos,path:string,path_pos:giturlparser.GitUrlPos}
It contains below fields:
protocol
/protocol_pos
: Protocol, e.g.http
inhttp://github.com
, and its position.user
/user_pos
: User name, e.g.username
inssh://username@githost.com
, and its position.password
/password_pos
: Password, e.g.password
inssh://username:password@githost.com
, and its position.host
/host_pos
: Host name, e.g.githost.com
inssh://githost.com
, and its position.port
/port_pos
: Port, e.g.12345
inssh://127.0.0.1:12345/org/repo.git
, and its position.path
/path_pos
: All the left parts after host name (and optional port), e.g./linrongbin16/giturlparser.lua.git
inhttps://github.com/linrongbin16/giturlparser.lua.git
, and its position.
There're 2 more sugar fields:
repo
/repo_pos
: Repository (the last part after the last slash/
), e.g.giturlparser.lua.git
inhttps://github.com/linrongbin16/giturlparser.lua.git
, and its position.org
/org_pos
: , Organization (the parts after host name (and optional port), before the last slash/
), e.g.linrongbin16
inhttps://github.com/linrongbin16/giturlparser.lua.git
, and its position.
[!NOTE]
- The
{path}
component is (almost) equivalent to/{org}/{repo}
.- The
{org}
and{repo}
component are trimmed from around slashes if there's any.- If there's only 1 slash, the
org
component is omitted.
Functions
parse
Parse url
and returns the parsed info (lua table).
--- @param url string
--- @return giturlparser.GitUrlInfo?, string?
M.parse = function(url)
Parameters:
url
: Git url, e.g. the output ofgit remote get-url origin
.
Returns:
- Returns
giturlparser.GitUrlInfo
andnil
if success. - Returns
nil
and error messagestring
if failed.
References
Development
To develop the project and make PR, please setup with:
To run unit tests, please install below dependencies:
Contribute
Please open issue/PR for anything about giturlparser.lua.
Like giturlparser.lua? Consider