mechanize.cr/README.md

122 lines
2.8 KiB
Markdown
Raw Normal View History

2021-06-02 07:36:52 +02:00
# mechanize.cr
2021-04-19 06:50:12 +02:00
2021-08-17 18:31:15 +02:00
[![Crystal CI](https://github.com/Kanezoh/mechanize.cr/actions/workflows/crystal.yml/badge.svg)](https://github.com/Kanezoh/mechanize.cr/actions/workflows/crystal.yml)
2021-04-30 14:40:06 +02:00
This project is inspired by Ruby's [mechanize](https://github.com/sparklemotion/mechanize).
2021-05-03 01:23:07 +02:00
The purpose is to cover all the features of original one.
2022-01-24 13:25:58 +01:00
[API Documentation](https://kanezoh.github.io/mechanize.cr/)
2021-04-19 06:50:12 +02:00
## Installation
1. Add the dependency to your `shard.yml`:
```yaml
dependencies:
mechanize:
2021-06-02 07:36:52 +02:00
github: Kanezoh/mechanize.cr
2021-04-19 06:50:12 +02:00
```
2. Run `shards install`
## Usage
2022-01-24 13:25:58 +01:00
### GET request
2021-06-02 07:36:52 +02:00
```crystal
require "mechanize"
agent = Mechanize.new
page = agent.get("http://example.com/")
puts page.code # => 200
puts page.body # => html
puts page.title # => Example Domain
```
### POST request
You can also send post request with data.
```crystal
require "mechanize"
agent = Mechanize.new
query = {"foo" => "foo_value", "bar" => "bar_value"}
page = agent.post("http://example.com/", query: query)
# => request body is foo=foo_value&bar=bar_value
```
### add query params, request_headers
2021-08-14 11:20:15 +02:00
You can add any query parameters and headers to requests.
2021-06-02 07:36:52 +02:00
2021-04-19 06:50:12 +02:00
```crystal
require "mechanize"
2021-06-02 07:36:52 +02:00
agent = Mechanize.new
agent.request_headers = HTTP::Headers{"Foo" => "Bar"}
params = {"hoge" => "hoge"}
page = agent.get("http://example.com/", params: params)
# The actual URL is http://example.com/?hoge=hoge
2021-04-19 06:50:12 +02:00
```
2021-06-02 07:36:52 +02:00
### fill and submit form
You can fill and submit form by using `field_with` and `submit`. It enables you to scrape web pages requiring login.
```crystal
require "mechanize"
agent = Mechanize.new
page = agent.get("#{web page contains login form}")
form = page.forms[0]
form.field_with("email").value = "tester@example.com"
form.field_with("password").value = "xxxxxx"
agent.submit(form)
2021-06-02 07:41:50 +02:00
agent.get("#{web page only logged-in users can see}"
2021-06-02 07:36:52 +02:00
```
2021-04-19 06:50:12 +02:00
2021-06-02 07:46:26 +02:00
### search node
You can use css selector to search html nodes by using `#css` method.
2021-08-14 11:20:15 +02:00
This method is from [lexbor](https://github.com/kostya/lexbor), so if you want to explore more, please refer the repository.
2021-06-02 07:46:26 +02:00
```crystal
puts page.css("h1").first.inner_text
```
2021-11-18 08:47:52 +01:00
### Logging
For activation, simply setup the log to `:debug` level
```crystal
Log.setup("mechanize", :debug)
```
2022-01-24 13:25:58 +01:00
### Basic auth
You can access a page which is protected by basic auth, setting username and password for the url.
```crystal
agent = Mechanize.new
agent.add_auth("http://example.com", "username", "password")
agent.get("http://example.com")
```
2021-04-19 06:50:12 +02:00
## Contributing
2021-06-02 07:37:33 +02:00
1. Fork it (<https://github.com/Kanezoh/mechanize.cr/fork>)
2021-04-19 06:50:12 +02:00
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Contributors
2021-06-02 07:37:33 +02:00
- [Kanezoh](https://github.com/Kanezoh) - creator and maintainer
2021-08-24 04:50:39 +02:00
- [mamantoha](https://github.com/mamantoha) - contributor