Skip to content

Commit 58391cb

Browse files
gkellogggkellogg
committed
Improve Vocabulary DSL documentation. For #432.
1 parent fe501c2 commit 58391cb

2 files changed

Lines changed: 93 additions & 55 deletions

File tree

‎lib/rdf/vocab/writer.rb‎

Lines changed: 41 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -3,53 +3,53 @@
33
require 'cgi'
44

55
module RDF
6-
##
7-
# Vocabulary format specification. This can be used to generate a Ruby class definition from a loaded vocabulary.
8-
#
9-
# Definitions can include recursive term definitions, when the value of a property is a blank-node term. They can also include list definitions, to provide a reasonable way to represent `owl:unionOf`-type relationships.
10-
#
11-
# @example a simple term definition
12-
# property :comment,
13-
# comment: %(A description of the subject resource.).freeze,
14-
# domain: "rdfs:Resource".freeze,
15-
# label: "comment".freeze,
16-
# range: "rdfs:Literal".freeze,
17-
# isDefinedBy: %(rdfs:).freeze,
18-
# type: "rdf:Property".freeze
19-
#
20-
# @example an embedded skos:Concept
21-
# term :ad,
22-
# exactMatch: [term(
23-
# type: "skos:Concept".freeze,
24-
# inScheme: "country:iso3166-1-alpha-2".freeze,
25-
# notation: %(ad).freeze
26-
# ), term(
27-
# type: "skos:Concept".freeze,
28-
# inScheme: "country:iso3166-1-alpha-3".freeze,
29-
# notation: %(and).freeze
30-
# )],
31-
# "foaf:name": "Andorra".freeze,
32-
# isDefinedBy: "country:".freeze,
33-
# type: "http://sweet.jpl.nasa.gov/2.3/humanJurisdiction.owl#Country".freeze
34-
#
35-
# @example owl:unionOf
36-
# property :duration,
37-
# comment: %(The duration of a track or a signal in ms).freeze,
38-
# domain: term(
39-
# "owl:unionOf": list("mo:Track".freeze, "mo:Signal".freeze),
40-
# type: "owl:Class".freeze
41-
# ),
42-
# isDefinedBy: "mo:".freeze,
43-
# "mo:level": "1".freeze,
44-
# range: "xsd:float".freeze,
45-
# type: "owl:DatatypeProperty".freeze,
46-
# "vs:term_status": "testing".freeze
476
class Vocabulary
487
class Format < RDF::Format
498
content_encoding 'utf-8'
509
writer { RDF::Vocabulary::Writer }
5110
end
5211

12+
##
13+
# Vocabulary format specification. This can be used to generate a Ruby class definition from a loaded vocabulary.
14+
#
15+
# Definitions can include recursive term definitions, when the value of a property is a blank-node term. They can also include list definitions, to provide a reasonable way to represent `owl:unionOf`-type relationships.
16+
#
17+
# @example a simple term definition
18+
# property :comment,
19+
# comment: %(A description of the subject resource.).freeze,
20+
# domain: "rdfs:Resource".freeze,
21+
# label: "comment".freeze,
22+
# range: "rdfs:Literal".freeze,
23+
# isDefinedBy: %(rdfs:).freeze,
24+
# type: "rdf:Property".freeze
25+
#
26+
# @example an embedded skos:Concept
27+
# term :ad,
28+
# exactMatch: [term(
29+
# type: "skos:Concept".freeze,
30+
# inScheme: "country:iso3166-1-alpha-2".freeze,
31+
# notation: %(ad).freeze
32+
# ), term(
33+
# type: "skos:Concept".freeze,
34+
# inScheme: "country:iso3166-1-alpha-3".freeze,
35+
# notation: %(and).freeze
36+
# )],
37+
# "foaf:name": "Andorra".freeze,
38+
# isDefinedBy: "country:".freeze,
39+
# type: "http://sweet.jpl.nasa.gov/2.3/humanJurisdiction.owl#Country".freeze
40+
#
41+
# @example owl:unionOf
42+
# property :duration,
43+
# comment: %(The duration of a track or a signal in ms).freeze,
44+
# domain: term(
45+
# "owl:unionOf": list("mo:Track".freeze, "mo:Signal".freeze),
46+
# type: "owl:Class".freeze
47+
# ),
48+
# isDefinedBy: "mo:".freeze,
49+
# "mo:level": "1".freeze,
50+
# range: "xsd:float".freeze,
51+
# type: "owl:DatatypeProperty".freeze,
52+
# "vs:term_status": "testing".freeze
5353
class Writer < RDF::Writer
5454
include RDF::Util::Logger
5555
format RDF::Vocabulary::Format

‎lib/rdf/vocabulary.rb‎

Lines changed: 52 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,14 @@ module RDF
55
# A {Vocabulary} can also serve as a Domain Specific Language (DSL) for generating an RDF Graph definition for the vocabulary (see {RDF::Vocabulary#to_enum}).
66
#
77
# ### Defining a vocabulary using the DSL
8-
# Vocabularies can be defined based on {RDF::Vocabulary} or {RDF::StrictVocabulary} using a simple Domain Specific Language (DSL). Terms of the vocabulary are specified using either `property` or `term` (alias), with the attributes of the term listed in a hash. See {property} for description of the hash.
8+
# Vocabularies can be defined based on {RDF::Vocabulary} or {RDF::StrictVocabulary} using a simple Domain Specific Language (DSL).
9+
#
10+
# * Ontology information for the vocabulary itself can be specified using the {ontology} method.
11+
# * Terms of the vocabulary are specified using either `property` or `term` (alias), with the attributes of the term listed in a hash. See {property} for description of the hash. Term attributes become properties of the associated {RDF::Vocabulary::Term} (see {RDF::Vocabulary::Term#attributes}).
12+
#
13+
# Note that, by default, the prefix associated with the vocabulary for forming and interpreting PNames is created from the class name of the vocabulary. See {\_\_prefix\_\_=} for overriding this at runtime.
14+
#
15+
# The simplest way to generate a DSL representation of a vocabulary is using {RDF::Vocabulary::Writer} given an {RDF::Graph} representation of the vocabulary.
916
#
1017
# ### Vocabularies:
1118
#
@@ -31,6 +38,31 @@ module RDF
3138
# foaf.knows #=> RDF::URI("http://xmlns.com/foaf/0.1/knows")
3239
# foaf[:name] #=> RDF::URI("http://xmlns.com/foaf/0.1/name")
3340
# foaf['mbox'] #=> RDF::URI("http://xmlns.com/foaf/0.1/mbox")
41+
#
42+
# @example Defining a simple vocabulary
43+
# EX = Class.new(RDF::StrictVocabulay("http://example/ns#")) do
44+
# # Ontology definition
45+
# ontology :"http://example/ns#",
46+
# label: "The RDF Example Vocablary".freeze,
47+
# type: "http://www.w3.org/2002/07/owl#Ontology".freeze
48+
#
49+
# # Class definitions
50+
# term :Class,
51+
# label: "My Class",
52+
# comment: "Good to use as an example",
53+
# type: "rdfs:Class",
54+
# subClassOf: "http://example/SuperClass",
55+
# "ex:prop": "Some annotation property not having a shortcut"
56+
#
57+
# # Property definitions
58+
# property :prop,
59+
# comment: "A description of the property".freeze,
60+
# label: "property".freeze,
61+
# domain: "http://example/ns#Class".freeze,
62+
# range: "rdfs:Literal".freeze,
63+
# isDefinedBy: %(ex:).freeze,
64+
# type: "rdf:Property".freeze
65+
# end
3466
#
3567
# @example Method calls are converted to the typical RDF camelcase convention
3668
# foaf = RDF::Vocabulary.new("http://xmlns.com/foaf/0.1/")
@@ -44,15 +76,6 @@ module RDF
4476
# graph = RDF::Graph.new << RDF::RDFS.to_enum
4577
# graph.dump(:ntriples)
4678
#
47-
# @example Defining a simple vocabulary
48-
# class EX < RDF::StrictVocabulay("http://example/ns#")
49-
# term :Class,
50-
# label: "My Class",
51-
# comment: "Good to use as an example",
52-
# "rdf:type" => "rdfs:Class",
53-
# "rdfs:subClassOf" => "http://example/SuperClass"
54-
# end
55-
#
5679
# @see https://www.w3.org/TR/rdf-sparql-query/#prefNames
5780
class Vocabulary
5881
extend ::Enumerable
@@ -176,7 +199,7 @@ def strict?; false; end
176199
# @return [RDF::Vocabulary::Term]
177200
#
178201
# @overload property(name, options)
179-
# Defines a new property or class in the vocabulary.
202+
# Defines a new property or class in the vocabulary as a {RDF::Vocabulary::Term}.
180203
#
181204
# @example A simple term definition
182205
# property :domain,
@@ -1109,7 +1132,7 @@ def other?
11091132

11101133
##
11111134
# Enumerate attributes with values transformed into {RDF::Value} instances
1112-
# Uses an empty hash with a default_proc which looks up values in attributes.
1135+
# Uses an empty hash with a default_proc which looks up values in attributes. The prevents specific attributes from being evaluated until acessed.
11131136
#
11141137
# Properties are indexed by symbol. Symbols directly interpreted by a term are the accessors defined for the {RDF::Vocabulary::Term} class, also in {Term::ATTR_URIs}. Other keys are interpreted as absolute URIs or PNames for properties defined on this term.
11151138
#
@@ -1131,7 +1154,20 @@ def properties
11311154
end
11321155

11331156
##
1134-
# Values of an attributes as {RDF::Value}
1157+
# Values of an attributes as {RDF::Value}.
1158+
#
1159+
# Attribute values are returned as either an {RDF::Value} or {Array<RDf::Value} if there is more than one value.
1160+
#
1161+
# Attribute values which are not already a {RDF::Value} (including strings and symbols) are converted by a heuristic loookup as follows:
1162+
#
1163+
# * An {RDF::URI} if it can be turned into a valid IRI using {RDF::Vocabulary.expand_pname}. This includes IRIs already in non-relative form.
1164+
# * {RDF::Literal::Date} if valud,
1165+
# * {RDF::Literal::DateTime} if valid,
1166+
# * {RDF::Literal::Integer} if valid,
1167+
# * {RDF::Literal::Decimal} if valid,
1168+
# * {RDF::Literal::Double} if valid,
1169+
# * {RDF::Literal::Boolean} if valid
1170+
# * Otherwise, {RDF::Literal} where type may be inferred by the class of the value.
11351171
#
11361172
# @param [Symbol] prop
11371173
# @return [RDF::Value, Array<RDF::Value>]
@@ -1246,7 +1282,9 @@ def range_includes
12461282
rangeIncludes
12471283
end
12481284

1249-
# Serialize back to a Ruby source initializer
1285+
##
1286+
# Serialize back to a Ruby source initializer. This is used primarily by {RDF::Vocabulary::Writer}.
1287+
#
12501288
# @param [String] indent
12511289
# @return [String]
12521290
def to_ruby(indent: "")

0 commit comments

Comments
 (0)