easyfileio 1.22
an easy way to read and write files in python
License: MIT

# how to use easyfileio

easyfileio is a simple program that makes inputs and outputs of file simple and easy.

## installation

write this in command prompt

`pip install easyfileio`

or

`python -m pip install easyfileio`

## how to use

### making an object
you must first create an object that you can use to operate file. Use `content` to make this object, like

```
example = easyfile.content('folderpath/folderpath', 'examplefile.txt')
```

This will create an object for the file you want to operate on. Even if you don't have the file yet, it will automatically create the file and the folder path for you. If you leave `'folderpath/folderpath'` as `''` or `None`, the file would be created in the current directory. 
If you leave out the file name, it would just create the file folder path. 

By default, easyfile uses a utf-8 encoding to read and write files. If you want to customize this, just write `encoding='encoding_type'` in `content`.

Example:
```
example = easyfile.content('folderpath/folderpath', 'examplefile.txt', encoding='shift-jis')
```

You also can make the file read-only by using `lock=True` in `content`. the file would still be able to read your file, but it would not be able to be written in manually.

Example:
```
example = easyfile.content('folderpath/folderpath', 'examplefile.txt', lock=True')
```

### fetching file
you can fetch the contents of the file with `example.fetch()`.
It strips all of the escape sequences, but you can use `no_strip=True` to automatically keep all of the escape sequences.

Example:
```
example.fetch(no_strip=True)
```

Executing this first is recommended (not required).

### saving strings
you can save strings with `example.save('string to save')`. it would automatically save the string you input. Saving a list would be explained later.
It will automatically write the string in a new line in the file, but you can overwrite, and write in the same line if you want.
To overwrite file, simply write `overwrite=True`. To write in the same line as before, just write, `sameLN=True`.
You can also lock or unlock your file by using `lock=True/False`

Example:
```
example.save('string to save', overwrite=True, sameLN=True, lock=False)
```

### changing content in file
use `example.change(line_index, 'changed line')` to change lines in code. You can lock or unlock your file by using `lock=True/False`

example:

```
example.change(0, 'first line')
```

### removing content in file
`example.delete(line_index')` to change lines in code. You can lock or unlock your file by using `lock=True/False`

example:
```
example.delete(0)
```

### removing file altogether
use `delete_file()` to remove file. You can still use`example.save('save string')` since it automatically creates file path.

Example:
```
sample.delete_file()
```

### saving lists
You can indeed save lists by using `stringify_list(['list', 'to', 'save'], parsing_sign)`. `parsing_sign` must be one character.
`stringify_list` would handle edge cases like `stringify_list(['list', 'to:save', 'to:list'], ':')` by multiplying the parsing_sign.

Example:
```
>>> stringify_list(['list', 'to:save', 'to:list'], ':')
output: list:to::save:to::list
```

### loading lists
after you've saved a list, you might want to load the list. When loading the list, use `de_stringify_list(string_to_load, parsing_sign)`. It would load the list by parsing the string, handling edge cases.

Example:
```
>>> stringify_list('list:to::save:to::list', ':')
output: ['list', 'to:save', 'to:list']
```


## limitations

### limitations for content.save()
because it opens and closes file every time using this function, it is recommended to merge strings first before using this function.
For instance, if you want to save:

```
first line
second line
third line
```

and you write:
```
example.save('first line')
example.save('second line')
example.save('third line')
```

it would be cost-inefficient. rather, use `\n` and write:

```
save_string = 'first line\n'
save_string += 'second line\n'
save_string += 'third line\n'

example.save(save_string)
```


### limitations for stringify_list()
because this isn't really as robust as JSON files, this can only save lists. when you want to save a variable name and a list, write:

```
string_one = True
string_two = 2
string_three = 'three'
string_three_to_save = easyfile.stringify_list([string_three], ':')
#only write stringify_list on elements you know are going to have strings and edge cases on it

save_string = f'string_one:{string_one}\nstring_two:{string_two}\nstring_three:{string_three_to_save}'
```