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