FAQ

How to add a custom search engine?

• You need to create a file in .config/nbrowser/engines/ directory with the name of the keyword you want it to be called with.
• in that file you need to create nbrowser_search() function which receive the search query and then use it to construct a URL

this is a sample example of duckduckgo search engine saved in .config/nbrowser/engines/ddg

nbrowser_search(){
  echo "http://duckduckgo.com/?q=$@"
}

now if i called nbrowser and typed ?ddg music it well open http://duckduckgo.com/?q=music

# pro tips:
- you can symlink that file, and then call the same search engine using different keywords
  like: 'ln -s duckduckgo ddg' and 'ln -s github git' ...
- you can use parts of the search query as condition to construct different urls
  like if it start with '-p' return pictures url, "-v" for videos, "-n" for news... 

How to add a custom bang?

• You need to create a file in .config/nbrowser/bangs/ directory with the name of the keyword you want it to be called with.
• in that file you need to create nbrowser_bang() function which may receive a search query.

this is a sample example of a bang that use ddgr and jq saved in .config/nbrowser/bangs/ddg

nbrowser_bang(){
  # search for query $@ using ddgr and get result in json format
  ddg_result_json=$(ddgr --json "$@")
  # parse results with jq and show a menu to let the user choose,
  # then extract the url from selected line using awk
  ddg_result_url=$(printf '%s' "${ddg_result_json}" | jq -r '.[]| "\(.title)  --  \(.url)"' \
                 | _choose | awk '{print $NF}' )
  # if no result has been selected exit
  [ -z "$ddg_result_url" ] && exit 0
  # open selected URL
  url_handler "$ddg_result_url"
}

now if i called nbrowser and typed !ddg music it well search ddg for the query music and then open a menu of results you can choose from

# pro tips:
- bangs don't necessary need search query; so you may use that as condition to run different functions
- bangs are differnt from engines you can make them do anything you want
- bangs and `nbrowser` share the same shell environment, so you can read variables or
  call any function available in `nbrowser`.

## functions
  - `has` : to check for installed dependencies. (has "arg")
  - `_pemx` : show an error msg and exit. (_pemx "msg")
  - `_notify` : show an msg. (_notify "msg")
  - `_choose` : show a menu and print the selected line. (echo "arg" | _choose)
  - `_clean_url` : remove tracking parameters from url (_clean_url "url")
  - `_copy_to_clipboard` : copy to clipboard (_copy_to_clipboard "text")
  - `open_video_with` : show menu to open video with. (open_video_with "url")
  - `open_picture_with` : show menu to open picture with. (open_picture_with "url")
  - `open_in_browser` : show menu to open url in browser. (open_in_browser "url")
  - `url_handler` : clean url then open with. (url_handler "url")

## variables
  $NBROWSER_DEFAULT_SEARCH : the name of the default search engine
  + any variable from the config file ".config/nbrowser/config"

How to add a custom URL bang (ubang) ?

• You need to create a file in .config/nbrowser/ubangs/ directory with the name of the keyword you want it to be called with.
• in that file you need to create nbrowser_ubang() function which receive the URL.

this is a sample example which redirect the URL to open_video_with() function saved in .config/nbrowser/ubangs/p

nbrowser_ubang() {
  open_video_with "$*"
}

now if i called nbrowser "https://example.com/" and typed !p it well open the Video Menu and then you can choose play the URL or download it

# pro tips:
- ubangs are like bangs share the same shell environment with `nbrowser`
- you can make an ubang to scan the url with virustotal, shorten it,
  generate a qr code to easily share it with your phone, or add it to local bookmark manager (ex: buku) ... 

How to add a custom domain bang (dbang) ?

- What is a dbang??
the idea is : when you send a URL to nbrowser it well extract the domain and check if you have a specific dbang for it then
  run the dbang without any need for an interaction
else
  show the default Menu

• You need to create a file in .config/nbrowser/dbangs/ directory with the name of the domain you want.
• in that file you need to create nbrowser_dbang() function which receive the URL.

this is a sample example which force open example.com URLs with mpv saved in .config/nbrowser/dbangs/example.com

nbrowser_dbang() {
  { setsid -f mpv "$*" >/dev/null 2>&1 ; }
}

now if i called nbrowser "https://example.com/something", nbrowser well play that URL with mpv

# pro tips:
- dbangs are like bangs share the same shell environment with `nbrowser`
- the regex i am using ignore the subdomains, so if you made a bang for "domain.com", all urls *.domain.com well be redirected to that bang
- if you want to run different functions for subdomains or only a specific subdomain make sure to check for that in your bang