convert method

Implementation

@override
/// Converts an RDF graph to a Turtle string representation.
///
/// This method serializes the given RDF graph to the Turtle format with
/// advanced formatting features including:
/// - Automatically detecting and writing prefix declarations
/// - Grouping triples by subject for more compact output
/// - Proper indentation and formatting for readability
/// - Optimizing blank nodes that appear only once as objects by inlining them
/// - Serializing RDF collections (lists) in the compact Turtle '(item1 item2)' notation
///
/// Parameters:
/// - [graph] The RDF graph to serialize to Turtle
/// - [baseUri] Optional base URI to use for resolving relative IRIs and
///   generating shorter references. If provided, a @base directive will be
///   included in the output.
///
/// Returns:
/// - A properly formatted Turtle string representation of the input graph.
///
/// Example:
/// ```dart
/// final graph = RdfGraph();
/// // Add some triples to the graph
/// final turtle = encoder.convert(graph, baseUri: 'http://example.org/');
/// ```
String convert(RdfGraph graph, {String? baseUri}) {
  _log.info('Serializing graph to Turtle');

  final buffer = StringBuffer();

  // Write base directive if provided
  if (baseUri != null) {
    buffer.writeln('@base <$baseUri> .');
  }

  // Map to store generated blank node labels for this serialization
  final Map<BlankNodeTerm, String> blankNodeLabels = {};
  _generateBlankNodeLabels(graph, blankNodeLabels);

  // Count blank node occurrences to determine which can be inlined
  final Map<BlankNodeTerm, int> blankNodeOccurrences =
      _countBlankNodeOccurrences(graph);

  // 1. Write prefixes
  final prefixCandidates = {
    ..._namespaceMappings.asMap(),
    ..._options.customPrefixes,
  };
  // Identify which prefixes are actually used in the graph
  final prefixes = _extractUsedAndGenerateMissingPrefixes(
    graph,
    prefixCandidates,
    baseUri,
  );

  _writePrefixes(buffer, prefixes);

  final prefixesByIri = prefixes.map((prefix, iri) {
    return MapEntry(iri, prefix);
  });

  // 2. Write triples grouped by subject
  _writeTriples(
    buffer,
    graph,
    prefixesByIri,
    blankNodeLabels,
    blankNodeOccurrences,
    baseUri,
  );

  return buffer.toString();
}