Class: YAML_LD::API

Inherits:
JSON::LD::API
  • Object
show all
Defined in:
lib/yaml_ld/api.rb

Overview

A YAML-LD processor based on JSON-LD.

See Also:

Author:

Constant Summary collapse 

%w(rel http://www.w3.org/ns/yaml-ld#context).freeze
%w(rel alternate).freeze
%w(type application/ld+yaml).freeze

Class Method Summary collapse

Class Method Details

.compact(input, context, expanded: false, documentLoader: self.method(:documentLoader), serializer: self.method(:serializer), **options) {|yamlld| ... } ⇒ String

Compacts the given input according to the steps in the Compaction Algorithm. The input must be copied, compacted and returned if there are no errors. If the compaction fails, an appropirate exception must be thrown.

If no context is provided, the input document is compacted using the top-level context of the document

The resulting Hash is either returned or yielded, if a block is given.

Parameters:

  • input (String, #read, Hash, Array) —

    The YAML-LD object to copy and perform the expansion upon.

  • context (String, #read, Hash, Array, JSON::LD::Context) —

    The base context to use when compacting the input.

  • serializer (Proc) (defaults to: self.method(:serializer)) —

    (nil) A Serializer method used for generating the YAML serialization of the result. If absent, the internal Ruby objects are returned, which can be transformed to YAML externally via #to_yaml. See serializer.

  • expanded (Boolean) (defaults to: false) —

    (false) Input is already expanded

  • options (Hash{Symbol => Object})

Yields:

  • YAML_LD

Yield Parameters:

  • yamlld (Array<Hash>) —

    The expanded YAML-LD document

Yield Returns:

  • (String) —

    returned YAML serialization

Returns:

  • (String) —

    If a block is given, the result of evaluating the block is returned, otherwise, the expanded YAML-LD document

Raises:

  • (JsonLdError)

See Also:



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/yaml_ld/api.rb', line 80

def self.compact(input, context, expanded: false,
                 documentLoader: self.method(:documentLoader),
                 serializer: self.method(:serializer),
                 **options,
                 &block)
  JSON::LD::API.compact(input, context, expanded: expanded,
                       documentLoader: documentLoader, 
                       serializer: serializer,
                       **options,
                       &block)
end

.documentLoader(url, extractAllScripts: false, profile: nil, requestProfile: nil, **options) {|remote_document| ... } ⇒ Object

Default document loader for YAML_LD.

Parameters:

  • url (RDF::URI, String)
  • extractAllScripts (Boolean) (defaults to: false) —

    If set to true, when extracting JSON-LD script elements from HTML, unless a specific fragment identifier is targeted, extracts all encountered JSON-LD script elements using an array form, if necessary.

  • profile (String) (defaults to: nil) —

    When the resulting contentType is text/html or application/xhtml+xml, this option determines the profile to use for selecting a JSON-LD script elements.

  • requestProfile (String) (defaults to: nil) —

    One or more IRIs to use in the request as a profile parameter.

  • options (Hash<Symbol => Object>)

Yields:

  • remote_document

Yield Parameters:

  • remote_document (RemoteDocument, RDF::Util::File::RemoteDocument)

Raises:

  • (IOError) 


239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/yaml_ld/api.rb', line 239

def self.documentLoader(url, extractAllScripts: false, profile: nil, requestProfile: nil, **options, &block)
  if url.respond_to?(:read)
    base_uri = options[:base]
    base_uri ||= url.base_uri if url.respond_to?(:base_uri)
    content_type = options[:content_type]
    content_type ||= url.content_type if url.respond_to?(:content_type)
    context_url = if url.respond_to?(:links) && url.links &&
      # Any JSON type other than ld+json
      (content_type == 'application/json' || content_type.match?(%r(application/(^ld)+json)))
      link = url.links.find_link(JSON::LD::API::LINK_REL_CONTEXT)
      link.href if link
    elsif  url.respond_to?(:links) && url.links &&
      # Any YAML type
      content_type.match?(%r(application/(\w+\+)*yaml))
      link = url.links.find_link(LINK_REL_CONTEXT)
      link.href if link
    end

    content = case content_type
    when nil, %r(application/(\w+\+)*yaml)
      # Parse YAML
      Psych.safe_load(url.read, aliases: true)
    else
      url.read
    end
    block.call(RemoteDocument.new(content,
      documentUrl: base_uri,
      contentType: content_type,
      contextUrl: context_url))
  elsif url.to_s.match?(/\.yaml\w*$/) || content_type.to_s.match?(%r(application/(\w+\+)*yaml))
    # Parse YAML
    block.call(RemoteDocument.new(Psych.load_file(url.to_s, aliases: true),
      documentUrl: base_uri,
      contentType: content_type,
      contextUrl: context_url))
  else
    RDF::Util::File.open_file(url, **options, &block)
  end
end

.expand(input, documentLoader: self.method(:documentLoader), serializer: self.method(:serializer), **options) {|yamlld, RDF::URI| ... } ⇒ String

Expands the given input according to the steps in the Expansion Algorithm. The input must be copied, expanded and returned if there are no errors. If the expansion fails, an appropriate exception must be thrown.

The resulting Array either returned or yielded

Parameters:

  • input (String, #read, Hash, Array) —

    The YAML-LD object to copy and perform the expansion upon.

  • documentLoader (Proc) (defaults to: self.method(:documentLoader)) —

    The callback of the loader to be used to retrieve remote documents and contexts, and to parse IO objects. If specified, it must be used to retrieve remote documents and contexts; otherwise, if not specified, the processor’s built-in loader must be used. See documentLoader for the method signature. The remote document returned must be parsed if it is YAML.

  • serializer (Proc) (defaults to: self.method(:serializer)) —

    (nil) A Serializer method used for generating the YAML serialization of the result. If absent, the internal Ruby objects are returned, which can be transformed to YAML externally via #to_yaml. See serializer.

  • options (Hash{Symbol => Object})

Yields:

  • YAML_LD, base_iri

Yield Parameters:

  • yamlld (Array<Hash>) —

    The expanded YAML-LD document

  • RDF::URI (RDF::URI The document base as determined during expansion) —

    The document base as determined during expansion

Yield Returns:

  • (String) —

    returned YAML serialization

Returns:

  • (String) —

    If a block is given, the result of evaluating the block is returned, otherwise, the expanded YAML-LD document

Raises:

  • (JsonLdError)

See Also:



43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/yaml_ld/api.rb', line 43

def self.expand(input,
                documentLoader: self.method(:documentLoader),
                serializer: self.method(:serializer),
                **options,
                &block)
  JSON::LD::API.expand(input,
                       documentLoader: documentLoader, 
                       serializer: serializer,
                       **options,
                       &block)
end

.flatten(input, context, expanded: false, documentLoader: self.method(:documentLoader), serializer: self.method(:serializer), **options) {|yamlld| ... } ⇒ Object, Hash

This algorithm flattens an expanded YAML-LD document by collecting all properties of a node in a single object and labeling all blank nodes with blank node identifiers. This resulting uniform shape of the document, may drastically simplify the code required to process YAML-LD data in certain applications.

The resulting Array is either returned, or yielded if a block is given.

Parameters:

  • input (String, #read, Hash, Array) —

    The YAML-LD object or array of JSON-LD objects to flatten or an IRI referencing the JSON-LD document to flatten.

  • context (String, #read, Hash, Array, JSON::LD::EvaluationContext) —

    An optional external context to use additionally to the context embedded in input when expanding the input.

  • expanded (Boolean) (defaults to: false) —

    (false) Input is already expanded

  • serializer (Proc) (defaults to: self.method(:serializer)) —

    (nil) A Serializer method used for generating the YAML serialization of the result. If absent, the internal Ruby objects are returned, which can be transformed to YAML externally via #to_yaml. See serializer.

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :createAnnotations (Boolean) —

    Unfold embedded nodes which can be represented using @annotation.

Yields:

  • YAML_LD

Yield Parameters:

  • yamlld (Array<Hash>) —

    The expanded YAML-LD document

Yield Returns:

  • (String) —

    returned YAML serialization

Returns:

  • (Object, Hash) —

    If a block is given, the result of evaluating the block is returned, otherwise, the flattened JSON-LD document

See Also:



116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/yaml_ld/api.rb', line 116

def self.flatten(input, context, expanded: false,
                 documentLoader: self.method(:documentLoader),
                 serializer: self.method(:serializer),
                 **options,
                 &block)
  JSON::LD::API.flatten(input, context, expanded: expanded,
                        documentLoader: documentLoader, 
                        serializer: serializer,
                        **options,
                        &block)
end

.frame(input, frame, expanded: false, documentLoader: self.method(:documentLoader), serializer: self.method(:serializer), **options) {|yamlld| ... } ⇒ Object, Hash

Frames the given input using the frame according to the steps in the Framing Algorithm. The input is used to build the framed output and is returned if there are no errors. If there are no matches for the frame, null must be returned. Exceptions must be thrown if there are errors.

The resulting Array is either returned, or yielded if a block is given.

Parameters:

  • input (String, #read, Hash, Array) —

    The YAML-LD object or array of YAML-LD objects to flatten or an IRI referencing the JSON-LD document to flatten.

  • frame (String, #read, Hash, Array) —

    The frame to use when re-arranging the data.

  • expanded (Boolean) (defaults to: false) —

    (false) Input is already expanded

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :embed ('@always', '@link', '@once', '@never') — default: '@once' —

    a flag specifying that objects should be directly embedded in the output, instead of being referred to by their IRI.

  • :explicit (Boolean) — default: false —

    a flag specifying that for properties to be included in the output, they must be explicitly declared in the framing context.

  • :requireAll (Boolean) — default: false —

    A flag specifying that all properties present in the input frame must either have a default value or be present in the JSON-LD input for the frame to match.

  • :omitDefault (Boolean) — default: false —

    a flag specifying that properties that are missing from the JSON-LD input should be omitted from the output.

  • :pruneBlankNodeIdentifiers (Boolean) — default: true —

    removes blank node identifiers that are only used once.

  • :omitGraph (Boolean) —

    does not use @graph at top level unless necessary to describe multiple objects, defaults to true if processingMode is 1.1, otherwise false.

Yields:

  • YAML_LD

Yield Parameters:

  • yamlld (Array<Hash>) —

    The expanded YAML-LD document

Yield Returns:

  • (String) —

    returned YAML serialization

Returns:

  • (Object, Hash) —

    If a block is given, the result of evaluating the block is returned, otherwise, the framed JSON-LD document

Raises:

  • (InvalidFrame)

See Also:



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/yaml_ld/api.rb', line 157

def self.frame(input, frame, expanded: false,
               documentLoader: self.method(:documentLoader),
               serializer: self.method(:serializer),
               **options,
               &block)
  JSON::LD::API.frame(input, frame, expanded: expanded,
                      documentLoader: documentLoader, 
                      serializer: serializer,
                      **options,
                      &block)
end

.fromRdf(input, useRdfType: false, useNativeTypes: false, documentLoader: self.method(:documentLoader), serializer: self.method(:serializer), **options) {|jsonld| ... } ⇒ Object, Hash

Take an ordered list of RDF::Statements and turn them into a JSON-LD document.

The resulting Array is either returned or yielded, if a block is given.

Parameters:

  • input (RDF::Enumerable)
  • useRdfType (Boolean) (defaults to: false) —

    (false) If set to true, the JSON-LD processor will treat rdf:type like a normal property instead of using @type.

  • useNativeTypes (Boolean) (defaults to: false) —

    (false) use native representations

  • serializer (Proc) (defaults to: self.method(:serializer)) —

    (nil) A Serializer method used for generating the YAML serialization of the result. If absent, the internal Ruby objects are returned, which can be transformed to YAML externally via #to_yaml. See serializer.

  • options (Hash{Symbol => Object})

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The JSON-LD document in expanded form

Yield Returns:

  • (Object) —

    returned object

Returns:

  • (Object, Hash) —

    If a block is given, the result of evaluating the block is returned, otherwise, the expanded JSON-LD document



212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/yaml_ld/api.rb', line 212

def self.fromRdf(input, useRdfType: false, useNativeTypes: false,
                 documentLoader: self.method(:documentLoader),
                 serializer: self.method(:serializer),
                 **options,
                 &block)
  JSON::LD::API.fromRdf(input,
                        useRdfType: useRdfType,
                        useNativeTypes: useNativeTypes,
                        documentLoader: documentLoader, 
                        serializer: serializer,
                        **options,
                        &block)
end

.serializer(object, *args, **options) ⇒ Object

The default serializer for serialzing Ruby Objects to JSON.

Defaults to MultiJson.dump

Parameters:

  • object (Object)
  • args (Array<Object>) —

    other arguments that may be passed for some specific implementation.

  • options (Hash<Symbol, Object>) —

    options passed from the invoking context.



289
290
291
292
 
# File 'lib/yaml_ld/api.rb', line 289

def self.serializer(object, *args, **options)
  # de-alias any objects to avoid the use of aliases and anchors
  "%YAML 1.2\n" + Psych.dump(object, **options)
end

.toRdf(input, expanded: false, documentLoader: self.method(:documentLoader), **options) {|statement| ... } ⇒ RDF::Enumerable

Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.

Parameters:

  • input (String, #read, Hash, Array) —

    The YAML-LD object to process when outputting statements.

  • expanded (Boolean) (defaults to: false) —

    (false) Input is already expanded

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :produceGeneralizedRdf (Boolean) — default: false —

    If true, output will include statements having blank node predicates, otherwise they are dropped.

Yields:

  • statement

Yield Parameters:

  • statement (RDF::Statement)

Returns:

  • (RDF::Enumerable) —

    set of statements, unless a block is given.

Raises:

  • (JsonLdError) 


182
183
184
185
186
187
188
189
190
 
# File 'lib/yaml_ld/api.rb', line 182

def self.toRdf(input, expanded: false,
               documentLoader: self.method(:documentLoader),
               **options,
               &block)
  JSON::LD::API.toRdf(input, expanded: expanded,
                      documentLoader: documentLoader, 
                      **options,
                      &block)
end