relaton 3.1.2 → 3.1.4

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
2
  SHA256:
3
- metadata.gz: 4243253e77d9ff955bee5534bb5dd4dc8ace300c68b208d9ad04b0b0243468ff
4
- data.tar.gz: a6737982c68329a90623a75dc407b78a8c6684373c8fe0b44e0b8a7a8bceeca9
3
+ metadata.gz: c2dcd5f1b916c7fe552e39b9376228255e2523385c8da7f91e1193b17ffb58d7
4
+ data.tar.gz: e7331e3f2c069cda9567b518411dcb35e866700151987d9b4d4f14e17ef0f8b5
5
5
  SHA512:
6
- metadata.gz: e3a28aa82a3b155f8222eb981cf814018539dd5b6ea4f33eb308ea034970b2670749cb778a7540767c6df7b526ffe61ed2aeb1d0f8186dfd8b121dd297d25a80
7
- data.tar.gz: 4836365cff31ecc94cb9464d6c321fa8f7770d72bb40adfe963a163cd23b260a77297700596eab3c54d2eb54fbd1d76774786d4bda3f07b6765b461d4cf38f91
6
+ metadata.gz: 65781d01bf2cedf282a94e0275ebf7bcc187fe9d92f029e58768acd782fe05e04f0391ddc579bfce8d7d106242927ad54e9b371b58293dde2651f7e940e201ef
7
+ data.tar.gz: 3f1e0879b62d13c363fd9d34bd02ffdc764a63f7ec8197d1614df983da34bcf02db5086679b68aa391b4fb52d91930be59cc2e58e7719c81ae21a2c9d9de3fa3
data/README.adoc CHANGED
@@ -66,15 +66,25 @@ e.g. `get("ISO 19115-1", "2014", all_parts: true)` is transformed into a referen
66
66
 
67
67
  === Configuration
68
68
 
69
- * `use_api` - `true` if it needs to use an online cache, `false` if not. The default value is `true`.
70
- * `api_host` - URL of an online cache. The default value is https://api.relaton.org.
69
+ * `use_api` - `true` to ask api.relaton.org before the flavor's own fetch on a cache miss; the flavor still answers whatever the API does not. The default value is the `RELATON_USE_API` environment variable (`1`, `true`, `yes` or `on` turn it on), else `false`.
70
+ * `api_host` - URL of the API. The default value is the `RELATON_API_HOST` environment variable, else https://api.relaton.org.
71
+ * `api_timeout` - open and read timeout of an API request, in seconds. The default value is `10`.
72
+ * `offline` - `true` to answer every fetch from the local cache only, with no network request. The default value is the `RELATON_OFFLINE` environment variable, else `false`.
73
+
74
+ The `relaton` command line turns the API on for one run with `--api` and off with `--no-api` (on `relaton fetch` and `relaton collection fetch`); with neither flag it follows `RELATON_USE_API`:
75
+
76
+ [source,sh]
77
+ ----
78
+ relaton fetch "IETF RFC 8341" --api
79
+ RELATON_USE_API=1 relaton fetch "IETF RFC 8341"
80
+ ----
71
81
 
72
82
  [source,ruby]
73
83
  ----
74
84
  require "relaton"
75
85
  => true
76
86
 
77
- Relaton.configure do |conf|
87
+ Relaton::Db.configure do |conf|
78
88
  conf.use_api = true
79
89
  conf.api_host = "https://api.relaton.org"
80
90
  end
@@ -0,0 +1,195 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Relaton
4
+ module Bib
5
+ module Converter
6
+ module Csl
7
+ # CSL-JSON entry -> ItemData. The downgrade direction: a CSL record
8
+ # is a flat citation, so fields it does not express are left out
9
+ # rather than invented. The mirror of Converter::Bibtex::FromBibtex.
10
+ class FromCsl
11
+ # The reverse of ENTRY_TYPES for the types the export emits; any
12
+ # other CSL type is kept as written.
13
+ TYPES = {
14
+ "article-journal" => "article", "chapter" => "inbook",
15
+ "paper-conference" => "inproceedings", "webpage" => "webresource",
16
+ }.freeze
17
+
18
+ # @param entry [Hash] one CSL-JSON entry
19
+ def initialize(entry)
20
+ @entry = entry
21
+ end
22
+
23
+ # @return [Relaton::Bib::ItemData]
24
+ def transform # rubocop:disable Metrics/MethodLength
25
+ ItemData.new(
26
+ id: @entry["id"],
27
+ docidentifier: fetch_docid,
28
+ type: fetch_type,
29
+ title: fetch_title,
30
+ contributor: fetch_contributor,
31
+ date: fetch_date,
32
+ abstract: fetch_abstract,
33
+ extent: fetch_extent,
34
+ edition: fetch_edition,
35
+ series: fetch_series,
36
+ source: fetch_source,
37
+ language: fetch_language,
38
+ keyword: fetch_keyword,
39
+ relation: fetch_relation,
40
+ )
41
+ end
42
+
43
+ private
44
+
45
+ # @return [Array<Relaton::Bib::Docidentifier>]
46
+ def fetch_docid
47
+ docid = [Docidentifier.new(content: @entry["id"].to_s, primary: true)]
48
+ docid << Docidentifier.new(content: @entry["ISBN"].to_s, type: "isbn") if @entry["ISBN"]
49
+ docid << Docidentifier.new(content: @entry["ISSN"].to_s, type: "issn") if @entry["ISSN"]
50
+ docid
51
+ end
52
+
53
+ # @return [String, nil]
54
+ def fetch_type
55
+ TYPES[@entry["type"]] || @entry["type"]
56
+ end
57
+
58
+ # @return [Array<Relaton::Bib::Title>]
59
+ def fetch_title
60
+ return [] unless @entry["title"]
61
+
62
+ [Title.new(type: "main", content: @entry["title"])]
63
+ end
64
+
65
+ # @return [Array<Relaton::Bib::Contributor>]
66
+ def fetch_contributor
67
+ contribs = []
68
+ fetch_person("author") { |c| contribs << c }
69
+ fetch_person("editor") { |c| contribs << c }
70
+
71
+ return contribs unless @entry["publisher"]
72
+
73
+ contribs << Contributor.new(
74
+ organization: Organization.new(name: [TypedLocalizedString.new(content: @entry["publisher"])]),
75
+ role: [Contributor::Role.new(type: "publisher")],
76
+ )
77
+ contribs
78
+ end
79
+
80
+ # CSL names are {family:, given:} or a bare {literal:}.
81
+ #
82
+ # @param role [String] contributor role
83
+ def fetch_person(role, &_)
84
+ Array(@entry[role]).each do |name|
85
+ yield Contributor.new(person: Person.new(name: build_name(name)), role: [Contributor::Role.new(type: role)])
86
+ end
87
+ end
88
+
89
+ # @param name [Hash] CSL name variable
90
+ # @return [Relaton::Bib::FullName]
91
+ def build_name(name)
92
+ return FullName.new(completename: LocalizedString.new(content: name["literal"])) if name["literal"]
93
+
94
+ fore = name["given"].to_s.split
95
+ FullName.new(
96
+ surname: LocalizedString.new(content: name["family"].to_s),
97
+ forename: fore.map { |fn| FullNameType::Forename.new(content: fn) },
98
+ )
99
+ end
100
+
101
+ # @return [Array<Relaton::Bib::Date>]
102
+ def fetch_date
103
+ { "issued" => "published", "accessed" => "accessed" }.filter_map do |field, type|
104
+ parts = @entry.dig(field, "date-parts")&.first
105
+ next unless parts
106
+
107
+ Bib::Date.new(type: type, at: iso_date(parts))
108
+ end
109
+ end
110
+
111
+ # @param parts [Array<Integer>] [year], [year, month] or [year, month, day]
112
+ # @return [String]
113
+ def iso_date(parts)
114
+ format("%04d", parts[0]).tap do |iso|
115
+ iso << "-%02d" % parts[1] if parts[1]
116
+ iso << "-%02d" % parts[2] if parts[2]
117
+ end
118
+ end
119
+
120
+ # @return [Array<Relaton::Bib::Abstract>]
121
+ def fetch_abstract
122
+ return [] unless @entry["abstract"]
123
+
124
+ [Abstract.new(content: @entry["abstract"])]
125
+ end
126
+
127
+ # @return [Array<Relaton::Bib::Extent>]
128
+ def fetch_extent
129
+ locs = []
130
+ locs << Locality.new(type: "volume", reference_from: @entry["volume"].to_s) if @entry["volume"]
131
+ if @entry["page"]
132
+ from, to = @entry["page"].to_s.split("-", 2)
133
+ locs << Locality.new(type: "page", reference_from: from, reference_to: to)
134
+ end
135
+ locs.any? ? [Extent.new(locality: locs)] : []
136
+ end
137
+
138
+ # @return [Relaton::Bib::Edition, nil]
139
+ def fetch_edition
140
+ Edition.new(content: @entry["edition"].to_s) if @entry["edition"]
141
+ end
142
+
143
+ # @return [Array<Relaton::Bib::Series>]
144
+ # container-title is the journal for article types and the book for
145
+ # chapters; the chapter shape maps to partOf, the journal shape to
146
+ # a series — the same split FromBibtex makes for journal/booktitle.
147
+ def fetch_series
148
+ return [] unless container_title && fetch_type != "inbook"
149
+
150
+ [Series.new(
151
+ type: "journal",
152
+ title: Title.new(content: container_title),
153
+ number: @entry["number"]&.to_s,
154
+ )]
155
+ end
156
+
157
+ # @return [Array<Relaton::Bib::Uri>]
158
+ def fetch_source
159
+ source = []
160
+ source << Uri.new(type: "src", content: @entry["URL"]) if @entry["URL"]
161
+ source << Uri.new(type: "doi", content: @entry["DOI"]) if @entry["DOI"]
162
+ source
163
+ end
164
+
165
+ # @return [Array<String>]
166
+ def fetch_language
167
+ return [] unless @entry["language"]
168
+
169
+ sub = @entry["language"].split("-").first
170
+ [Iso639[sub]&.alpha2 || sub]
171
+ end
172
+
173
+ # @return [Array<Relaton::Bib::Keyword>]
174
+ def fetch_keyword
175
+ Array(@entry["keyword"]).map do |kw|
176
+ Keyword.new(vocab: LocalizedString.new(content: kw))
177
+ end
178
+ end
179
+
180
+ # @return [Array<Relaton::Bib::Relation>]
181
+ def fetch_relation
182
+ return [] unless container_title && fetch_type == "inbook"
183
+
184
+ ttl = Title.new(type: "main", content: container_title)
185
+ [Relation.new(type: "partOf", bibitem: ItemData.new(title: [ttl]))]
186
+ end
187
+
188
+ def container_title
189
+ @entry["container-title"]
190
+ end
191
+ end
192
+ end
193
+ end
194
+ end
195
+ end
@@ -2,6 +2,8 @@
2
2
 
3
3
  require "yeptris"
4
4
 
5
+ require_relative "csl/from_csl"
6
+
5
7
 
6
8
  module Relaton
7
9
  module Bib
@@ -21,6 +23,16 @@ module Relaton
21
23
  Renderer.new(item).to_s
22
24
  end
23
25
 
26
+ # CSL-JSON string -> Hash{String=>ItemData}
27
+ def self.to_item(csl_str)
28
+ entries = ::Yeptris::JSON.load(csl_str)
29
+ entries.reduce({}) do |h, entry|
30
+ item = FromCsl.new(entry).transform
31
+ h[item.id.to_s] = item
32
+ h
33
+ end
34
+ end
35
+
24
36
  class Renderer
25
37
  def initialize(item)
26
38
  @item = item
@@ -97,7 +109,7 @@ module Relaton
97
109
  def published_year
98
110
  date = Array(@item.date).find { |d| %w[published issued].include?(d.type.to_s) } || @item.date.first
99
111
  value = date && (date.at || date.from || date.to)
100
- value.to_s[/\d{4}/]
112
+ value.to_s[/\d{4}/] || ""
101
113
  end
102
114
 
103
115
  def source_uri
@@ -82,7 +82,10 @@ module Relaton
82
82
  # @return [Relaton::Bibdata, Relaton::Bibcollection]
83
83
  def new_bib_item_class(item)
84
84
  if item.is_a?(Hash)
85
- if item["items"]
85
+ # `#to_h` writes a nested collection as `{"root" => …}`.
86
+ if item["root"].is_a?(Hash)
87
+ ::Relaton::Bibcollection.new(item["root"])
88
+ elsif item["items"]
86
89
  ::Relaton::Bibcollection.new(item)
87
90
  else
88
91
  bibitem = ::Relaton::Cli::YAMLConvertor.convert_single_file item
@@ -0,0 +1,171 @@
1
+ require "fileutils"
2
+ require "time"
3
+ require "yaml"
4
+ require "lutaml/store"
5
+ require_relative "../bibcollection"
6
+ require_relative "util"
7
+
8
+ module Relaton
9
+ module Cli
10
+ # The collections of `relaton collection` (relaton#549): one lutaml-store
11
+ # FileSystem store under `<dir>/v2/`, keyed by the collection name the
12
+ # user types. Each value is the collection's YAML (`{"root" => …}`, as
13
+ # `Bibcollection#to_h` makes it) with a top-level `updated` time, so the
14
+ # data file is the same YAML an older relaton wrote.
15
+ #
16
+ # lutaml-store is the only storage layer, as for `Db::Cache` (relaton#548):
17
+ # its lock makes a read-modify-write atomic between threads and processes,
18
+ # and its rename makes a write atomic. Nothing here builds a path from a
19
+ # name or takes a lock of its own. The one raw IO is the one-time move of
20
+ # the flat files an older relaton wrote directly in `<dir>`: each is
21
+ # imported, then moved to `<dir>-v1.bak/`, never deleted.
22
+ class CollectionStore
23
+ LAYOUT = "v2".freeze
24
+ UPDATED = "updated".freeze
25
+
26
+ attr_reader :dir
27
+
28
+ # @param dir [String] the collections directory
29
+ def initialize(dir)
30
+ @dir = dir
31
+ @store = Lutaml::Store::BasicStore.new(
32
+ adapter_type: :filesystem,
33
+ adapter_options: { path: File.join(dir, LAYOUT), extension: ".yaml",
34
+ integrity_checks: false,
35
+ create_directories: false },
36
+ cache: { enabled: false },
37
+ )
38
+ move_flat_files
39
+ end
40
+
41
+ # @param pattern [String] a glob over the names (`--collection`)
42
+ # @return [Array<String>] the matching names, sorted
43
+ def names(pattern = "*")
44
+ @store.keys.select { |name| File.fnmatch pattern, name }.sort
45
+ end
46
+
47
+ # @param name [String]
48
+ def exist?(name)
49
+ @store.exists? name
50
+ end
51
+
52
+ # @param name [String]
53
+ # @return [Relaton::Bibcollection, nil]
54
+ def get(name)
55
+ hash = read name
56
+ Relaton::Bibcollection.new hash["root"] if hash
57
+ end
58
+
59
+ # @param name [String]
60
+ # @return [Time, nil] when the collection was last written
61
+ def updated(name)
62
+ time = read(name)&.dig UPDATED
63
+ Time.iso8601 time if time
64
+ end
65
+
66
+ # @param name [String]
67
+ # @return [Integer, nil] the size of the stored collection, in bytes
68
+ def size(name)
69
+ @store.get(name)&.bytesize
70
+ end
71
+
72
+ # @param name [String]
73
+ # @param coll [Relaton::Bibcollection]
74
+ # @return [Boolean] false when the store already holds the name
75
+ def create(name, coll)
76
+ @store.adapter.transaction do
77
+ next false if @store.exists? name
78
+
79
+ @store.set name, encode(coll.to_h)
80
+ true
81
+ end
82
+ end
83
+
84
+ # Atomic read-modify-write under the store's exclusive lock.
85
+ #
86
+ # @param name [String]
87
+ # @yieldparam coll [Relaton::Bibcollection, nil] nil when it is missing
88
+ # @yieldreturn [Relaton::Bibcollection]
89
+ def update(name)
90
+ @store.update(name) do |value|
91
+ hash = decode value if value
92
+ coll = hash && Relaton::Bibcollection.new(hash["root"])
93
+ encode yield(coll).to_h
94
+ end
95
+ end
96
+
97
+ private
98
+
99
+ # @return [Hash, nil]
100
+ def read(name)
101
+ value = @store.get name
102
+ decode value if value
103
+ end
104
+
105
+ def decode(value)
106
+ YAML.safe_load value, permitted_classes: [Date, Time, Symbol],
107
+ aliases: true
108
+ end
109
+
110
+ def encode(hash, updated = Time.now)
111
+ hash.merge(UPDATED => updated.utc.iso8601).to_yaml
112
+ end
113
+
114
+ # A flat collection file is imported unless the store already holds its
115
+ # name, and then moved to the backup either way, under the store's lock
116
+ # so two processes do not move one file. The scan runs again inside the
117
+ # lock: another process can have moved the files first.
118
+ def move_flat_files
119
+ return if flat_collections.empty?
120
+
121
+ @store.adapter.transaction do
122
+ flat_collections(warn: false).each do |name, path, hash|
123
+ if @store.exists? name
124
+ Util.warn "collections #{dir}: `#{name}` is in the store; " \
125
+ "the flat file is not imported, moved to #{backup path}"
126
+ else
127
+ @store.set name, encode(hash, File.mtime(path))
128
+ Util.info "collections #{dir}: `#{name}` imported, the flat " \
129
+ "file moved to #{backup path}"
130
+ end
131
+ end
132
+ end
133
+ end
134
+
135
+ # @param warn [Boolean] warn about a file that is not valid YAML
136
+ # @return [Array<Array(String, String, Hash)>] name, path and YAML of
137
+ # each file directly in the directory that holds a collection
138
+ def flat_collections(warn: true)
139
+ return [] unless Dir.exist? dir
140
+
141
+ Dir.children(dir).sort.filter_map do |name|
142
+ path = File.join dir, name
143
+ next unless File.file?(path) && !name.start_with?(".")
144
+
145
+ hash = YAML.safe_load File.read(path, encoding: "UTF-8"),
146
+ permitted_classes: [Date, Time, Symbol],
147
+ aliases: true
148
+ [name, path, hash] if hash.is_a?(Hash) && hash["root"].is_a?(Hash)
149
+ rescue Psych::Exception, ArgumentError => e
150
+ Util.warn "the file `#{path}` isn't a collection: #{e.message}" if warn
151
+ nil
152
+ rescue Errno::ENOENT
153
+ nil # another process moved it
154
+ end
155
+ end
156
+
157
+ # Moves a file to `<dir>-v1.bak/`; a name the backup already holds
158
+ # takes a numeric suffix.
159
+ # @return [String] the backup path
160
+ def backup(path)
161
+ bak = "#{File.expand_path dir}-v1.bak" # `dir/` must not put it inside
162
+ FileUtils.mkdir_p bak
163
+ target = File.join bak, File.basename(path)
164
+ n = 0
165
+ target = File.join(bak, "#{File.basename path}.#{n += 1}") while File.exist? target
166
+ FileUtils.mv path, target
167
+ target
168
+ end
169
+ end
170
+ end
171
+ end
@@ -2,6 +2,7 @@ require "date"
2
2
  require "tmpdir"
3
3
  require "shellwords"
4
4
  require "pubid"
5
+ require_relative "util"
5
6
  require_relative "relaton_file"
6
7
  require_relative "xml_convertor"
7
8
  require_relative "yaml_convertor"
@@ -58,10 +59,14 @@ module Relaton
58
59
  option :"publication-date-after",
59
60
  desc: "Fetch only documents published after the specified date " \
60
61
  "(e.g. 2002, 2002-01, or 2002-01-01)"
62
+ option :api, type: :boolean, desc: Relaton::Cli::API_OPTION_DESC
61
63
 
62
64
  def fetch(code)
65
+ api_was = apply_api_option options
63
66
  io = IO.new($stdout.fcntl(::Fcntl::F_DUPFD), mode: "w:UTF-8")
64
67
  io.puts(fetch_document(code, options) || supported_type_message)
68
+ ensure
69
+ restore_api_option api_was
65
70
  end
66
71
 
67
72
  desc "Metanorma-XML-File / Directory Relaton-XML-Directory",
@@ -343,6 +348,26 @@ module Relaton
343
348
  "Invalid date range: --publication-date-after (#{date_after}) must be before --publication-date-before (#{date_before})."
344
349
  end
345
350
 
351
+ # `--api` / `--no-api` (relaton#535) sets the API tier for this command;
352
+ # no flag keeps the configuration (RELATON_USE_API, else off). Offline
353
+ # mode still makes no request. The command restores the value it
354
+ # returns (#restore_api_option), so a caller that runs the CLI in its
355
+ # own process keeps its configuration.
356
+ #
357
+ # @return [Boolean, nil] the configured value, to restore
358
+ def apply_api_option(options)
359
+ config = Relaton::Db.configuration
360
+ was = config.use_api
361
+ config.use_api = options[:api] unless options[:api].nil?
362
+ was
363
+ end
364
+
365
+ # @param was [Boolean, nil] what #apply_api_option returned; nil when
366
+ # the command stopped before it
367
+ def restore_api_option(was)
368
+ Relaton::Db.configuration.use_api = was unless was.nil?
369
+ end
370
+
346
371
  # @param code [String]
347
372
  # @param options [Hash]
348
373
  # @option options [String] :type
@@ -351,7 +376,9 @@ module Relaton
351
376
  # @return [String, nil]
352
377
  def fetch_document(code, options) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize,Metrics/MethodLength
353
378
  year = options[:year]&.to_s
379
+ # `api` is the CLI's switch (#apply_api_option), not a fetch option.
354
380
  dup_opts = options.dup.transform_keys { |k| k.to_s.gsub("-", "_").to_sym }
381
+ dup_opts.delete :api
355
382
  %i[publication_date_before publication_date_after].each do |key|
356
383
  dup_opts[key] = parse_date_option(dup_opts[key], key.to_s.tr("_", "-").prepend("--")) if dup_opts[key]
357
384
  end
@@ -371,7 +398,9 @@ module Relaton
371
398
  nil
372
399
  rescue Pubid::Errors::Error
373
400
  %("#{code}" is not a recognized standards identifier)
374
- rescue Relaton::RequestError => e
401
+ rescue Relaton::RequestError, Relaton::NotInLocalStoreError => e
402
+ # A transport failure, or offline mode with no stored entry
403
+ # (relaton#536): print the reason instead of a backtrace.
375
404
  e.message
376
405
  end
377
406