https://github.com/kaitai-io/ksylint

A linter for ksy files.
https://github.com/kaitai-io/ksylint

Last synced: 10 days ago
JSON representation

A linter for ksy files.

• Host: GitHub
• URL: https://github.com/kaitai-io/ksylint
• Owner: kaitai-io
• License: gpl-3.0
• Created: 2019-09-28T21:40:04.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2021-08-15T15:05:25.000Z (over 3 years ago)
• Last Synced: 2024-09-18T07:01:39.672Z (4 months ago)
• Language: Python
• Homepage: http://kaitai.io
• Size: 37.1 KB
• Stars: 11
• Watchers: 8
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-kaitai - ksylint - A linter for .ksy files (Tools / Fixed set of file formats)

README

        
ksylint


Check Kaitai Struct .ksy files for errors and style flaws.




 

 



## Installation

``` bash

pip install ksylint

```

## Usage

``` bash

ksylint hello_world.ksy

```

### Missing style guide tests (TODO)

1. General formatting

    - Use block YAML style in most general cases, unless explicitly specified/allowed otherwise.

    - Formatting of maps-inside-sequences MUST have - delimiter and first map element on the same first line.

3. Meta section (meta)

    - xref — keys inside MUST be in alphabetic order

    - license — MUST be a valid SPDX license expression

    - ks-version — SHOULD list lowest possible KS compiler version that is able to compile this file.

    - 	KS syntax allows usage of some top-level elements deep inside the hierarchy — this can be useful during development, for example, for purpose of grafting one .ksy file into another quickly. However, in production-quality .ksy files, one MUST NOT use keys like title, imports or ks-version (i.e. everything except explicitly listed in a list above) on intermediate levels.

    - The following keys are reserved for internal use (i.e. debugging and test running) and MUST NOT be used in general-purpose .ksy files: ks-debug, ks-opaque-types

4. Documentation

    - Single-line documentation strings SHOULD BE formatted using raw unquoted string literals.

    - Multi-line SHOULD BE formatted using YAML literal style scalar, i.e. using : | syntax.

    - Lines should be wrapped to be 80 columns long. If it doesn’t fit into single line after wrapping, then it’s a multi-line docstring, so use proper multi-line syntax.

    - There is no formal conversion of docstrings into language-specific docstrings now in KS, but generally we SHOULD keep it close to CommonMark formatting, i.e.:

        - paragraphs separated by an empty line

        - bullet lists created by an asterisk * and a space at the beginning of the line

        - use backticks ` to wrap identifiers and small pieces of code

5. Sequence attributes

    - Attribute identifiers

    - Trailing padding

### Not checked

- All identifiers, docstrings, comments and generally all human-readable text SHOULD be kept in English, unless there’s a very good reason not to do so.

- application — SHOULD name a particular application, if there’s any; if there are too many to list (for example, network packet formats or executables are used virtually everywhere), then one SHOULD omit this field.

- file-extension — if there’s only one extension, MUST be a string; if there are several, MUST be an sequence in block form and SHOULD order extensions from most popular extension to least popular.