README

一个库，提供在EasyRdf（原始库，仍然维护的分支）和rdfInterface对象之间转换的方法（双向）。

特别有用，当你有太多EasyRdf代码需要迁移，但你希望使用rdfInterface生态系统来开发新代码时。

安装

• 获取 Composer
• 运行 composer require sweetrdf/rdfInterface2easyRdf
• 安装您选择的EasyRdf实现，例如 composer require sweetrdf/easyrdf。
• 安装您选择的rdfInterface实现，例如 composer require sweetrdf/quick-rdf。

用法

rdfInterface到EasyRdf

这种方向的转换很简单

• 如果你不关心严格的结果类型检查，只需使用 rdfInterface2easyRdf\AsEasyRdf::asEasyRdf() 方法，例如

  # let's prepare all kind of rdfInterface objects
  $blank = quickRdf\DataFactory::blankNode();
  $named = quickRdf\DataFactory::namedNode('http://foo');
  $literal = quickRdf\DataFactory::literal('bar', 'en');
  $quad = quickRdf\DataFactory::quad($blank, $named, $literal);
  $dataset = new quickRdf\Dataset();
  $dataset->add($quad);
  $node = $dataset->withTerm($named);
  
  print_r(rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($blank));
  print_r(rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($named));
  print_r(rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($literal));
  echo rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($quad)->getGraph()->dump('text');
  echo rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($node)->getGraph()->dump('text');
  echo rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($dataset)->dump('text');

  • 如果你想将转换后的数据附加到已存在的图中，请将其作为第二个参数传递，例如（继续上一个示例中的代码）

    $graph = new EasyRdf\Graph();
    $graph->resource('http://baz')->addLiteral('https://foo', 'other value');
    rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($quad, $graph);
    echo $graph->dump('text');

• 如果你关心严格定义的返回数据类型，请使用 rdfInterface2easyRdf\AsEasyRdf::asLiteral()，rdfInterface2easyRdf\AsEasyRdf::asResource() 和 rdfInterface2easyRdf\AsEasyRdf::asGraph()。
  • 它们只接受兼容的输入类型，例如 rdfInterface2easyRdf\AsEasyRdf::asLiteral() 只接受 rdfInterface\LiteralInterface
  • rdfInterface\NodeInterface 既可以由 rdfInterface2easyRdf\AsEasyRdf::asResource() 也可以由 rdfInterface2easyRdf\AsEasyRdf::asGraph() 接受
  • 可以像 rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf() 一样传递一个可选的第二个参数 EasyRdf\Graph（请参阅上面的示例）

EasyRdf到rdfInterface

这种方向的转换可能很棘手。重要注意事项

• 由于rdfInterface只定义了一个接口但没有实际的实现，你必须始终传递一个RDF术语工厂对象（$dataFactory 参数）。
• 由于rdfInterface没有定义创建数据集（rdfInterface\DatasetInterface）和数据集节点（rdfInterface\DatasetNodeInterface）的标准方式，asRdfInterface() 方法返回一个 rdfInterface\QuadIteratorInterface，它是一个三元组迭代器。将 EasyRdf\Resource 或 EasyRdf\Graph 转换为数据集或数据集节点的方法是将EasyRdf对象中的三元组添加到现有的 rdfInterface\DatasetInterface 或 rdfInterface\DatasetNodeInterface 中。 可以使用 add()、addDataset() 和 addDatasetNode() 方法来实现（请参阅下面的示例）。
• 关于 EasyRdf\Resource 转换存在歧义。你可能想将其转换为RDF术语（rdfInterface\BlankNode 或 rdfInterface\NamedNode）或者将其转换为一组三元组（四元组迭代器、数据集或数据集节点）。
  • 如果 EasyRdf\Resource 对象没有属性（没有三元组），则 asRdfInterface() 方法将其转换为RDF术语，否则转换为 rdfInterface\QuadIteratorInterface。
  • 使用 asTerm()、asQuadIterator()、add()、addDataset() 或 addDatasetNode() 来强制更具体的行为。

以下示例中使用的EasyRdf图和术语工厂的示例

$graph = new EasyRdf\Graph();
$blank = $graph->resource('_:blank');
$res1  = $graph->resource('http://foo');
$res2  = $graph->resource('http://baz');
$res1->add('http://resource', $res2);
$lit1  = new EasyRdf\Literal('literal', 'en');
$lit2  = new EasyRdf\Literal(1, null, 'http://www.w3.org/2001/XMLSchema#integer');
$res1->addLiteral('http://langLiteral', $lit1);
$res1->addLiteral('http://intLiteral', $lit2);
$res3  = $graph->resource('http://marry');
$res3->addLiteral('http://langLiteral', $lit1);

$df = new quickRdf\DataFactory();

• 使用 asRdfInterface() 根据输入猜测输出类型。

  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($blank, $df));
  # as $res2 contains no properties, it's converted to a named node
  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res2, $df));
  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($lit1, $df));
  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($lit2, $df));
  # as $res1 contains properties, it's converted to a quad iterator
  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df));
  foreach (rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df) as $i) {
    print_r($i);
  }
  # EasyRdf\Graph is also converted to a quad iterator
  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($graph, $df));
  foreach (rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($graph, $df) as $i) {
    print_r($i);
  }

• 使用 asTerm() 来强制将一个 EasyRdf\Resource 转换为术语

  print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df));
  print_r(rdfInterface2easyRdf\AsRdfInterface::asTerm($res1, $df));

• 有两种方法可以将 EasyRdf\Graph 和 EasyRdf\Resource 转换为数据集

  echo $graph->dump('text');
  
  # using quad iterator returned by the asRdfInterface()
  $dataset = new quickRdf\Dataset();
  $dataset->add(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($graph, $df));
  echo $dataset;
  
  # using add()/addDataset() method
  # (addDataset() works the same, just has strictly defined return type)
  $dataset = rdfInterface2easyRdf\AsRdfInterface::add($graph, $df, new quickRdf\Dataset());
  echo $dataset;
  
  # similarly for an EasyRdf\Resource
  # (just only given resource triples are converted)
  $dataset = new quickRdf\Dataset();
  $dataset->add(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df));
  echo $dataset;
  $dataset = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, new quickRdf\Dataset());
  echo $dataset;
  # using add()/addDataset() we can also enforce 
  # a whole graph to be converted based on an EasyRdf\Resource
  $dataset = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, new quickRdf\Dataset(), true);
  echo $dataset;

• 将 EasyRdf\Resource 转换为数据集节点相对最为复杂

  echo $graph->dump('text');
  
  $emptyDatasetNode = new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $df::blankNode());
  $datasetNode = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, $emptyDatasetNode);
  print_r($datasetNode->getNode());
  # the dataset attached to the dataset node contains all triples
  echo $datasetNode->getDataset();
  # but the dataset node itself returns only triples of the converted EasyRdf\Resource
  foreach($datasetNode as $i) {
    echo "$i\n";
  }
  
  # conversion could be limited to EasyRdf\Resource triples only using the $wholeGraph parameter
  $emptyDatasetNode = new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $df::blankNode());
  $datasetNode = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, $emptyDatasetNode, false);
  print_r($datasetNode->getNode());
  # the dataset attached to the dataset node contains all triples
  echo $datasetNode->getDataset();
  
  # addDatasetNode() works in the same way, just has narrower return type
  $emptyDatasetNode = new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $df::blankNode());
  $datasetNode = rdfInterface2easyRdf\AsRdfInterface::addDatasetNode($res1, $df, $emptyDatasetNode);
  print_r($datasetNode->getNode());
  echo $datasetNode->getDataset();

• 在 add()、addDataset() 和 addDatasetNode() 的情形下，用于传递数据集/数据集节点的参数也可以接受一个可调用的对象，例如：

  $dataset = rdfInterface2easyRdf\AsRdfInterface::addDataset($res1, $df, fn() => new quickRdf\Dataset());
  
  $datasetNode = rdfInterface2easyRdf\AsRdfInterface::addDatasetNode(
    $res1, 
    $df, 
    fn($x) => new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $x)
  );