cff 0.1.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 8b6e59d2c810ff7f55fac883fa8febd7bda2928c
4
- data.tar.gz: 3e93472087c65a0bf7d57ef038e60ffd48438647
2
+ SHA256:
3
+ metadata.gz: 30519ae0956f0d4221822133c8d638170919f92a3c969af8fc9acf75146f1652
4
+ data.tar.gz: d50b46821a6b7711cadfa8f89628afad29c1c06c0549756c7cbbe2f50fd38507
5
5
  SHA512:
6
- metadata.gz: 7e9af9c7e01db4ffda0371ce140e7c8ed338c2d419cf44d786b093e54e479b1e8dc74d17e7581e98a9298ac10a16c559d802788d764a4ce9792f798c253ad684
7
- data.tar.gz: 59aaa4928118dfb01fd7617c7b6722bb0a7db3274af945926391cd82325de025ca1a88545972621f08368d4b9765642aecd39d1f8a5f2f3862e92aac2cea587d
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
@@ -1,3 +1,5 @@
1
- source "https://rubygems.org"
1
+ # frozen_string_literal: true
2
+
3
+ source 'https://rubygems.org'
2
4
 
3
5
  gemspec
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 [yyyy] [name of copyright owner]
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 manipulating CITATION.cff files.
4
+ A Ruby library for creating, editing, validating and converting CITATION.cff files.
5
5
 
6
- [![Build Status](https://travis-ci.org/hainesr/ruby-cff.svg?branch=master)](https://travis-ci.org/hainesr/ruby-cff)
7
- [![Maintainability](https://api.codeclimate.com/v1/badges/7eaa3890f17664e10bc6/maintainability)](https://codeclimate.com/github/hainesr/ruby-cff/maintainability)
8
- [![Coverage Status](https://coveralls.io/repos/github/hainesr/ruby-cff/badge.svg)](https://coveralls.io/github/hainesr/ruby-cff)
6
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1184077.svg)](https://doi.org/10.5281/zenodo.1184077)
7
+ [![Gem Version](https://badge.fury.io/rb/cff.svg)](https://badge.fury.io/rb/cff)
8
+ [![Tests](https://github.com/citation-file-format/ruby-cff/actions/workflows/ruby.yml/badge.svg)](https://github.com/citation-file-format/ruby-cff/actions/workflows/ruby.yml)
9
+ [![Linter](https://github.com/citation-file-format/ruby-cff/actions/workflows/lint.yml/badge.svg)](https://github.com/citation-file-format/ruby-cff/actions/workflows/lint.yml)
10
+ [![Maintainability](https://api.codeclimate.com/v1/badges/6bb4c661bfb4971260ba/maintainability)](https://codeclimate.com/github/citation-file-format/ruby-cff/maintainability)
11
+ [![Coverage Status](https://coveralls.io/repos/github/citation-file-format/ruby-cff/badge.svg)](https://coveralls.io/github/citation-file-format/ruby-cff)
9
12
 
10
13
  ### Synopsis
11
14
 
12
- This library provides a Ruby interface to manipulate CITATION.cff files. The primary entry points are the Model and File classes.
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
- See the [CITATION.cff documentation](https://citation-file-format.github.io/) for more details.
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
- cff = CFF::Model.new("Ruby CFF Library")
20
- cff.version = 0.1.0
21
- cff.date_released = Date.today
22
- cff.authors << CFF::Person.new("Robert", "Haines")
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("CITATION.cff", cff)
38
+ CFF::File.write('CITATION.cff', model)
25
39
  ```
26
40
 
27
- Will produce a file that looks something like this:
41
+ Which will produce a file that looks something like this:
28
42
 
29
- ```
30
- cff-version: 1.0.3
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).