https://github.com/consolidation/comments

A tool for preserving comments, e.g. when parsing YAML files.
https://github.com/consolidation/comments

Last synced: about 2 months ago
JSON representation

A tool for preserving comments, e.g. when parsing YAML files.

• Host: GitHub
• URL: https://github.com/consolidation/comments
• Owner: consolidation
• Created: 2017-11-05T15:32:47.000Z (almost 7 years ago)
• Default Branch: main
• Last Pushed: 2020-07-16T23:59:14.000Z (about 4 years ago)
• Last Synced: 2024-07-18T04:03:30.585Z (2 months ago)
• Language: PHP
• Size: 23.4 KB
• Stars: 11
• Watchers: 3
• Forks: 6
• Open Issues: 3
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Consolidation\Comments

A tool for preserving comments, e.g. when parsing YAML files.

[![Build Status](https://travis-ci.org/consolidation/comments.svg?branch=main)](https://travis-ci.org/consolidation/comments)

[![Windows Build](https://ci.appveyor.com/api/projects/status/7x2amxttvvuuh7pf?svg=true)](https://ci.appveyor.com/project/greg-1-anderson/comments)

[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/consolidation/comments/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/consolidation/comments/?branch=main)

[![Coverage Status](https://coveralls.io/repos/github/consolidation/comments/badge.svg?branch=main)](https://coveralls.io/github/consolidation/comments?branch=main)

[![License](https://poser.pugx.org/consolidation/comments/license)](https://packagist.org/packages/consolidation/comments)

## Component Status

Prototype.

## Motivation

Do lightweight editing on YAML files and then rewrite the file without losing embedded comments.

## Usage

```

// First step: read the file, parse the yaml, edit and dump the results.

$original_contents = file_get_contents($filepath);

$parsed_data = Yaml::parse($original_contents);

$processed_data = $this->my_processing_function($parsed_data);

$altered_contents = Yaml::dump($parsed_data, PHP_INT_MAX, 2, Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK);

// Second step: collect comments from original document and inject them into result.

$commentManager = new Comments();

$commentManager->collect(explode("\n", $original_contents));

$altered_with_comments = $commentManager->inject(explode("\n", $altered_contents));

$result = implode("\n", $altered_with_comments);

```

## Limitations

The comment manager collects groups of comment lines and associates them with the first non-blank content line that follows the comment. If there are multiple non-blank content lines that are exactly the same, then the comment lines are re-injected in the same order they appeared in the original file.

## Installation

$ composer require consolidation/comments

## Comparison to Existing Solutions

See Klausi's [yaml_comments](https://github.com/klausi/yaml_comments).