browser-ruler/README.md

57 lines
2.1 KiB
Markdown

# browser-ruler
A small program that allows writing rules to determine which browser to lauch based on the URL
Tested on an Ubuntu and Pop_OS! system but should work on anything that supports xdg
## Configuration
When launched, configuration will be read first from the `-config` option, if provided, then from `$XDG_CONFIG_HOME/browser-ruler/config.hcl`, if found, and then from `$HOME/.browser-ruler.hcl`. If none of these are found, it will panic and ask you to provide it some configuration.
Config files are in the HCL config language with a schema defined below.
```hcl
default_browser_cmd = list(string)
rule [label] {
browser_cmd = list(string)
match = string
}
```
To see some detailed samples, check out `sample-config.hcl`.
### Writing a MatchFunc
The `match` expression in the config should be a `MatchFunc`. This can done by using any of the helper methods available:
```go
// accepts any number of hostnames and returns a match function that matches the hostname against any of them
matchHostname(...string) MatchFunc
// accepts any number of regexps and returns a match function that matches the hostname against any of them
matchHostRegexp(...string) MatchFunc
// accepts any number of regexps and returns a match function that matches the full url string against any of them
matchRegexp(...string) MatchFunc
// accepts any number of MatchFuncs and returns a new match function that matches against any of them
matchAny(...MatchFunc) MatchFunc
```
If you want more flexibility, you can write your own using the [`expr`](https://github.com/antonmedv/expr) language. Generally, this language gives you the power to write an expression that evaluates to a boolean using exposed variables. Additonally, a helper exists to convert a `bool` value into a `MatchFunc`. For example:
```
MatchFunc(hostname endsWith "google.com")
```
The following variables are avaiable for building custom match expressions.
```
hostname: the requested URL hostname
fullUrl: the full string of the requested URL
url: the Go url.URL struct requested URL
MatchFunc(bool) MatchFunc: constructs a match function from a bool value
```
## Installation
make install set-default