cff 0.8.0 → 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES.md +91 -0
- data/CITATION.cff +62 -5
- data/CONTRIBUTING.md +71 -0
- data/LICENCE +1 -1
- data/README.md +57 -17
- data/Rakefile +9 -8
- data/cff.gemspec +12 -11
- data/lib/cff/citable.rb +72 -0
- data/lib/cff/entity.rb +11 -31
- data/lib/cff/errors.rb +14 -9
- data/lib/cff/file.rb +101 -31
- data/lib/cff/formatters/all.rb +26 -0
- data/lib/cff/formatters/apalike.rb +145 -0
- data/lib/cff/formatters/bibtex.rb +205 -0
- data/lib/cff/formatters/formatter.rb +98 -0
- data/lib/cff/formatters.rb +61 -0
- data/lib/cff/identifier.rb +14 -8
- data/lib/cff/{model.rb → index.rb} +73 -66
- data/lib/cff/licensable.rb +4 -5
- data/lib/cff/model_part.rb +46 -10
- data/lib/cff/person.rb +8 -10
- data/lib/cff/reference.rb +76 -112
- data/lib/cff/schema.rb +23 -0
- data/lib/{schema → cff/schemas}/1.2.0.json +1 -1
- data/lib/cff/util.rb +63 -6
- data/lib/cff/validatable.rb +13 -13
- data/lib/cff/version.rb +2 -2
- data/lib/cff.rb +4 -27
- metadata +37 -31
- data/lib/cff/formatter/apa_formatter.rb +0 -77
- data/lib/cff/formatter/bibtex_formatter.rb +0 -122
- data/lib/cff/formatter/formatter.rb +0 -63
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a3c050f5d10f432c5f693e34a3e357d6f6cb6354a34f1437e2d002d31260a668
|
|
4
|
+
data.tar.gz: 77a28d90a783419770aa706b033fc16895aa33762b1bf1e8d63f283e949b52b8
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 20af71ee0317e192bccd3cd2a4e8e2be39c8bab84b9c4c74571968b80d519d292b2b7f2564aa5786fe995fddedfa90edea76058e400bd0971b1d805e0256b9ab
|
|
7
|
+
data.tar.gz: e38acde51d42a67b37c197c9d03e55fbe2a55ec5f3ee2e2632c1842a6292035831ac55acfd8ded8812bda8dc06d96578b2dcf28870f29f1d6fc0c855df758ba8
|
data/CHANGES.md
CHANGED
|
@@ -1,5 +1,96 @@
|
|
|
1
1
|
# Changes log for the Ruby CFF Library
|
|
2
2
|
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
* Add `type` to top-level CFF model.
|
|
6
|
+
* Correctly label datasets with APA-like formatter.
|
|
7
|
+
* Formatters: output a year, even if a month is not given.
|
|
8
|
+
* BibTeX: generalize getting simple publication data.
|
|
9
|
+
* BibTeX: generalize getting more complex publication data.
|
|
10
|
+
* BibTeX: get volume number from CFF `issue`.
|
|
11
|
+
* BibTeX: get publisher for a book.
|
|
12
|
+
* APA: get publisher for a book.
|
|
13
|
+
* BibTeX: add 'inproceedings' type for a preferred-citation.
|
|
14
|
+
* APA: add 'conference-paper' type for a preferred-citation.
|
|
15
|
+
* Generalize the `::pages_from_model` method.
|
|
16
|
+
* BibTeX: add address information where appropriate.
|
|
17
|
+
* BibTeX: use `software`, not `misc` where appropriate.
|
|
18
|
+
* BibTeX: add `version` field to `software` type.
|
|
19
|
+
* BibTeX: add `license` field to `software` type.
|
|
20
|
+
* Update README with the BibTeX formatter updates.
|
|
21
|
+
* Adding missing mapping for proceedings and conference
|
|
22
|
+
* BibTeX: add `manual` type for `preferred-citation`.
|
|
23
|
+
* BibTeX: add `doi` field to `manual` type.
|
|
24
|
+
* BibTeX: add `unpublished` type for `preferred-citation`.
|
|
25
|
+
* BibTeX: add `booklet` type for `preferred-citation`.
|
|
26
|
+
* BibTeX: add `techreport` type for `preferred-citation`.
|
|
27
|
+
* BibTeX: add the `institution` field for a `techreport`.
|
|
28
|
+
* APA: add the institution for a report, if possible.
|
|
29
|
+
* Clean up affiliations that include location in the report fixtures.
|
|
30
|
+
* Add `alias` field to `Entity`.
|
|
31
|
+
* Add a note to `Reference` about the `format` field.
|
|
32
|
+
* Ensure allowed fields in `Reference` are in alpha order.
|
|
33
|
+
* Add `term` field to `Reference`.
|
|
34
|
+
* Ensure allowed fields in `Entity` are in alpha order.
|
|
35
|
+
* Define `ModelPart#empty?`.
|
|
36
|
+
* Use `ModelPart#empty?` to simplify the formatter code.
|
|
37
|
+
* BibTeX: add the `note` field to all types.
|
|
38
|
+
* Prevent errors when cff is passed explicit `nil`s
|
|
39
|
+
* Update model part constructors for consistent behaviour.
|
|
40
|
+
* BibTeX: Use conference date if citing a conference paper.
|
|
41
|
+
* APA: Use conference date if citing a conference paper.
|
|
42
|
+
* APA: update range code to be more flexible.
|
|
43
|
+
* APA: add [Conference paper] label for conference papers.
|
|
44
|
+
* APA: handle date ranges with an earlier end date.
|
|
45
|
+
* Add `Util::transliterate` to normalise towards ASCII.
|
|
46
|
+
* Use the `transliterate` method to normalize citekeys.
|
|
47
|
+
* Add `Util::parameterize` to consolidate citekey code.
|
|
48
|
+
* Use the `parameterize` method to generate citekeys.
|
|
49
|
+
* Rename `generate_reference` -> `generate_citekey`.
|
|
50
|
+
* Only require language list if it is needed
|
|
51
|
+
* APA: don't output empty brackets if there's no issue.
|
|
52
|
+
* Formatters: use `date-published` for month/year values.
|
|
53
|
+
* Add a note to the README about BibTeX and APA standards.
|
|
54
|
+
* BibTeX: generalise author lists to actor lists.
|
|
55
|
+
* BibTeX: add `editor` field for `inproceedings` type.
|
|
56
|
+
* BibTeX: use `editors-series` if `editors` is not present.
|
|
57
|
+
* BibTeX: add `editor` field to `book` type.
|
|
58
|
+
* BibTeX: add `editor` field to `proceedings` type.
|
|
59
|
+
* Use the schema to determine the allowed fields within `Reference`.
|
|
60
|
+
* Use the schema to determine the allowed fields within `Person`.
|
|
61
|
+
* Use the schema to determine the allowed fields within `Entity`.
|
|
62
|
+
* Use the schema to determine the allowed fields within `Model`.
|
|
63
|
+
* Use the schema to determine the allowed fields within `Identifier`.
|
|
64
|
+
* Rename the `Model` class to `Index` which makes more sense.
|
|
65
|
+
* Add 'phdthesis' and 'mastersthesis' types for a preferred-citation.
|
|
66
|
+
* Add contribution guidelines.
|
|
67
|
+
* Handle 'in-press' in the formatters.
|
|
68
|
+
* Handle 'in-preparation' in the formatters.
|
|
69
|
+
* Handle 'submitted' in the formatters.
|
|
70
|
+
* Handle 'advance-online' in the formatters.
|
|
71
|
+
* Wholesale changes to isolate all the code from itself.
|
|
72
|
+
* Expand the range of tests, rubies and OSs in the CI.
|
|
73
|
+
* Update runtime gem dependencies.
|
|
74
|
+
* Implement an extensible formatter system.
|
|
75
|
+
|
|
76
|
+
## Version 0.9.0
|
|
77
|
+
|
|
78
|
+
* Update to final released version of schema 1.2.0.
|
|
79
|
+
* Add `description` field to `Identifier`.
|
|
80
|
+
* Add `Model::read` to parse a CFF file from memory.
|
|
81
|
+
* Add `Model::open`. Same as `read` but can take a block.
|
|
82
|
+
* Override `File#to_yaml`.
|
|
83
|
+
* Allow `File::write` to write File objects.
|
|
84
|
+
* Add `save_as` parameter to `File#write`.
|
|
85
|
+
* Add `Reference::from_cff`.
|
|
86
|
+
* Update CITATION.cff file to reference CFF repo.
|
|
87
|
+
* Fix `File` docs to be explicit about filenames.
|
|
88
|
+
* Validate the filename of a CFF file.
|
|
89
|
+
* Surface the `fail_fast` options on the `File` validatation methods.
|
|
90
|
+
* Reduce json_schema dependency to ~0.20.0.
|
|
91
|
+
* Fix APA-like formatter when a reference is missing a volume.
|
|
92
|
+
* APA: don't emit journal data if there's no journal.
|
|
93
|
+
|
|
3
94
|
## Version 0.8.0
|
|
4
95
|
|
|
5
96
|
* Add a comment field to the File class.
|
data/CITATION.cff
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# This CITATION.cff file was created by ruby-cff (v 0.
|
|
1
|
+
# This CITATION.cff file was created by ruby-cff (v 1.0.0).
|
|
2
2
|
# Gem: https://rubygems.org/gems/cff
|
|
3
3
|
# CFF: https://citation-file-format.github.io/
|
|
4
4
|
|
|
@@ -15,12 +15,69 @@ authors:
|
|
|
15
15
|
keywords:
|
|
16
16
|
- ruby
|
|
17
17
|
- credit
|
|
18
|
-
- citation
|
|
18
|
+
- software citation
|
|
19
|
+
- research software
|
|
20
|
+
- software sustainability
|
|
19
21
|
- metadata
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
+
- citation file format
|
|
23
|
+
- CFF
|
|
24
|
+
version: 1.0.0
|
|
22
25
|
doi: 10.5281/zenodo.1184077
|
|
23
|
-
date-released:
|
|
26
|
+
date-released: 2022-10-09
|
|
24
27
|
license: Apache-2.0
|
|
25
28
|
repository-artifact: https://rubygems.org/gems/cff
|
|
26
29
|
repository-code: https://github.com/citation-file-format/ruby-cff
|
|
30
|
+
references:
|
|
31
|
+
- type: software
|
|
32
|
+
title: Citation File Format
|
|
33
|
+
authors:
|
|
34
|
+
- family-names: Druskat
|
|
35
|
+
given-names: Stephan
|
|
36
|
+
orcid: https://orcid.org/0000-0003-4925-7248
|
|
37
|
+
- family-names: Spaaks
|
|
38
|
+
given-names: Jurriaan H.
|
|
39
|
+
orcid: https://orcid.org/0000-0002-7064-4069
|
|
40
|
+
- family-names: Chue Hong
|
|
41
|
+
given-names: Neil
|
|
42
|
+
orcid: https://orcid.org/0000-0002-8876-7606
|
|
43
|
+
- family-names: Haines
|
|
44
|
+
given-names: Robert
|
|
45
|
+
orcid: https://orcid.org/0000-0002-9538-7919
|
|
46
|
+
- family-names: Baker
|
|
47
|
+
given-names: James
|
|
48
|
+
orcid: https://orcid.org/0000-0002-2682-6922
|
|
49
|
+
- family-names: Bliven
|
|
50
|
+
given-names: Spencer
|
|
51
|
+
orcid: https://orcid.org/0000-0002-1200-1698
|
|
52
|
+
email: spencer.bliven@gmail.com
|
|
53
|
+
- family-names: Willighagen
|
|
54
|
+
given-names: Egon
|
|
55
|
+
orcid: https://orcid.org/0000-0001-7542-0286
|
|
56
|
+
- family-names: Pérez-Suárez
|
|
57
|
+
given-names: David
|
|
58
|
+
orcid: https://orcid.org/0000-0003-0784-6909
|
|
59
|
+
website: https://dpshelio.github.io
|
|
60
|
+
- family-names: Konovalov
|
|
61
|
+
given-names: Alexander
|
|
62
|
+
orcid: https://orcid.org/0000-0001-5299-3292
|
|
63
|
+
identifiers:
|
|
64
|
+
- type: doi
|
|
65
|
+
value: 10.5281/zenodo.1003149
|
|
66
|
+
description: The concept DOI for the collection containing all versions of the Citation File Format.
|
|
67
|
+
- type: doi
|
|
68
|
+
value: 10.5281/zenodo.5171937
|
|
69
|
+
description: The versioned DOI for the version 1.2.0 of the Citation File Format.
|
|
70
|
+
keywords:
|
|
71
|
+
- citation file format
|
|
72
|
+
- CFF
|
|
73
|
+
- citation files
|
|
74
|
+
- software citation
|
|
75
|
+
- file format
|
|
76
|
+
- YAML
|
|
77
|
+
- software sustainability
|
|
78
|
+
- research software
|
|
79
|
+
- credit
|
|
80
|
+
abstract: CITATION.cff files are plain text files with human- and machine-readable citation information for software. Code developers can include them in their repositories to let others know how to correctly cite their software. This is the specification for the Citation File Format.
|
|
81
|
+
date-released: 2021-08-09
|
|
82
|
+
license: CC-BY-4.0
|
|
83
|
+
version: 1.2.0
|
data/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Contributing to the Ruby CFF Library
|
|
2
|
+
## Introduction
|
|
3
|
+
|
|
4
|
+
**Thank you** for considering a contribution to the **Ruby CFF Library**!
|
|
5
|
+
|
|
6
|
+
If you intended to contribute to another part of the Citation File Format project, for example the Citation File Format specification itself, please contribute to the respective repository ([list of repositories in the `citation-file-format` GitHub organization](https://github.com/orgs/citation-file-format/repositories)).
|
|
7
|
+
|
|
8
|
+
**Please follow these guidelines.** Their purpose is to make both contributing and accepting contributions easier for all parties involved.
|
|
9
|
+
|
|
10
|
+
There are many ways to contribute, e.g.:
|
|
11
|
+
|
|
12
|
+
* Tell a friend or colleague about the Citation File Format and Ruby CFF, or tweet about it
|
|
13
|
+
* Write blog posts, tutorials, etc. about the Citation File Format and Ruby CFF
|
|
14
|
+
* Review the format and its schema and documentation
|
|
15
|
+
* Improve wording in any prose output, including the specifications
|
|
16
|
+
* Create a new, better version of the schema and specifications
|
|
17
|
+
* Improve automated tests, continuous integration, documentation, etc.
|
|
18
|
+
|
|
19
|
+
## Ground Rules
|
|
20
|
+
|
|
21
|
+
Your contribution to Ruby CFF is valued, and it should be an enjoyable experience. To ensure this there is the Ruby CFF
|
|
22
|
+
[Code of Conduct](https://github.com/citation-file-format/ruby-cff/blob/main/CODE_OF_CONDUCT.md) which you are required to follow.
|
|
23
|
+
|
|
24
|
+
Please always start any contribution that will change the contents of this repository from [an issue](https://github.com/citation-file-format/ruby-cff/issues). This may mean [creating a new issue](https://github.com/citation-file-format/ruby-cff/issues/new) if it's something that hasn't been requested so far. This way,
|
|
25
|
+
|
|
26
|
+
* you can make sure that you don't invest your valuable time in something that may not be merged; and
|
|
27
|
+
* we can make sure that your contribution is something that will improve Ruby CFF, is in scope, and aligns with the roadmap for the Ruby CFF and the Citation File Format.
|
|
28
|
+
|
|
29
|
+
## Your First Contribution
|
|
30
|
+
|
|
31
|
+
If you are unsure where to begin with your contribution to CFF, have a look at the [open issues in this repository](https://github.com/citation-file-format/ruby-cff/issues), and see if you can identify one that you would like to work on.
|
|
32
|
+
|
|
33
|
+
If you have never contributed to an open source project, you may find this tutorial helpful: [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github).
|
|
34
|
+
|
|
35
|
+
## Getting started
|
|
36
|
+
|
|
37
|
+
This is the workflow for contributions to this repository:
|
|
38
|
+
|
|
39
|
+
1. Take note of the [code of conduct](https://github.com/citation-file-format/ruby-cff/blob/main/CODE_OF_CONDUCT.md)
|
|
40
|
+
1. [Create a new issue](https://github.com/citation-file-format/ruby-cff/issues/new) if needs be, and discuss the changes you want to make with the maintainers and community
|
|
41
|
+
1. Fork the repository
|
|
42
|
+
1. Create a branch in your fork of the repository
|
|
43
|
+
1. Make changes in the new branch in your fork
|
|
44
|
+
* Please don't forget tests!
|
|
45
|
+
* If you add any classes, modules, methods, attributes, or constants, please document them
|
|
46
|
+
1. Create a pull request
|
|
47
|
+
1. Address any comments that come up during review
|
|
48
|
+
1. If and when your pull request has been merged, you can delete your branch (or the whole forked repository)
|
|
49
|
+
|
|
50
|
+
This workflow is loosely based on GitHub flow, and you can find more information in the [GitHub flow documentation](https://docs.github.com/en/get-started/quickstart/github-flow).
|
|
51
|
+
|
|
52
|
+
### Working with tests and documentation
|
|
53
|
+
|
|
54
|
+
There is a comprehensive test suite for Ruby CFF, which also contains a collection of test `CITATION.cff` files - both valid and invalid. Please add tests (and new test `CITATION.cff` files if appropriate) for any new features you add, or bugs you squash. It is advised to run these tests locally on your computer prior to submitting a pull request. However, if that's not possible, you still can submit the pull request and later check the status of the tests for your pull request on GitHub.
|
|
55
|
+
|
|
56
|
+
To run the tests, assuming that you have all the dependencies installed, simply run:
|
|
57
|
+
```shell
|
|
58
|
+
$ rake
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
To rebuild the documentation, if you have added to it or changed it:
|
|
62
|
+
```shell
|
|
63
|
+
$ rake rdoc
|
|
64
|
+
```
|
|
65
|
+
Then load `html/index.html` into a Web browser and double check it.
|
|
66
|
+
|
|
67
|
+
## FAQ
|
|
68
|
+
|
|
69
|
+
- **These guidelines do not address aspect XYZ! What should I do now?**
|
|
70
|
+
|
|
71
|
+
Please [submit an issue](https://github.com/citation-file-format/ruby-cff/issues/new), asking for clarification of and/or an addition to the guidelines.
|
data/LICENCE
CHANGED
|
@@ -186,7 +186,7 @@
|
|
|
186
186
|
same "printed page" as the copyright notice for easier
|
|
187
187
|
identification within third-party archives.
|
|
188
188
|
|
|
189
|
-
Copyright (c) 2018-
|
|
189
|
+
Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
|
|
190
190
|
|
|
191
191
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
192
|
you may not use this file except in compliance with the License.
|
data/README.md
CHANGED
|
@@ -7,6 +7,7 @@ A Ruby library for creating, editing, validating and converting CITATION.cff fil
|
|
|
7
7
|
[](https://badge.fury.io/rb/cff)
|
|
8
8
|
[](https://github.com/citation-file-format/ruby-cff/actions/workflows/ruby.yml)
|
|
9
9
|
[](https://github.com/citation-file-format/ruby-cff/actions/workflows/lint.yml)
|
|
10
|
+
[](https://github.com/rubocop/rubocop)
|
|
10
11
|
[](https://codeclimate.com/github/citation-file-format/ruby-cff/maintainability)
|
|
11
12
|
[](https://coveralls.io/github/citation-file-format/ruby-cff)
|
|
12
13
|
|
|
@@ -14,7 +15,7 @@ A Ruby library for creating, editing, validating and converting CITATION.cff fil
|
|
|
14
15
|
|
|
15
16
|
This library provides a Ruby interface to create and edit Citation File Format (CFF) files. The resulting files can be validated against a formal schema to ensure correctness and can be output in a number of different citation-friendly formats.
|
|
16
17
|
|
|
17
|
-
The primary API entry points are the `
|
|
18
|
+
The primary API entry points are the `Index` and `File` classes.
|
|
18
19
|
|
|
19
20
|
See the [CITATION.cff documentation](https://citation-file-format.github.io/) for more details about the Citation File Format.
|
|
20
21
|
|
|
@@ -22,10 +23,10 @@ See the [full API documentation](https://citation-file-format.github.io/ruby-cff
|
|
|
22
23
|
|
|
23
24
|
### Quick start
|
|
24
25
|
|
|
25
|
-
You can quickly build and save a CFF
|
|
26
|
+
You can quickly build and save a CFF index like this:
|
|
26
27
|
|
|
27
28
|
```ruby
|
|
28
|
-
|
|
29
|
+
index = CFF::Index.new('Ruby CFF Library') do |cff|
|
|
29
30
|
cff.version = CFF::VERSION
|
|
30
31
|
cff.date_released = Date.today
|
|
31
32
|
cff.authors << CFF::Person.new('Robert', 'Haines')
|
|
@@ -35,7 +36,7 @@ model = CFF::Model.new('Ruby CFF Library') do |cff|
|
|
|
35
36
|
cff.repository_code = 'https://github.com/citation-file-format/ruby-cff'
|
|
36
37
|
end
|
|
37
38
|
|
|
38
|
-
CFF::File.write('CITATION.cff',
|
|
39
|
+
CFF::File.write('CITATION.cff', index)
|
|
39
40
|
```
|
|
40
41
|
|
|
41
42
|
Which will produce a file that looks something like this:
|
|
@@ -51,14 +52,14 @@ keywords:
|
|
|
51
52
|
- ruby
|
|
52
53
|
- credit
|
|
53
54
|
- citation
|
|
54
|
-
version: 0.
|
|
55
|
-
date-released:
|
|
55
|
+
version: 1.0.0
|
|
56
|
+
date-released: 2022-10-01
|
|
56
57
|
license: Apache-2.0
|
|
57
58
|
repository-artifact: https://rubygems.org/gems/cff
|
|
58
59
|
repository-code: https://github.com/citation-file-format/ruby-cff
|
|
59
60
|
```
|
|
60
61
|
|
|
61
|
-
`CFF::File` can be used to create a file directly, and it exposes the underlying `CFF::
|
|
62
|
+
`CFF::File` can be used to create a file directly, and it exposes the underlying `CFF::Index` directly. If using a block with `CFF::File::open` the file will get written on closing it:
|
|
62
63
|
|
|
63
64
|
```ruby
|
|
64
65
|
CFF::File.open('CITATION.cff') do |cff|
|
|
@@ -72,6 +73,38 @@ CFF::File.open('CITATION.cff') do |cff|
|
|
|
72
73
|
end
|
|
73
74
|
```
|
|
74
75
|
|
|
76
|
+
You can read a CFF file quickly with `CFF::File::read`:
|
|
77
|
+
|
|
78
|
+
```ruby
|
|
79
|
+
cff = CFF::File.read('CITATION.cff')
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
And you can read a CFF file from memory with `CFF::Index::read` or `CFF::Index::open` - as with `CFF::File` a block can be passed in to `open`:
|
|
83
|
+
|
|
84
|
+
```ruby
|
|
85
|
+
cff_string = ::File.read('CITATION.cff')
|
|
86
|
+
cff = CFF::Index.read(cff_string)
|
|
87
|
+
|
|
88
|
+
CFF::Index.open(cff_string) do |cff|
|
|
89
|
+
# Edit cff here...
|
|
90
|
+
end
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
To quickly reference other software from your own CFF file, you can use `CFF::Reference.from_cff`. This example uses the CFF file from the core CFF repository as a reference for the Ruby CFF repository:
|
|
94
|
+
|
|
95
|
+
```ruby
|
|
96
|
+
require 'open-uri'
|
|
97
|
+
|
|
98
|
+
uri = 'https://raw.githubusercontent.com/citation-file-format/citation-file-format/main/CITATION.cff'
|
|
99
|
+
other_cff = URI(uri).open.read
|
|
100
|
+
|
|
101
|
+
ref = CFF::Reference.from_cff(CFF::Index.read(other_cff))
|
|
102
|
+
|
|
103
|
+
CFF::File.open('CITATION.cff') do |cff|
|
|
104
|
+
cff.references = [ref]
|
|
105
|
+
end
|
|
106
|
+
```
|
|
107
|
+
|
|
75
108
|
### Validating CFF files
|
|
76
109
|
|
|
77
110
|
To quickly validate a file and raise an error on failure, you can use `CFF::File` directly:
|
|
@@ -84,7 +117,7 @@ rescue CFF::ValidationError => e
|
|
|
84
117
|
end
|
|
85
118
|
```
|
|
86
119
|
|
|
87
|
-
Both `CFF::File` and `CFF::
|
|
120
|
+
Both `CFF::File` and `CFF::Index` have instance methods to validate CFF files as well:
|
|
88
121
|
|
|
89
122
|
```ruby
|
|
90
123
|
cff = CFF::File.read('CITATION.cff')
|
|
@@ -95,9 +128,11 @@ rescue CFF::ValidationError => e
|
|
|
95
128
|
end
|
|
96
129
|
```
|
|
97
130
|
|
|
98
|
-
Non-bang methods (`validate`) return
|
|
131
|
+
Non-bang methods (`validate`) return an array, with `true`/`false` at index 0 to indicate pass/fail, and an array of errors at index 1 (if any).
|
|
132
|
+
|
|
133
|
+
Passing `fail_fast: true` (default: `false`) will cause the validator to abort on the first error it encounters and report just that. Only the instance methods on `CFF::File` and `CFF::Index` provide the `fail_fast` option.
|
|
99
134
|
|
|
100
|
-
|
|
135
|
+
The validation methods (both class and instance) on `File` also validate the filename of a CFF file; in normal circumstances a CFF file should be named 'CITATION.cff'. You can switch this behaviour off by passing `fail_on_filename: false`. The non-bang methods (`validate`) on `File` return an extra value in the result array: `true`/`false` at index 2 to indicate whether the filename passed/failed validation.
|
|
101
136
|
|
|
102
137
|
### Outputting citation text
|
|
103
138
|
|
|
@@ -121,19 +156,21 @@ Assuming the same CFF data as above, the two formats will look something like th
|
|
|
121
156
|
#### BibTeX format
|
|
122
157
|
|
|
123
158
|
```tex
|
|
124
|
-
@
|
|
159
|
+
@software{Haines_Ruby_CFF_Library_2022,
|
|
125
160
|
author = {Haines, Robert},
|
|
126
|
-
|
|
161
|
+
license = {Apache-2.0},
|
|
162
|
+
month = {10},
|
|
127
163
|
title = {{Ruby CFF Library}},
|
|
128
164
|
url = {https://github.com/citation-file-format/ruby-cff},
|
|
129
|
-
|
|
165
|
+
version = {1.0.0},
|
|
166
|
+
year = {2022}
|
|
130
167
|
}
|
|
131
168
|
```
|
|
132
169
|
|
|
133
170
|
#### APA-like format
|
|
134
171
|
|
|
135
172
|
```
|
|
136
|
-
Haines, R. (
|
|
173
|
+
Haines, R. (2022). Ruby CFF Library (Version 1.0.0) [Computer software]. https://github.com/citation-file-format/ruby-cff
|
|
137
174
|
```
|
|
138
175
|
|
|
139
176
|
#### Citing a paper rather than software
|
|
@@ -145,16 +182,19 @@ cff = CFF::File.read('CITATION.cff')
|
|
|
145
182
|
|
|
146
183
|
cff.to_bibtex(preferred_citation: false)
|
|
147
184
|
cff.to_apalike(preferred_citation: false)
|
|
148
|
-
|
|
149
185
|
```
|
|
150
186
|
|
|
151
187
|
#### A note on citation formats
|
|
152
188
|
|
|
153
|
-
Due to the different expectations of different publication venues, the citation text may need minor tweaking to be used in specific situations. If you spot a major, or general, error in the output
|
|
189
|
+
Due to the different expectations of different publication venues, the citation text may need minor tweaking to be used in specific situations. If you spot a major, or general, error in the output do [let us know](https://github.com/citation-file-format/ruby-cff/issues), but please check against the [BibTex](https://www.bibtex.com/format/) and [APA](https://apastyle.apa.org/style-grammar-guidelines/references) standards first.
|
|
154
190
|
|
|
155
191
|
### Library versions
|
|
156
192
|
|
|
157
|
-
|
|
193
|
+
From version 1.0.0 onwards, the principles of [semantic versioning](https://semver.org/) are applied when numbering releases with new features or breaking changes.
|
|
194
|
+
|
|
195
|
+
### Developing Ruby CFF
|
|
196
|
+
|
|
197
|
+
Please see our [Code of Conduct](https://github.com/citation-file-format/ruby-cff/blob/main/CODE_OF_CONDUCT.md) and our [contributor guidelines](https://github.com/citation-file-format/ruby-cff/blob/main/CONTRIBUTING.md).
|
|
158
198
|
|
|
159
199
|
### Licence
|
|
160
200
|
|
data/Rakefile
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
# Copyright (c) 2018-
|
|
3
|
+
# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
|
|
4
4
|
#
|
|
5
5
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
6
6
|
# you may not use this file except in compliance with the License.
|
|
@@ -15,24 +15,25 @@
|
|
|
15
15
|
# limitations under the License.
|
|
16
16
|
|
|
17
17
|
require 'bundler/gem_tasks'
|
|
18
|
-
require '
|
|
18
|
+
require 'minitest/test_task'
|
|
19
19
|
require 'rdoc/task'
|
|
20
20
|
require 'rubocop/rake_task'
|
|
21
21
|
|
|
22
22
|
task default: :test
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
t.libs << 'lib'
|
|
27
|
-
t.test_files = FileList['test/**/*_test.rb']
|
|
24
|
+
Minitest::TestTask.create do |test|
|
|
25
|
+
test.test_globs = 'test/**/*_test.rb'
|
|
28
26
|
end
|
|
29
27
|
|
|
30
28
|
RDoc::Task.new do |r|
|
|
31
29
|
r.main = 'README.md'
|
|
32
|
-
r.rdoc_files.include(
|
|
30
|
+
r.rdoc_files.include(
|
|
31
|
+
'README.md', 'LICENCE', 'CODE_OF_CONDUCT.md', 'CONTRIBUTING.md',
|
|
32
|
+
'CHANGES.md', 'lib/**/*.rb'
|
|
33
|
+
)
|
|
33
34
|
r.options << '--markup=markdown'
|
|
34
35
|
r.options << '--tab-width=2'
|
|
35
|
-
r.options << "-t Ruby CFF Library version #{::CFF::VERSION}"
|
|
36
|
+
r.options << "-t Ruby CFF Library (version #{::CFF::VERSION})"
|
|
36
37
|
end
|
|
37
38
|
|
|
38
39
|
RuboCop::RakeTask.new
|
data/cff.gemspec
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
# Copyright (c) 2018-
|
|
3
|
+
# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
|
|
4
4
|
#
|
|
5
5
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
6
6
|
# you may not use this file except in compliance with the License.
|
|
@@ -35,7 +35,8 @@ Gem::Specification.new do |spec|
|
|
|
35
35
|
'bug_tracker_uri' => 'https://github.com/citation-file-format/ruby-cff/issues',
|
|
36
36
|
'changelog_uri' => 'https://github.com/citation-file-format/ruby-cff/blob/main/CHANGES.md',
|
|
37
37
|
'documentation_uri' => 'https://citation-file-format.github.io/ruby-cff/',
|
|
38
|
-
'source_code_uri' => 'https://github.com/citation-file-format/ruby-cff'
|
|
38
|
+
'source_code_uri' => 'https://github.com/citation-file-format/ruby-cff',
|
|
39
|
+
'rubygems_mfa_required' => 'true'
|
|
39
40
|
}
|
|
40
41
|
|
|
41
42
|
spec.files = `git ls-files -z`.split("\x0").reject do |f|
|
|
@@ -48,17 +49,17 @@ Gem::Specification.new do |spec|
|
|
|
48
49
|
|
|
49
50
|
spec.required_ruby_version = '>= 2.6'
|
|
50
51
|
|
|
51
|
-
spec.add_runtime_dependency 'json_schema', '~> 0.
|
|
52
|
-
spec.add_runtime_dependency 'language_list', '~> 1.2'
|
|
52
|
+
spec.add_runtime_dependency 'json_schema', '~> 0.20.4'
|
|
53
|
+
spec.add_runtime_dependency 'language_list', '~> 1.2.1'
|
|
53
54
|
|
|
54
|
-
spec.add_development_dependency 'minitest', '~> 5.
|
|
55
|
+
spec.add_development_dependency 'minitest', '~> 5.16.0'
|
|
55
56
|
spec.add_development_dependency 'rake', '~> 13.0'
|
|
56
|
-
spec.add_development_dependency 'rdoc', '~> 6.
|
|
57
|
-
spec.add_development_dependency 'rubocop', '~> 1.
|
|
58
|
-
spec.add_development_dependency 'rubocop-minitest', '~> 0.
|
|
59
|
-
spec.add_development_dependency 'rubocop-performance', '~> 1.
|
|
60
|
-
spec.add_development_dependency 'rubocop-rake', '~> 0.
|
|
61
|
-
spec.add_development_dependency 'simplecov', '
|
|
57
|
+
spec.add_development_dependency 'rdoc', '~> 6.4.0'
|
|
58
|
+
spec.add_development_dependency 'rubocop', '~> 1.35.0'
|
|
59
|
+
spec.add_development_dependency 'rubocop-minitest', '~> 0.21.0'
|
|
60
|
+
spec.add_development_dependency 'rubocop-performance', '~> 1.14.0'
|
|
61
|
+
spec.add_development_dependency 'rubocop-rake', '~> 0.6.0'
|
|
62
|
+
spec.add_development_dependency 'simplecov', '0.18.3'
|
|
62
63
|
spec.add_development_dependency 'simplecov-lcov', '~> 0.8.0'
|
|
63
64
|
spec.add_development_dependency 'test_construct', '~> 2.0'
|
|
64
65
|
end
|
data/lib/cff/citable.rb
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
|
|
4
|
+
#
|
|
5
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
6
|
+
# you may not use this file except in compliance with the License.
|
|
7
|
+
# You may obtain a copy of the License at
|
|
8
|
+
#
|
|
9
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
10
|
+
#
|
|
11
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
12
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
13
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
14
|
+
# See the License for the specific language governing permissions and
|
|
15
|
+
# limitations under the License.
|
|
16
|
+
|
|
17
|
+
require_relative 'formatters'
|
|
18
|
+
|
|
19
|
+
##
|
|
20
|
+
module CFF
|
|
21
|
+
# Methods to enable turning a CFF model or file into a citation.
|
|
22
|
+
#
|
|
23
|
+
# The core functionality is in the `citation` method. In addition, each
|
|
24
|
+
# available output format has a `to_{format}` method generated for it as
|
|
25
|
+
# well, e.g. `to_bibtex` or `to_apalike`. These methods take a single
|
|
26
|
+
# parameter, `preferred_citation:`, which defaults to `true` as in the
|
|
27
|
+
# `citation` method.
|
|
28
|
+
module Citable
|
|
29
|
+
# :call-seq:
|
|
30
|
+
# citation(format, preferred_citation: true) -> String
|
|
31
|
+
#
|
|
32
|
+
# Output this Index in the specified format. Setting
|
|
33
|
+
# `preferred_citation: true` will honour the `preferred_citation` field in
|
|
34
|
+
# the index if one is present (default).
|
|
35
|
+
#
|
|
36
|
+
# `format` can be supplied as a String or a Symbol.
|
|
37
|
+
#
|
|
38
|
+
# Formats that are built-in to Ruby CFF are:
|
|
39
|
+
#
|
|
40
|
+
# * APAlike (e.g. `:apalike`, `'apalike'` or `'APAlike'`)
|
|
41
|
+
# * BibTeX (e.g. `:bibtex`, `'bibtex'` or `'BibTeX'`)
|
|
42
|
+
#
|
|
43
|
+
# *Note:* This method assumes that this Index is valid when called.
|
|
44
|
+
def citation(format, preferred_citation: true)
|
|
45
|
+
formatter = Formatters.formatter_for(format)
|
|
46
|
+
return '' if formatter.nil?
|
|
47
|
+
|
|
48
|
+
formatter.format(model: self, preferred_citation: preferred_citation)
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def self.add_to_format_method(format) # :nodoc:
|
|
52
|
+
method = "to_#{format}"
|
|
53
|
+
return if method_defined?(method)
|
|
54
|
+
|
|
55
|
+
class_eval(
|
|
56
|
+
# def to_bibtex(preferred_citation: true)
|
|
57
|
+
# citation(:bibtex, preferred_citation: preferred_citation)
|
|
58
|
+
# end
|
|
59
|
+
<<-END_TO_FORMAT, __FILE__, __LINE__ + 1
|
|
60
|
+
def #{method}(preferred_citation: true)
|
|
61
|
+
citation(:#{format}, preferred_citation: preferred_citation)
|
|
62
|
+
end
|
|
63
|
+
END_TO_FORMAT
|
|
64
|
+
)
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# Add the formatters we know about already upfront.
|
|
68
|
+
Formatters.formatters.each do |format|
|
|
69
|
+
add_to_format_method(format)
|
|
70
|
+
end
|
|
71
|
+
end
|
|
72
|
+
end
|