= Indentation flattener

A small an simple library to transform text with indentations to
a text with extra symbols "PushIndent" and "PopIndent"

This project is based on https://github.com/jleahred/indent_tokenizer[indent_tokenizer]

This format is more convenient to use with peg grammars (as I will do)



== Usage

Add to `cargo.toml`
[source, toml]
----
[dependencies]
pending...
----

See example below



== Modifs

None


== Indentation format

Tabs are no valid on indentation grouping.

Indentation "Push" and "Pop" will be inserted on each indentation level modif.


Let's see by example.


.Simple valid input
----
.....
...
    ....        new ident level
        ....    new ident level
        ....
    ....        one back indent level
    ....
        ....    new indent level
....            two back indent level
....
    ....        new indent level
----


Indentation groups can have any number of spaces

.Valid indentation different spaces
----
.....
  ....              level1  <--
        ....        level2
  ....              level1  <--
  ....
....
....
      ....          level1  <--
            ....    level2  <--
----

It's not a good idea to have same level with different spaces, but it's
allowed when you are creating a new level.

In this example, last level1 and last level2  are idented with more spaces than previus ones




.Invalid indentation
----
.....
...
    ....
        ....
       ....     <--  incorrect indentation
    ....        <--  correct previous ident level
    ....
....
....
    ....
----

In order to go back a level, the indentation has to match with
the previous on this level.

As we saw in previous example, increasing level is free indentation.


.Start line indicator
----
|.....
    |.....
    |......
        |......
----

You can start lines with `|`, but it's optional.


.Start line indicator is optional
----
.....
     |1234
     1234
     ......
        ......
----

But if you combine lines with `|` and without on same level, columns will not match



It is usefull when you need to start with spaces.


.I want to start a line with spaces
----
.....
     | .....     <- This line starts with an space
     |  ......   <- Starting with 2 spaces
     |.....      <- starts with no spaces
     .....      <- starting with no spaces
     ...        <- starting with no spaces
----


.My line starts with a `|`
----
.....
    ||.....     This line starts with a `|`
    |......     This one starts with `.`

.....
.....
    ||.....     This line starts with a `|`
    ......     This one starts with `.`

----


A line is empty when there are no content or it only has spaces (no matter how many).

Empty lines will produce new line `char` and no change of indentation level


.Empty lines
----
.....
    .....
    .....
    .....
    .....     next line is empty

    .....     next line is empty

.....
.....         next line is empty

----

What if I want represent empty lines?

.Representing empty lines
----
.....
    .....
    .....     There is a new line after (same indent level)

    .....
    .....     There is a new line after (explicitly marked)
    |
    .....     three new lines after
    |
    |
    |
.....   Two new lines at end of document
|
|
----

`|` is quite usefull if you need to represent empty lines at end of document.


What if I want to represent spaces at end of line?

Spaces at end of line will not be erased, therefore, you don't need to do anything about it.

But it could be intesting to represent it because some editors can run trailing or
just because you can visualize it.


.Representing spaces at end line
----
.....
    .....
    .....
    .....
    This line keeps 2 spaces and end  |
    and you know it

    Next line is properly indented and only has spaces
    |   |

----


In fact, you can write `|` at end of all lines. It will be removed.

Next strings, are equivalent.

.`|` it's optional at end of line
----
.....|
    .....|
    .....|
    .....|


.....
    .....
    .....
    .....

----



But I could need a pipe `|` at end of line

.pipe at end of line
----
.....
    .....
    .....
    .....
    This line ends with a pipe||

----




== Output format

The output will be a string with codes PUSH_INDENT and POP_INDENT

.From lib.rs
[source, rust]
----
    const PUSH_INDENT: char = 0x02 as char;
    const POP_INDENT: char = 0x03 as char;
----

Spaces to mark indentation, will be removed from output.

See examples below.

As the system works with lines, every existing line with content, will finish with `end of line`



== API

It works with concrete types vs general types (as String, u32 or usize)


Constants::
[source, rust]
----
const EOL: char = '\n';
const PUSH_INDENT: char = 0x02 as char;
const POP_INDENT: char = 0x03 as char;
----


Concrete types::
[source, rust]
----
#[derive(Debug, PartialEq, Copy, Clone)]
pub struct LineNum(u32);

#[derive(Debug, PartialEq, Clone, Eq)]
pub struct SLine(String);

#[derive(Debug, PartialEq, Clone, Eq, Default)]
pub struct SFlattedText(String);
----


Function to call::
[source, rust]
----
pub fn flatter(input: &str) -> Result<SFlattedText, Error>
----



Error type::
[source, rust]
----
#[derive(Debug, PartialEq)]
pub struct Error {
    pub line: LineNum,
    pub desc: String,
}
----


Thats all


Look into lib.rs


== Examples

You can look into tests.rs, there are several tests.


.Simple example
[source, rust]
----
# this input...

0
    01
    02
        020
        021
        023
            0230
            0231

# produces...
0
\u{2}01
02
\u{2}020
021
023
\u{2}0230
0231
\u{3}\u{3}\u{3}"
----

As you can see, indentations has been removed by codes to mark PUSH_INDENT and POP_INDENT

[NOTE]
All lines are finished with new line. If last line has not a new line, the system will insert one


.Complex example
[source, rust]
----
    let flat = flatter("
0
     || 01a
     01b
     01c

     02a
     02b

        |020a
        ||020b

        |  021a
        |021b
1a
1b
    11a
    ||11b
    11c

    12a  ||
    |12b  ||
2a
    21a
    21b
    |
    |

")
        .unwrap();

    assert!(flat ==
            SFlattedText::from("
0
\u{2}| 01a
01b
01c

02a
02b

\u{2}020a
|020b

  021a
021b
\u{3}\u{3}1a
1b
\u{2}11a
|11b
11c

12a  |
12b  |
\u{3}2a
\u{2}21a
21b



\u{3}"));
----

More examples on tests.rs

