README.md in arx-1.2.1 vs README.md in arx-1.3.0

- old
+ new

@@ -21,11 +21,11 @@ 1. Suppose we wish to search for papers in the `cs.FL` (Formal Languages and Automata Theory) category whose title contains `"Buchi Automata"`, not authored by `Tomáš Babiak`, sorted by submission date (latest first). ```ruby require 'arx' - papers = Arx(sort_by: :date_submitted) do |query| + papers = Arx(sort_by: :submitted_at) do |query| query.category('cs.FL') query.title('Buchi Automata').and_not.author('Tomáš Babiak') end ``` @@ -44,11 +44,11 @@ ``` ## Features - Ruby classes `Arx::Paper`, `Arx::Author` and `Arx::Category` that wrap the resulting Atom XML query result from the search API. -- Supports querying by a paper's ID, title, author(s), abstract, subject category, comment, journal reference, or report number. +- Supports querying by a paper's ID, title, author(s), abstract, subject category, comment, journal reference, report number or last updated date. - Provides a small DSL for writing queries. - Supports searching fields by exact match. ## Installation @@ -90,26 +90,46 @@ #### Sorting criteria and order The order in which search results are returned can be modified through the `sort_by` and `sort_order` keyword arguments (in the `Arx::Query` initializer): -- `sort_by` accepts the symbols: `:relevance`, `:last_updated` or `:date_submitted` +- `sort_by` accepts the symbols: `:relevance`, `:updated_at` or `:submitted_at` - `sort_order` accepts the symbols: `:ascending` or `:descending` ```ruby # Sort by submission date in ascending order (earliest first) -Arx::Query.new(sort_by: :date_submitted, sort_order: :ascending) +Arx::Query.new(sort_by: :submitted_at, sort_order: :ascending) #=> sortBy=submittedDate&sortOrder=ascending ``` **Note**: The default setting is to sort by `:relevance` in `:descending` order: ```ruby Arx::Query.new #=> sortBy=relevance&sortOrder=descending ``` +#### Paging + +The arXiv API offers a paging mechanism that allows you to get chucks of the result set at a time. It can be used through the `start` and `max_results` keyword arguments (in the `Arx::Query` initializer): + +- `start` is the index of the first returned result (using 0-based indexing) + +- `max_results` is the number of results returned by the query + +```ruby +# Get results 10-29 +Arx::Query.new(start: 10, max_results: 20) +#=> start=10&max_results=20 +``` + +**Note**: The default values are those of the arXiv API: `start` defaults to `0` and `max_results` defaults to `10`: + +```ruby +Arx::Query.new #=> start=0&max_results=10 +``` + #### Searching by ID The arXiv search API doesn't only support searching for papers by metadata fields, but also by ID. When searching by ID, a different URL query string parameter `id_list` is used (instead of `search_query` as seen before). Although the `id_list` can be used to *"search by ID"*, it is better to **think of it as restricting the search space to the papers with the provided IDs**: @@ -131,18 +151,20 @@ The arXiv search API supports searches for the following paper metadata fields: ```ruby FIELDS = { - title: 'ti', # Title - author: 'au', # Author - abstract: 'abs', # Abstract - comment: 'co', # Comment - journal: 'jr', # Journal reference - category: 'cat', # Subject category - report: 'rn', # Report number - all: 'all' # All (of the above) + title: 'ti', # Title + author: 'au', # Author + abstract: 'abs', # Abstract + comment: 'co', # Comment + journal: 'jr', # Journal reference + category: 'cat', # Subject category + report: 'rn', # Report number + updated_at: 'lastUpdatedDate', # Last updated date + submitted_at: 'submittedDate', # Submission date + all: 'all' # All (of the above) } ``` Each of these fields has an instance method defined under the `Arx::Query` class. For example: @@ -254,11 +276,11 @@ **Note**: If running a search query this way, then the `sort_by` and `sort_order` parameters can be added as additional keyword arguments. ```ruby # Papers in the cs.FL category whose title contains "Buchi Automata", not authored by Tomáš Babiak -results = Arx(sort_by: :date_submitted) do |query| +results = Arx(sort_by: :submitted_at) do |query| query.category('cs.FL') query.title('Buchi Automata').and_not.author('Tomáš Babiak') end results.size #=> 18 @@ -270,11 +292,11 @@ **Note**: If using the `query` parameter, the `sort_by` and `sort_order` criteria should be defined in the `Arx::Query` object initializer rather than as arguments in `Arx()`. ```ruby # Papers in the cs.FL category whose title contains "Buchi Automata", not authored by Tomáš Babiak -q = Arx::Query.new(sort_by: :date_submitted) +q = Arx::Query.new(sort_by: :submitted_at) q.category('cs.FL') q.title('Buchi Automata').and_not.author('Tomáš Babiak') results = Arx(query: q) results.size #=> 18 @@ -398,25 +420,51 @@ #=> "cond-mat" category.full_name #=> "Condensed Matter" ``` -# Acknowledgements +## Acknowledgements A large portion of this library is based on the brilliant work done by [Scholastica](https://github.com/scholastica) in their [`arxiv`](https://github.com/scholastica/arxiv) gem for retrieving individual papers from arXiv through the search API. Arx was created mostly due to the seemingly inactive nature of Scholastica's repository. Additionally, it would have been infeasible to contribute such large changes to an already well-established gem, especially since https://scholasticahq.com/ appears to be dependent upon this gem. Nevertheless, a special thanks goes out to Scholastica for providing the influence for Arx. +## Contributors + +All contributions to this repository are greatly appreciated. Contribution guidelines can be found [here](/CONTRIBUTING.md). + +<table> + <thead> + <tr> + <th align="center"> + <a href="https://github.com/eonu"> + <img src="https://avatars0.githubusercontent.com/u/24795571?s=460&v=4" alt="Edwin Onuonga" width="60px"> + <br/>eonu + <br/><sub>(Edwin Onuonga)</sub> + </a> + <br/> + <a href="mailto:ed@eonu.net">✉️</a> + <a href="https://eonu.net">🌍</a> + </th> + <th align="center"> + <a href="https://github.com/xuanxu"> + <img src="https://avatars.githubusercontent.com/u/6528?v=4" alt="xuanxu" width="60px"> + <br/>xuanxu + <br/><sub>(Juanjo Bazán)</sub> + </a> + <br/> + <a href="jjbazan@gmail.com">✉️</a> + <a href="http://juanjobazan.com/">🌍</a> + </th> + <!-- Add more <th></th> blocks for more contributors --> + </tr> + </thead> +</table> + --- <p align="center"> <b>Arx</b> &copy; 2019-2020, Edwin Onuonga - Released under the <a href="http://mit-license.org/">MIT</a> License.<br/> <em>Authored and maintained by Edwin Onuonga.</em> - - <p align="center"> - <a href="https://eonu.net">eonu.net</a>&nbsp;&middot;&nbsp; - GitHub: <a href="https://github.com/eonu">@eonu</a>&nbsp;&middot;&nbsp; - Email: <a href="mailto:ed@eonu.net">ed@eonu.net</a> - </p> </p> \ No newline at end of file