cff 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3516244b4f8ca79e358adb6a561ea0d1007590b1fc34686eff2566444e465381
-  data.tar.gz: 6ad965bc59a6acf7cfa1a0737ed97bbd994e4fabdb64551eb7bdef6d32411534
+  metadata.gz: aa0896639724d0e82551bf84fde9801a00974dac14e120dafa51b53bc07c33cb
+  data.tar.gz: 0ef577895dff069272703c4c063dc5a84e1e484be6c23ce696592803093c43f7
 SHA512:
-  metadata.gz: 822d9b5f9e260d6bec6bbf9fa2891951b10319feca11f5c899431c86143fcdbde0b874ec9fcd598307ffd5b731578f8979d712375f65cfd7092617e5bd3dcf02
-  data.tar.gz: 122e43d2a21f50b897204e15d4d497cd95cea23a0de1d25a6efc744ca4316e9c5c09fab681e572e8bf66900a4bd40bcbfdf34ecb19e42168c484ca3bbf852d66
+  metadata.gz: 63ae9c19849721bb92af374493b8930d75d7bb3bfbbc6e14a8f1fad0bbbf39064c635f5c03f5d2828bc507b33f65dea69d194a640f6be212bf6088fc3238b9f0
+  data.tar.gz: 5101768a4a0ab8de6176ba2506c98ad5efce62f517f34146feaa8a114939e2154f415ac1cdb4162e4b7407c7bdf3e3bdba1f8c7b06c4b5f714b68f620f402bc6

data/CHANGES.md

@@ -1,5 +1,15 @@
 # Changes log for the Ruby CFF Library
 
+## 1.3.0
+
+* Abstract out parsing YAML.
+* Turn on underlying support for YAML anchors/aliases.
+
+## 1.2.0
+
+* Always treat dates as Ruby Date objects.
+* BibTeX: escape special characters ($%&_#{}).
+
 ## 1.1.0
 
 * BibTeX: output months as three letter abbreviations.

data/CITATION.cff

@@ -1,4 +1,4 @@
-# This CITATION.cff file was created by ruby-cff (v 1.1.0).
+# This CITATION.cff file was created by ruby-cff (v 1.3.0).
 # Gem: https://rubygems.org/gems/cff
 # CFF: https://citation-file-format.github.io/
 
@@ -21,9 +21,9 @@ keywords:
 - metadata
 - citation file format
 - CFF
-version: 1.1.0
+version: 1.3.0
 doi: 10.5281/zenodo.1184077
-date-released: 2023-04-10
+date-released: 2024-10-26
 license: Apache-2.0
 repository-artifact: https://rubygems.org/gems/cff
 repository-code: https://github.com/citation-file-format/ruby-cff

data/LICENCE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+   Copyright (c) 2018-2024 The Ruby Citation File Format Developers.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -122,6 +122,30 @@ CFF::File.open('CITATION.cff') do |cff|
 end
 ```
 
+#### Notes on CFF files with YAML anchors and aliases
+
+Ruby CFF can read files that use YAML anchors and aliases. An anchor (`&<label>`) identifies a section of your file for reuse elsewhere. An alias (`*<label>`) is then used to mark where you want that section to be repeated. In this example, the `&authors` anchor marks an author list for reuse wherever the `*authors` alias is used:
+
+```yaml
+cff-version: 1.2.0
+title: Ruby CFF Library
+authors: &authors
+- family-names: Haines
+  given-names: Robert
+  affiliation: The University of Manchester, UK
+
+...
+
+references:
+  - type: software
+    title: Citation File Format
+    authors: *authors
+```
+
+Ruby uses a single object to represent all aliases of an anchor. This means that once the above has been read in by Ruby CFF, if you add an author to either the top-level author list, or the author list in the reference, the new author will appear in both places. With this in mind, you should only use anchors and aliases where the relationship between sections is such that you are sure that exact repetition will always make sense.
+
+When saving CFF files that use anchors and aliases the underlying YAML library will not preserve their names. For example, if the above is loaded into Ruby CFF and then immediately saved `&authors`/`*authors` will most likely become `&1`/`*1`.
+
 ### Validating CFF files
 
 To quickly validate a file and raise an error on failure, you can use `CFF::File` directly:
@@ -203,7 +227,7 @@ cff.to_apalike(preferred_citation: false)
 
 #### A note on citation formats
 
-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.
+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.
 
 ### Library versions
 

data/lib/cff/file.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2024 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,7 +19,6 @@ require_relative 'index'
 require_relative 'version'
 
 require 'date'
-require 'yaml'
 
 ##
 module CFF
@@ -71,9 +70,7 @@ module CFF
       content = ::File.read(file)
       comment = File.parse_comment(content)
 
-      new(
-        file, YAML.safe_load(content, permitted_classes: [Date, Time]), comment
-      )
+      new(file, Util.parse_yaml(content), comment)
     end
 
     # :call-seq:
@@ -91,7 +88,7 @@ module CFF
       if ::File.exist?(file)
         content = ::File.read(file)
         comment = File.parse_comment(content)
-        yaml = YAML.safe_load(content, permitted_classes: [Date, Time])
+        yaml = Util.parse_yaml(content)
       else
         comment = CFF_COMMENT
         yaml = ''

data/lib/cff/formatters/bibtex.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2024 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -45,13 +45,17 @@ module CFF
         month.downcase unless month.nil?
       end.freeze
 
+      # We need to escape these characters in titles and names, as per
+      # https://tex.stackexchange.com/questions/34580/escape-character-in-latex
+      ESCAPE_CHARS = Regexp.new(/([&%$#_{}])/)
+
       def self.format(model:, preferred_citation: true) # rubocop:disable Metrics
         model = select_and_check_model(model, preferred_citation)
         return if model.nil?
 
         values = {}
         values['author'] = actor_list(model.authors)
-        values['title'] = "{#{model.title}}"
+        values['title'] = "{#{l(model.title)}}"
 
         publication_type = bibtex_type(model)
         publication_data_from_model(model, publication_type, values)
@@ -79,7 +83,7 @@ module CFF
       def self.publication_data_from_model(model, type, fields)
         ENTRY_TYPE_MAP[type].each do |field|
           if model.respond_to?(field)
-            fields[field] = model.send(field).to_s
+            fields[field] = l(model.send(field).to_s)
           else
             field = field.chomp('!')
             fields[field] = send("#{field}_from_model", model)
@@ -108,9 +112,9 @@ module CFF
       # BibTeX 'institution' could be grabbed from an author's affiliation, or
       # provided explicitly.
       def self.institution_from_model(model)
-        return model.institution.name unless model.institution.empty?
+        return l(model.institution.name) unless model.institution.empty?
 
-        model.authors.first.affiliation
+        l(model.authors.first.affiliation)
       end
 
       # BibTeX 'school' is CFF 'institution'.
@@ -125,7 +129,7 @@ module CFF
 
       # BibTeX 'booktitle' is CFF 'collection-title'.
       def self.booktitle_from_model(model)
-        model.collection_title
+        l(model.collection_title)
       end
 
       # BibTeX 'editor' is CFF 'editors' or 'editors-series'.
@@ -138,11 +142,11 @@ module CFF
       end
 
       def self.publisher_from_model(model)
-        model.publisher.empty? ? '' : model.publisher.name
+        model.publisher.empty? ? '' : l(model.publisher.name)
       end
 
       def self.series_from_model(model)
-        model.conference.empty? ? '' : model.conference.name
+        model.conference.empty? ? '' : l(model.conference.name)
       end
 
       # If we're citing a conference paper, try and use the date of the
@@ -182,9 +186,9 @@ module CFF
         end
       end
 
-      def self.format_actor(author)
-        return "{#{author.name}}" if author.is_a?(Entity)
-        return author.alias if author.family_names.empty? && author.given_names.empty?
+      def self.format_actor(author) # rubocop:disable Metrics/AbcSize
+        return "{#{l(author.name)}}" if author.is_a?(Entity)
+        return l(author.alias) if author.family_names.empty? && author.given_names.empty?
 
         particle =
           author.name_particle.empty? ? '' : "#{author.name_particle} "
@@ -209,6 +213,12 @@ module CFF
 
         Util.parameterize(reference)
       end
+
+      # Escape a string to preserve special characters in LaTeX output.
+      # Used in many places, so short method name to preserve reading flow.
+      def self.l(string)
+        string.gsub(ESCAPE_CHARS, '\\\\\1')
+      end
     end
   end
 end

data/lib/cff/formatters/formatter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2023 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -67,16 +67,9 @@ module CFF
       end
 
       def self.month_and_year_from_date(value)
-        if value.is_a?(Date)
-          [value.month, value.year].map(&:to_s)
-        else
-          begin
-            date = Date.parse(value.to_s)
-            [date.month, date.year].map(&:to_s)
-          rescue ArgumentError
-            ['', '']
-          end
-        end
+        return ['', ''] unless value.is_a?(Date)
+
+        [value.month, value.year].map(&:to_s)
       end
 
       # CFF 'pages' is the number of pages, which has no equivalent in BibTeX

data/lib/cff/index.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2024 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -25,8 +25,6 @@ require_relative 'schema'
 require_relative 'validatable'
 require_relative 'citable'
 
-require 'yaml'
-
 ##
 module CFF
   # Index is the core data structure for a CITATION.cff file. It can be
@@ -100,7 +98,7 @@ module CFF
     #
     # Read a CFF Index from a String and parse it for subsequent manipulation.
     def self.read(index)
-      new(YAML.safe_load(index, permitted_classes: [Date, Time]))
+      new(Util.parse_yaml(index))
     end
 
     # :call-seq:

data/lib/cff/model_part.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2023 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -59,23 +59,57 @@ module CFF
       symbols.each do |symbol|
         field = symbol.to_s.tr('_', '-')
 
-        class_eval(
-          # def date_end=(date)
-          #   date = (date.is_a?(Date) ? date.dup : Date.parse(date))
-          #
-          #   @fields['date-end'] = date
-          # end
-          <<-END_SETTER, __FILE__, __LINE__ + 1
-            def #{symbol}=(date)
-              date = (date.is_a?(Date) ? date.dup : Date.parse(date))
-
-              @fields['#{field}'] = date
-            end
-          END_SETTER
-        )
+        date_getter(symbol, field)
+        date_setter(symbol, field)
       end
     end
 
+    def self.date_getter(symbol, field)
+      class_eval(
+        # def date_end
+        #   date = @fields['date-end']
+        #   return date if date.is_a?(Date)
+        #
+        #   begin
+        #     Date.parse(date)
+        #   rescue
+        #     ''
+        #   end
+        # end
+        <<-END_GETTER, __FILE__, __LINE__ + 1
+          def #{symbol}
+            date = @fields['#{field}']
+            return date if date.is_a?(Date)
+
+            begin
+              Date.parse(date)
+            rescue
+              ''
+            end
+          end
+        END_GETTER
+      )
+    end
+
+    def self.date_setter(symbol, field)
+      class_eval(
+        # def date_end=(date)
+        #   date = (date.is_a?(Date) ? date.dup : Date.parse(date))
+        #
+        #   @fields['date-end'] = date
+        # end
+        <<-END_SETTER, __FILE__, __LINE__ + 1
+          def #{symbol}=(date)
+            date = (date.is_a?(Date) ? date.dup : Date.parse(date))
+
+            @fields['#{field}'] = date
+          end
+        END_SETTER
+      )
+    end
+
+    private_class_method :date_getter, :date_setter
+
     private
 
     def method_to_field(name)

data/lib/cff/util.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2018-2022 The Ruby Citation File Format Developers.
+# Copyright (c) 2018-2024 The Ruby Citation File Format Developers.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@ require_relative 'person'
 require_relative 'version'
 
 require 'rubygems'
+require 'yaml'
 
 ##
 module CFF
@@ -30,6 +31,10 @@ module CFF
 
     module_function
 
+    def parse_yaml(string)
+      YAML.safe_load(string, aliases: true, permitted_classes: [Date, Time])
+    end
+
     def update_cff_version(version)
       return '' if version.nil? || version.empty?
 
@@ -44,6 +49,8 @@ module CFF
     # is a Person or Entity. This isn't perfect, but works 99.99% I think.
     def build_actor_collection!(source)
       source.map! do |s|
+        next s if s.is_a?(Person) || s.is_a?(Entity)
+
         s.has_key?('name') ? Entity.new(s) : Person.new(s)
       end
     end

data/lib/cff/version.rb

@@ -17,7 +17,7 @@
 ##
 module CFF
   # :nodoc:
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
   DEFAULT_SPEC_VERSION = '1.2.0'
   MIN_VALIDATABLE_VERSION = '1.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cff
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Robert Haines
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-10 00:00:00.000000000 Z
+date: 2024-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schema
@@ -242,7 +242,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.23
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: A Ruby library for manipulating CITATION.cff files.