Struct PropertySort 

pub struct PropertySort<'a> { /* private fields */ }

A sort of an object’s properties, waiting to be told how to order them.

Built by CstObject::sort_properties.

Implementations

impl<'a> PropertySort<'a>

pub fn pin_comment_headers(self) -> Self

Leaves a comment that heads a group of properties where it was written.

A comment with a blank line above it reads as a heading for the properties beneath it rather than as a description of the first of them, so it stays put and the properties sort past it. Without this, every comment above a property travels with that property, which carries a heading off to wherever its first property happens to land.

The blank line itself stays too, as does a blank line with no comment under it.

Example

use jsonc_parser::ParseOptions;
use jsonc_parser::cst::CstRootNode;

let json_text = r#"{
  "prop": 1,

  // section
  "prop2": 2,
  "prop1": 1
}"#;

let root = CstRootNode::parse(json_text, &ParseOptions::default()).unwrap();
let root_obj = root.object_value().unwrap();
root_obj
  .sort_properties()
  .pin_comment_headers()
  .by_key(|prop| prop.decoded_name());

assert_eq!(root.to_string(), r#"{
  "prop": 1,

  // section
  "prop1": 1,
  "prop2": 2
}"#);

pub fn pin_comment_headers_with( self, rule: impl FnMut(&CstObjectProp, &[CstComment]) -> usize + 'a, ) -> Self

Decides for each property how much of what was written above it is a heading for what follows rather than part of the property.

rule is handed the property and the comments written above it, in the order they appear, and returns how many of them, counting from the top, stay where they were written. The rest travel with the property, as does the blank line under whatever stayed.

Returning comments.len() pins everything above the property and 0 pins nothing, so PropertySort::pin_comment_headers is if prop.has_blank_line_before() { comments.len() } else { 0 }. A count in between splits a block that is partly a heading and partly a note about the property itself.

The rule is only consulted where a header could be written, which is a property on a line of its own; it is not called for an object written on one line.

The rule must not change the object’s children. Doing so leaves the sort with nothing safe to write back, so it gives up and leaves the object as the rule left it.

pub fn within_groups(self) -> Self

Sorts each run of properties between blank lines on its own, so that no property crosses one.

A blank line, and whatever was written under it, is the boundary between two groups, and a boundary stays where it is. A rule set by PropertySort::pin_comment_headers_with still decides what travels with the properties inside each group.

Example

use jsonc_parser::ParseOptions;
use jsonc_parser::cst::CstRootNode;

let json_text = r#"{
  "m": 1,

  // section
  "z": 2,
  "a": 3
}"#;

let root = CstRootNode::parse(json_text, &ParseOptions::default()).unwrap();
let root_obj = root.object_value().unwrap();
root_obj
  .sort_properties()
  .within_groups()
  .by_key(|prop| prop.decoded_name());

// "m" stays above the blank line and only "z" and "a" trade places
assert_eq!(root.to_string(), r#"{
  "m": 1,

  // section
  "a": 3,
  "z": 2
}"#);

pub fn by(self, compare: impl FnMut(&CstObjectProp, &CstObjectProp) -> Ordering)

Sorts the properties with the given comparator.

The sort is stable, so properties that compare equal keep the order they were written in. The comparator must describe a total order, as the sort may panic otherwise, and it must not change the object’s children; see PropertySort::pin_comment_headers_with.

pub fn by_key<K: Ord>(self, key: impl FnMut(&CstObjectProp) -> K)

Sorts the properties by a key, which is worked out once per property.

A child that isn’t a property, which is only possible if the tree has been manipulated into holding something else, has no key and sorts above every property. Behaves like PropertySort::by in every other respect.