cff 0.2.0 → 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/CHANGES.md +252 -0
- data/CITATION.cff +83 -0
- data/Gemfile +3 -1
- data/LICENCE +1 -1
- data/README.md +177 -22
- data/Rakefile +17 -12
- data/bin/console +4 -3
- data/cff.gemspec +41 -22
- data/lib/cff.rb +25 -11
- data/lib/cff/entity.rb +35 -25
- data/lib/cff/errors.rb +53 -0
- data/lib/cff/file.rb +209 -18
- data/lib/cff/formatter/apa_formatter.rb +77 -0
- data/lib/cff/formatter/bibtex_formatter.rb +122 -0
- data/lib/cff/formatter/formatter.rb +63 -0
- data/lib/cff/identifier.rb +72 -0
- data/lib/cff/licensable.rb +45 -0
- data/lib/cff/model.rb +223 -89
- data/lib/cff/{model-part.rb → model_part.rb} +17 -9
- data/lib/cff/person.rb +45 -24
- data/lib/cff/reference.rb +564 -0
- data/lib/cff/util.rb +48 -17
- data/lib/cff/validatable.rb +54 -0
- data/lib/cff/version.rb +7 -4
- data/lib/schema/1.2.0.json +1882 -0
- metadata +124 -29
- data/.gitignore +0 -30
- data/.ruby-gemset +0 -1
- data/.ruby-version +0 -1
- data/.travis.yml +0 -20
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: c4c306916ccaa887479febca758c7d8d5e9272229ee9eedb88663649e3d6c15c
|
|
4
|
+
data.tar.gz: 798151267eba0eab166fc104660a5a87f15ecafdd336c0e9819ab9922a58b516
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2834d89f3fac5714b9708cd4c15999c5df41c50bfc9bab3fa6b208cca46fff333b6d619fb7e84cb6faaec5a42219ae3a37db9830c2f788179a926d66e6ac1c33
|
|
7
|
+
data.tar.gz: 82bc7dffa78909c49c0c035ab6b8823852a1ce5e8c9486ce81f09d7a88fb530c09e2a0c486274d282ae963a737bc6cef272dd1be00509c2d65053a6ff1f2c827
|
data/CHANGES.md
ADDED
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
# Changes log for the Ruby CFF Library
|
|
2
|
+
|
|
3
|
+
## Version 0.9.0
|
|
4
|
+
|
|
5
|
+
* Update to final released version of schema 1.2.0.
|
|
6
|
+
* Add `description` field to `Identifier`.
|
|
7
|
+
* Add `Model::read` to parse a CFF file from memory.
|
|
8
|
+
* Add `Model::open`. Same as `read` but can take a block.
|
|
9
|
+
* Override `File#to_yaml`.
|
|
10
|
+
* Allow `File::write` to write File objects.
|
|
11
|
+
* Add `save_as` parameter to `File#write`.
|
|
12
|
+
* Add `Reference::from_cff`.
|
|
13
|
+
* Update CITATION.cff file to reference CFF repo.
|
|
14
|
+
* Fix `File` docs to be explicit about filenames.
|
|
15
|
+
* Validate the filename of a CFF file.
|
|
16
|
+
* Surface the `fail_fast` options on the `File` validatation methods.
|
|
17
|
+
* Reduce json_schema dependency to ~0.20.0.
|
|
18
|
+
* Fix APA-like formatter when a reference is missing a volume.
|
|
19
|
+
* APA: don't emit journal data if there's no journal.
|
|
20
|
+
|
|
21
|
+
## Version 0.8.0
|
|
22
|
+
|
|
23
|
+
* Add a comment field to the File class.
|
|
24
|
+
* Update the CITATION.cff file to add a comment.
|
|
25
|
+
* Document the simple fields in Model.
|
|
26
|
+
* Updating Ruby version and dependencies
|
|
27
|
+
* GitHub Actions for CI
|
|
28
|
+
* Update Gemspec to fix security vulnerabilities
|
|
29
|
+
* Implement BibTeX output
|
|
30
|
+
* Implement APA-like output
|
|
31
|
+
* Update the LICENCE and the file headers.
|
|
32
|
+
* Add a linter Action.
|
|
33
|
+
* Adjust fixtures to reflect custom styles
|
|
34
|
+
* Move latest supported ruby to be >= 2.6.
|
|
35
|
+
* Dynamically create tests
|
|
36
|
+
* Use the new `YAML.safe_load` API form.
|
|
37
|
+
* Add a filename to `CFF::File`.
|
|
38
|
+
* Fix invalid references bug
|
|
39
|
+
* Allow time to be loaded from YAML
|
|
40
|
+
* Add `CFF::File.open` which accepts a block.
|
|
41
|
+
* `Model::new` can now accept a block.
|
|
42
|
+
* `Entity::new` can now accept a block.
|
|
43
|
+
* `Person::new` can now accept a block.
|
|
44
|
+
* `Reference::new` can now accept a block.
|
|
45
|
+
* Update README with new `Model` and `File` APIs.
|
|
46
|
+
* Turn on Actions CI for all branches.
|
|
47
|
+
* Turn Coveralls reporting back on after move to Actions.
|
|
48
|
+
* Use `Last, First` format for BibTeX output.
|
|
49
|
+
* Add `BibtexFormatter::generate_reference`.
|
|
50
|
+
* Change DOI links to https in the APA formatter.
|
|
51
|
+
* Set up a GitHub Action to build and deploy the docs.
|
|
52
|
+
* Add metadata to the gemspec.
|
|
53
|
+
* Generalize authorship of the gem a bit.
|
|
54
|
+
* Document `to_*` formatting methods in `Model`.
|
|
55
|
+
* Add `alias` field to `Person`.
|
|
56
|
+
* `Person` no longer requires `given-names` and `family-names`.
|
|
57
|
+
* The `version` field can be a number or a string.
|
|
58
|
+
* Bump default spec version to 1.2.0.
|
|
59
|
+
* Load and parse the CFF schema.
|
|
60
|
+
* Add validation code and supporting infrastructure.
|
|
61
|
+
* Add validation class methods to `CFF::File`.
|
|
62
|
+
* Handle empty fields in `Reference` when reading from files.
|
|
63
|
+
* Add an `Identifier` type.
|
|
64
|
+
* Add the `identifiers` field to the `Model`.
|
|
65
|
+
* Add the `identifiers` field to `Reference`.
|
|
66
|
+
* Update the key complete CFF file in the tests.
|
|
67
|
+
* Ensure `name-particle` is used in BibTex output.
|
|
68
|
+
* Add `preferred-citation` to the `Model`.
|
|
69
|
+
* Load the `Entity` fields in a `Reference` correctly.
|
|
70
|
+
* Preserve title capitalization in BibTeX output.
|
|
71
|
+
* Add `Licensable` mixin.
|
|
72
|
+
* Wire `Licensable` into `Model`.
|
|
73
|
+
* Wire `Licensable` into `Reference`.
|
|
74
|
+
* Use the SPDX licences list in the schema to cross-check.
|
|
75
|
+
* Protect `Entity` names in BibTeX output with `{}`.
|
|
76
|
+
* Add support for `name-suffix` in BibTeX output.
|
|
77
|
+
* Streamline the APA formatter `format_author` method.
|
|
78
|
+
* Streamline BibTeX `generate_reference` method.
|
|
79
|
+
* Streamline the BibTeX `format_author` method.
|
|
80
|
+
* Update `1.2.0` schema.
|
|
81
|
+
* Add `Formatter::month_and_year_from_date` util method.
|
|
82
|
+
* Add `Formatter::url` util method.
|
|
83
|
+
* Simplify `BibtexFormatter::format`.
|
|
84
|
+
* Simplify and improve the APA formatter.
|
|
85
|
+
* Honour `preferred_citation` when outputting citation text.
|
|
86
|
+
* Only use '[Computer software]' label in APA format for software.
|
|
87
|
+
* Map `Reference` types to BibTeX types when formatting.
|
|
88
|
+
|
|
89
|
+
## Version 0.4.0
|
|
90
|
+
|
|
91
|
+
* Remove unused Util#expand_field method.
|
|
92
|
+
* Changed Model#keywords to be a field type.
|
|
93
|
+
* Model is now a subclass of ModelPart.
|
|
94
|
+
* Document ModelPart and Util just enough.
|
|
95
|
+
* Add Util::normalize_modelpart_array! method.
|
|
96
|
+
* Tighten up checking for empty collections in model.
|
|
97
|
+
* Move the references into the Model fields.
|
|
98
|
+
* Add an in-place actor collection builder method.
|
|
99
|
+
* Move authors and contact to Model fields.
|
|
100
|
+
* Refactor Reference so the actor lists are fields.
|
|
101
|
+
* Remove unused method: Util::build_actor_collection.
|
|
102
|
+
* Remove unused method: Util::expand_array_field.
|
|
103
|
+
* Add rubocop to the development dependencies.
|
|
104
|
+
* Add rubocop configuration files.
|
|
105
|
+
* Add rubocop rake tasks.
|
|
106
|
+
* Many rubocop fixes.
|
|
107
|
+
* Compact ALLOWED_FIELDS lists for consistency.
|
|
108
|
+
* Allow creation of a Reference without a type.
|
|
109
|
+
* Remove unused method: Util.delete_from_hash.
|
|
110
|
+
* Refactor duplicated code into Util.fields_to_hash.
|
|
111
|
+
* Add File#write (instance method).
|
|
112
|
+
* Ensure a model always returns '' for missing fields.
|
|
113
|
+
* Test reading short and minimal CFF files.
|
|
114
|
+
* Cleanup duplicated tests.
|
|
115
|
+
* Don't store dotfiles in the gemfile.
|
|
116
|
+
* Add a CITATION.cff file!
|
|
117
|
+
|
|
118
|
+
## Version 0.3.0
|
|
119
|
+
|
|
120
|
+
* Update badges for new repo location.
|
|
121
|
+
* Add back the coveralls badge for new repo location.
|
|
122
|
+
* Update gemspec with new repo location.
|
|
123
|
+
* Bump version number for 0.3.0 release.
|
|
124
|
+
* Add a Reference model to represent references.
|
|
125
|
+
* Wire the Reference model into Model and File.
|
|
126
|
+
* Add authors field to Reference.
|
|
127
|
+
* Read the author field properly when parsing a Reference.
|
|
128
|
+
* Remove the ModelPart constructor.
|
|
129
|
+
* Add the DOI badge to the README.
|
|
130
|
+
* Add the simple string fields to Reference.
|
|
131
|
+
* Add format field to Reference.
|
|
132
|
+
* Move duplicated builder methods to Util module.
|
|
133
|
+
* Remove the Util module from the public API.
|
|
134
|
+
* Restrict reference type to the defined set.
|
|
135
|
+
* Add Date type fields to the Reference model.
|
|
136
|
+
* Add contact to the Reference model.
|
|
137
|
+
* Add editors to the Reference model.
|
|
138
|
+
* Add editors-series to the Reference model.
|
|
139
|
+
* Add recipients to the Reference model.
|
|
140
|
+
* Add senders to the Reference model.
|
|
141
|
+
* Add translators to the Reference model.
|
|
142
|
+
* Refactor the Reference#fields method for complexity.
|
|
143
|
+
* Refactor the Model#to_yaml method for complexity.
|
|
144
|
+
* Restrict reference status to the defined set.
|
|
145
|
+
* Add languages to the Reference model.
|
|
146
|
+
* Restrict reference licence to the SPDX Licence List.
|
|
147
|
+
* Rename Util array_to_fields to expand_array_field.
|
|
148
|
+
* Add a Util method expand_field.
|
|
149
|
+
* Correctly read in the actor lists from a file.
|
|
150
|
+
* Update quick start example in the README.
|
|
151
|
+
* Add the integer fields to the Reference model.
|
|
152
|
+
* Refactor Reference#fields to cope with single Entities.
|
|
153
|
+
* Add the singular Entity fields to the Reference model.
|
|
154
|
+
* Add issue-date field to the Reference model.
|
|
155
|
+
* Add the keywords field to the Reference model.
|
|
156
|
+
* Refactor keyword list initialization in Reference.
|
|
157
|
+
* Add patent-states field to the Reference model.
|
|
158
|
+
* Refactor Reference#keywords to be a standard field.
|
|
159
|
+
* Refactor Reference#patent_states to be a field.
|
|
160
|
+
* Extend the tests for Reference after the refactor.
|
|
161
|
+
* Normalize Reference types when they are set.
|
|
162
|
+
* Normalize the Reference status when set.
|
|
163
|
+
* Add a note to the README about versioning.
|
|
164
|
+
* Add a CHANGES file.
|
|
165
|
+
|
|
166
|
+
## Version 0.2.0
|
|
167
|
+
|
|
168
|
+
* Add a rubygems version badge to the README.
|
|
169
|
+
* Add older rubies to the CI, but allow failures.
|
|
170
|
+
* Add the licence to the gemspec.
|
|
171
|
+
* Rename the ALLOWED_METHODS list to FIELDS.
|
|
172
|
+
* Send missing methods straight to Model, from File.
|
|
173
|
+
* Fix passing through arguments for missing methods (File).
|
|
174
|
+
* Add a Util module with delete_from_hash as first utility.
|
|
175
|
+
* Move method_to_field to the Util module.
|
|
176
|
+
* Refactor for more complete parsing ability.
|
|
177
|
+
* Freeze the allowed fields constant in Model.
|
|
178
|
+
* Change allowed fields to be more flexible
|
|
179
|
+
* Add abstract to Model.
|
|
180
|
+
* Factor out the process of converting array fields to yaml.
|
|
181
|
+
* Fix test for authors that was split incorrectly.
|
|
182
|
+
* Add contact to Model.
|
|
183
|
+
* Add tests to check capitalized fields are rejected.
|
|
184
|
+
* Refactor model building for maintainability.
|
|
185
|
+
* Add commit to the Model.
|
|
186
|
+
* Add doi to the Model.
|
|
187
|
+
* Add keywords to Model.
|
|
188
|
+
* Fix #11: prevent serialization of empty collections.
|
|
189
|
+
* Add license to Model.
|
|
190
|
+
* Refactor testing simple fields.
|
|
191
|
+
* Add license-url to Model.
|
|
192
|
+
* Simplify parsing the keywords in Model.
|
|
193
|
+
* Refactor testing reading complete CFF file.
|
|
194
|
+
* Add repository* to Model.
|
|
195
|
+
* Add url to Model.
|
|
196
|
+
* Fix #12: typo in README example usage.
|
|
197
|
+
* Add to the quick start example in the README.
|
|
198
|
+
* Create a new base class (ModelPart) for parts of the model.
|
|
199
|
+
* Add ModelPart#method_missing.
|
|
200
|
+
* Add affiliation to Person, and tests for it too.
|
|
201
|
+
* Add address to Entity, and tests for it too.
|
|
202
|
+
* Add accessors for required fields on Person, Entity.
|
|
203
|
+
* Add the rest of the optional fields in Person.
|
|
204
|
+
* Add the rest of the simple fields in Entity.
|
|
205
|
+
* Add the date fields in Entity.
|
|
206
|
+
* Test dates in Entity with text inputs.
|
|
207
|
+
|
|
208
|
+
## Version 0.1.0
|
|
209
|
+
|
|
210
|
+
* Add a code of conduct.
|
|
211
|
+
* Add Travis configuration.
|
|
212
|
+
* Add licence text to all source files.
|
|
213
|
+
* Add a Travis badge to the README.
|
|
214
|
+
* Add a CodeClimate badge to the README.
|
|
215
|
+
* Set up coveralls integration.
|
|
216
|
+
* Add a coveralls badge to the README.
|
|
217
|
+
* Add the current CFF spec version as the default.
|
|
218
|
+
* Add a simple model class.
|
|
219
|
+
* Message doesn't need to be passed to new.
|
|
220
|
+
* Add title to model and wire into default message.
|
|
221
|
+
* Add a method to set the message.
|
|
222
|
+
* Remove the default values on ingestion.
|
|
223
|
+
* Swap requires in main cff file.
|
|
224
|
+
* Only set a default message on construction.
|
|
225
|
+
* Add a File class to read and write CFF files.
|
|
226
|
+
* Switch to using standard accessor for message field.
|
|
227
|
+
* Streamline title output tests.
|
|
228
|
+
* Add a set title method to Model and test it.
|
|
229
|
+
* Turn off line wrapping in Model yaml output.
|
|
230
|
+
* Fix #2. Don't include title in the default message.
|
|
231
|
+
* Test that yaml output doesn't include the header.
|
|
232
|
+
* Write cff from a String or Model.
|
|
233
|
+
* Fix #3. Create a File from either a model or title.
|
|
234
|
+
* When testing file loading, compare to yaml directly.
|
|
235
|
+
* Test the message is loaded correctly into a File.
|
|
236
|
+
* Add version to the Model and File APIs.
|
|
237
|
+
* Add date-released to the Model and File APIs.
|
|
238
|
+
* Fix cff_version test.
|
|
239
|
+
* Move the Model class to a Hash-based implementation.
|
|
240
|
+
* Initialize Model with a title or a Hash.
|
|
241
|
+
* Update the File class to use the new Model class.
|
|
242
|
+
* Use a method whitelist for Model and File.
|
|
243
|
+
* Add a Person model to represent authors.
|
|
244
|
+
* Add an Entity model to represent authors.
|
|
245
|
+
|
|
246
|
+
## About this file
|
|
247
|
+
|
|
248
|
+
This file is, at least in part, generated by the following command:
|
|
249
|
+
|
|
250
|
+
```shell
|
|
251
|
+
$ git log --pretty=format:"* %s" --reverse --no-merges <commit-hash>..
|
|
252
|
+
```
|
data/CITATION.cff
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# This CITATION.cff file was created by ruby-cff (v 0.9.0).
|
|
2
|
+
# Gem: https://rubygems.org/gems/cff
|
|
3
|
+
# CFF: https://citation-file-format.github.io/
|
|
4
|
+
|
|
5
|
+
cff-version: 1.2.0
|
|
6
|
+
message: If you use ruby-cff in your work, please cite it using the following metadata
|
|
7
|
+
title: Ruby CFF Library
|
|
8
|
+
abstract: This library provides a Ruby interface to manipulate Citation File Format files
|
|
9
|
+
authors:
|
|
10
|
+
- family-names: Haines
|
|
11
|
+
given-names: Robert
|
|
12
|
+
orcid: https://orcid.org/0000-0002-9538-7919
|
|
13
|
+
affiliation: The University of Manchester, UK
|
|
14
|
+
- name: The Ruby Citation File Format Developers
|
|
15
|
+
keywords:
|
|
16
|
+
- ruby
|
|
17
|
+
- credit
|
|
18
|
+
- software citation
|
|
19
|
+
- research software
|
|
20
|
+
- software sustainability
|
|
21
|
+
- metadata
|
|
22
|
+
- citation file format
|
|
23
|
+
- CFF
|
|
24
|
+
version: 0.9.0
|
|
25
|
+
doi: 10.5281/zenodo.1184077
|
|
26
|
+
date-released: 2021-08-18
|
|
27
|
+
license: Apache-2.0
|
|
28
|
+
repository-artifact: https://rubygems.org/gems/cff
|
|
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/Gemfile
CHANGED
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
|
|
189
|
+
Copyright (c) 2018-2021 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
|
@@ -1,43 +1,49 @@
|
|
|
1
1
|
# Ruby CFF
|
|
2
|
-
## Robert Haines
|
|
2
|
+
## Robert Haines and The Ruby Citation File Format Developers
|
|
3
3
|
|
|
4
|
-
A Ruby library for
|
|
4
|
+
A Ruby library for creating, editing, validating and converting CITATION.cff files.
|
|
5
5
|
|
|
6
|
+
[](https://doi.org/10.5281/zenodo.1184077)
|
|
6
7
|
[](https://badge.fury.io/rb/cff)
|
|
7
|
-
[](https://github.com/citation-file-format/ruby-cff/actions/workflows/ruby.yml)
|
|
9
|
+
[](https://github.com/citation-file-format/ruby-cff/actions/workflows/lint.yml)
|
|
10
|
+
[](https://codeclimate.com/github/citation-file-format/ruby-cff/maintainability)
|
|
11
|
+
[](https://coveralls.io/github/citation-file-format/ruby-cff)
|
|
10
12
|
|
|
11
13
|
### Synopsis
|
|
12
14
|
|
|
13
|
-
This library provides a Ruby interface to
|
|
15
|
+
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.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
The primary API entry points are the `Model` and `File` classes.
|
|
18
|
+
|
|
19
|
+
See the [CITATION.cff documentation](https://citation-file-format.github.io/) for more details about the Citation File Format.
|
|
20
|
+
|
|
21
|
+
See the [full API documentation](https://citation-file-format.github.io/ruby-cff/) for more details about Ruby CFF.
|
|
16
22
|
|
|
17
23
|
### Quick start
|
|
18
24
|
|
|
25
|
+
You can quickly build and save a CFF model like this:
|
|
26
|
+
|
|
19
27
|
```ruby
|
|
20
|
-
|
|
21
|
-
cff.version =
|
|
22
|
-
cff.date_released = Date.today
|
|
23
|
-
cff.authors << CFF::Person.new(
|
|
24
|
-
cff.license =
|
|
25
|
-
cff.keywords <<
|
|
26
|
-
cff.repository_artifact =
|
|
28
|
+
model = CFF::Model.new('Ruby CFF Library') do |cff|
|
|
29
|
+
cff.version = CFF::VERSION
|
|
30
|
+
cff.date_released = Date.today
|
|
31
|
+
cff.authors << CFF::Person.new('Robert', 'Haines')
|
|
32
|
+
cff.license = 'Apache-2.0'
|
|
33
|
+
cff.keywords << 'ruby' << 'credit' << 'citation'
|
|
34
|
+
cff.repository_artifact = 'https://rubygems.org/gems/cff'
|
|
35
|
+
cff.repository_code = 'https://github.com/citation-file-format/ruby-cff'
|
|
36
|
+
end
|
|
27
37
|
|
|
28
|
-
CFF::File.write(
|
|
38
|
+
CFF::File.write('CITATION.cff', model)
|
|
29
39
|
```
|
|
30
40
|
|
|
31
|
-
|
|
41
|
+
Which will produce a file that looks something like this:
|
|
32
42
|
|
|
33
|
-
```
|
|
34
|
-
cff-version: 1.0
|
|
43
|
+
```yaml
|
|
44
|
+
cff-version: 1.2.0
|
|
35
45
|
message: If you use this software in your work, please cite it using the following metadata
|
|
36
46
|
title: Ruby CFF Library
|
|
37
|
-
version: 0.1.0
|
|
38
|
-
date-released: 2018-02-24
|
|
39
|
-
license: Apache-2.0
|
|
40
|
-
repository-artifact: https://rubygems.org/gems/cff
|
|
41
47
|
authors:
|
|
42
48
|
- family-names: Haines
|
|
43
49
|
given-names: Robert
|
|
@@ -45,8 +51,157 @@ keywords:
|
|
|
45
51
|
- ruby
|
|
46
52
|
- credit
|
|
47
53
|
- citation
|
|
54
|
+
version: 0.9.0
|
|
55
|
+
date-released: 2021-08-18
|
|
56
|
+
license: Apache-2.0
|
|
57
|
+
repository-artifact: https://rubygems.org/gems/cff
|
|
58
|
+
repository-code: https://github.com/citation-file-format/ruby-cff
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`CFF::File` can be used to create a file directly, and it exposes the underlying `CFF::Model` directly. If using a block with `CFF::File::open` the file will get written on closing it:
|
|
62
|
+
|
|
63
|
+
```ruby
|
|
64
|
+
CFF::File.open('CITATION.cff') do |cff|
|
|
65
|
+
cff.version = CFF::VERSION
|
|
66
|
+
cff.date_released = Date.today
|
|
67
|
+
cff.authors << CFF::Person.new('Robert', 'Haines')
|
|
68
|
+
cff.license = 'Apache-2.0'
|
|
69
|
+
cff.keywords << 'ruby' << 'credit' << 'citation'
|
|
70
|
+
cff.repository_artifact = 'https://rubygems.org/gems/cff'
|
|
71
|
+
cff.repository_code = 'https://github.com/citation-file-format/ruby-cff'
|
|
72
|
+
end
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
You can read a CFF file quickly with `CFF::File::read`:
|
|
76
|
+
|
|
77
|
+
```ruby
|
|
78
|
+
cff = CFF::File.read('CITATION.cff')
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
And you can read a CFF file from memory with `CFF::Model::read` or `CFF::Model::open` - as with `CFF::File` a block can be passed in to `open`:
|
|
82
|
+
|
|
83
|
+
```ruby
|
|
84
|
+
cff_string = ::File.read('CITATION.cff')
|
|
85
|
+
cff = CFF::Model.read(cff_string)
|
|
86
|
+
|
|
87
|
+
CFF::Model.open(cff_string) do |cff|
|
|
88
|
+
# Edit cff here...
|
|
89
|
+
end
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
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:
|
|
93
|
+
|
|
94
|
+
```ruby
|
|
95
|
+
require 'open-uri'
|
|
96
|
+
|
|
97
|
+
uri = 'https://raw.githubusercontent.com/citation-file-format/citation-file-format/main/CITATION.cff'
|
|
98
|
+
other_cff = URI.open(uri).read
|
|
99
|
+
|
|
100
|
+
ref = CFF::Reference.from_cff(CFF::Model.read(other_cff))
|
|
101
|
+
|
|
102
|
+
CFF::File.open('CITATION.cff') do |cff|
|
|
103
|
+
cff.references = [ref]
|
|
104
|
+
end
|
|
48
105
|
```
|
|
49
106
|
|
|
107
|
+
### Validating CFF files
|
|
108
|
+
|
|
109
|
+
To quickly validate a file and raise an error on failure, you can use `CFF::File` directly:
|
|
110
|
+
|
|
111
|
+
```ruby
|
|
112
|
+
begin
|
|
113
|
+
CFF::File.validate!('CITATION.cff')
|
|
114
|
+
rescue CFF::ValidationError => e
|
|
115
|
+
# Handle validation errors here...
|
|
116
|
+
end
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Both `CFF::File` and `CFF::Model` have instance methods to validate CFF files as well:
|
|
120
|
+
|
|
121
|
+
```ruby
|
|
122
|
+
cff = CFF::File.read('CITATION.cff')
|
|
123
|
+
begin
|
|
124
|
+
cff.validate!(fail_fast: true)
|
|
125
|
+
rescue CFF::ValidationError => e
|
|
126
|
+
# Handle validation errors here...
|
|
127
|
+
end
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
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).
|
|
131
|
+
|
|
132
|
+
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::Model` provide the `fail_fast` option.
|
|
133
|
+
|
|
134
|
+
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.
|
|
135
|
+
|
|
136
|
+
### Outputting citation text
|
|
137
|
+
|
|
138
|
+
This library can use CFF data to output text suitable for use when citing software. Currently the output formats supported are:
|
|
139
|
+
|
|
140
|
+
* BibTeX; and
|
|
141
|
+
* an APA-like format.
|
|
142
|
+
|
|
143
|
+
You can use this feature as follows:
|
|
144
|
+
```ruby
|
|
145
|
+
cff = CFF::File.read('CITATION.cff')
|
|
146
|
+
|
|
147
|
+
cff.to_bibtex
|
|
148
|
+
cff.to_apalike
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
These methods assume that the CFF data is valid - see the notes on validation above.
|
|
152
|
+
|
|
153
|
+
Assuming the same CFF data as above, the two formats will look something like this:
|
|
154
|
+
|
|
155
|
+
#### BibTeX format
|
|
156
|
+
|
|
157
|
+
```tex
|
|
158
|
+
@misc{Haines_Ruby_CFF_Library_2021,
|
|
159
|
+
author = {Haines, Robert},
|
|
160
|
+
month = {8},
|
|
161
|
+
title = {{Ruby CFF Library}},
|
|
162
|
+
url = {https://github.com/citation-file-format/ruby-cff},
|
|
163
|
+
year = {2021}
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
#### APA-like format
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
Haines, R. (2021). Ruby CFF Library (Version 0.9.0) [Computer software]. https://github.com/citation-file-format/ruby-cff
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
#### Citing a paper rather than software
|
|
174
|
+
|
|
175
|
+
The CFF has been designed with direct citation of software in mind. We'd like software to be considered a first-class research output, like journal articles and conference papers. If you would rather that your citation text points to a paper that describes your software, rather than the software itself, you can use the `preferred-citation` field for that paper. When producing citation text this library will honour `preferred-citation`, if present, by default. If you would like to specify a `preferred-citation` and still produce a direct citation to the software then you can configure the formatter as follows:
|
|
176
|
+
|
|
177
|
+
```ruby
|
|
178
|
+
cff = CFF::File.read('CITATION.cff')
|
|
179
|
+
|
|
180
|
+
cff.to_bibtex(preferred_citation: false)
|
|
181
|
+
cff.to_apalike(preferred_citation: false)
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
#### A note on citation formats
|
|
186
|
+
|
|
187
|
+
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 please [let us know](https://github.com/citation-file-format/ruby-cff/issues).
|
|
188
|
+
|
|
189
|
+
### Library versions
|
|
190
|
+
|
|
191
|
+
Until this library reaches version 1.0.0 the API may be subject to breaking changes. When version 1.0.0 is released, then the principles of [semantic versioning](https://semver.org/) will be applied.
|
|
192
|
+
|
|
50
193
|
### Licence
|
|
51
194
|
|
|
52
195
|
[Apache 2.0](http://www.apache.org/licenses/). See LICENCE for details.
|
|
196
|
+
|
|
197
|
+
### Research notice
|
|
198
|
+
|
|
199
|
+
Please note that this repository is participating in a study into sustainability
|
|
200
|
+
of open source projects. Data will be gathered about this repository for
|
|
201
|
+
approximately the next 12 months, starting from June 2021.
|
|
202
|
+
|
|
203
|
+
Data collected will include number of contributors, number of PRs, time taken to
|
|
204
|
+
close/merge these PRs, and issues closed.
|
|
205
|
+
|
|
206
|
+
For more information, please visit
|
|
207
|
+
[our informational page](https://sustainable-open-science-and-software.github.io/) or download our [participant information sheet](https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf).
|