Bangs

A lightweight and extensible search engine that leverages "bangs" to quickly redirect queries to your favorite services. Customize your search experience by defining your own bangs and effortlessly expand its capabilities.

Features

• Customizable Bangs: Define and manage your own bangs through a simple bangs.yaml configuration file.
• Flexible Query Handling: Perform searches using query parameters or clean URL paths.
• Command-Line Interface: Easily configure and run the search engine with various CLI options.
• Default Search Engine: Specify a default search URL for queries without a bang (only works when using q query parameter).
• Public Instances: Accessible via https://bang.dikka.dev and https://s.dikka.dev with HTTPS support.
• Extensible & Open: Contributions to expand and refine bang definitions are highly encouraged.
• Robust Testing: Automated Go workflows ensure the correctness and reliability of bang URLs.

Public Instances

Experience Bangs without any setup by using our public instances:

• Primary Instance: https://bang.dikka.dev
• Alternative Instance: https://s.dikka.dev

Both URLs point to the same backend and support HTTPS for secure connections.

Installation

Docker (Preferred)

Note: Docker support is forthcoming. Stay tuned for updates!

• Docker Image: To be hosted on GitHub.
• Usage: TBD

Build from Source

Ensure you have Go installed (version 1.18 or later).

1. Clone the Repository

   git clone https://github.com/Sett17/bangs.git
   cd bangs

2. Build the Application

   go build -o bangs ./cmd

Usage

Usage Scenarios

1. Query-Based Search

Perform a search by specifying the bang and query as URL parameters using the public instance.

Example:

https://s.dikka.dev/?q=!gh Sett17/bangs

Explanation:
The above URL uses the !gh bang to perform a GitHub search for the repository Sett17/bangs.

With query-based searches, you also have the option to omit the bang and use the default search engine defined in bangs.yaml. This is useful when you want to use bangs as the default search engine in your browser, so you do not need to specify a bang every time.

2. Path-Based Search

Perform a search by embedding the bang and query directly into the URL path using the public instance.

Example:

https://s.dikka.dev/!gh/Sett17/bangs

Explanation:
This URL achieves the same search as the query-based example but uses the path to specify the bang and query.

3. Default Search

Perform a search without specifying a bang, which uses the default search engine.

Example:

https://s.dikka.dev/?q=OpenAI ChatGPT

Explanation:
The above URL uses the default search engine defined in bangs.yaml to search for "OpenAI ChatGPT".

4. Double Hashtag Search

Perform a search by typing a double hashtag ## at the start of the query, which uses the default search engine.

Example:

https://s.dikka.dev/?q=##OpenAI ChatGPT

Explanation:
The above URL uses the default search engine defined in bangs.yaml to search for "OpenAI ChatGPT" by stripping the ## from the query.

Command-Line Options

Option	Short	Description	Default	Example
--bangs	-b	Path to the YAML file containing bang definitions.	bangs.yaml	-b path/to/your/bangs.yaml
--port	-p	Port on which the server will run.	8080	-p 9090
--verbose	-v	Enable verbose debug logging.	false	-v
--help	-h	Show help message.	false	-h

Configuration

Bangs are defined in a bangs.yaml file. Each bang maps a unique identifier to a search URL containing a placeholder {} where the query will be inserted. Additionally, a default key can be specified to handle searches without a bang.

Example bangs.yaml:

default: 'https://www.google.com/search?q={}'

# Other search engines:
# default: 'https://www.bing.com/search?q={}'
# default: 'https://duckduckgo.com/?q={}'

gh:
  bang: "gh"
  url: "https://github.com/Sett17/{}"
  description: 'Search code repositories on GitHub.'

g:
  bang: "g"
  url: "https://www.google.com/search?q={}"
  description: 'Popular global search engine by Google.'

Setting Bangs as the Default Search Engine

This capability varies based on your browser.

Chromium-Based Browsers

s.dikka.dev/g/chrome set default search engine

Firefox

s.dikka.dev/g/firefox set default search engine

Advanced Usage

Enhance your Bangs experience with advanced configurations and persistent setups. For detailed instructions, please refer to the Advanced Usage guide.

Contributing

Contributions are highly welcome! If you have new bangs to add or improvements to the existing ones, feel free to submit a pull request to the bangs.yaml file.

How to Contribute

• Branch Naming: Please name your feature branches in the format bang/{chars}, where {chars} represents the bang characters (e.g., bang/y, bang/gh).
• Adding Bangs: Ensure your new bang is placed in the appropriate section within bangs.yaml.
• Non-Search Bangs: If your contribution is not a search-related bang, please explain the use case clearly in your pull request description.
• Follow Templates: There are issue and PR templates in place to guide your contributions. Please follow them.

Testing

The project includes a comprehensive Go test workflow that not only checks the functionality of the application but also validates the correctness of all bang URLs defined in bangs.yaml.

Running Tests Locally

go test ./...

Continuous Integration

Every pull request triggers the Go test workflow to ensure that new contributions do not break existing functionality and that all bang URLs remain valid.

Docker

Installation and Running with Docker

Note: Docker support is forthcoming. Stay tuned for updates!

• Docker Image: To be hosted on GitHub.
• Usage: TBD

License

LICENSE

---

Happy Searching! 🚀