Move file reading docs to cairo (#1997)

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

---------

Co-authored-by: Kamil Jankowski <[email protected]>
Co-authored-by: Piotr Magiera <[email protected]>

docs/src/appendix/snforge-library/fs.md

@@ -2,9 +2,91 @@
 
 Module containing functions for interacting with the filesystem.
 
-* [`read_txt`](fs/read_txt.md) - reads and parses plain text file content into an array of felts
-* [`parse_txt`](fs/parse_txt.md) - parses plain text file content and tries to deserialize it into the
- specified type
-* [`read_json`](fs/read_json.md) - reads and parses json file content into an array of felts
-* [`parse_json`](fs/parse_json.md) - parses json file content and tries to deserialize it into the specified
- type
+## `File`
+```
+trait FileTrait {
+ fn new(path: ByteArray) -> File;
+}
+```
+
+## `FileParser<T>`
+```rust
+trait FileParser<T, +Serde<T>> {
+ fn parse_txt(file: @File) -> Option<T>;
+ fn parse_json(file: @File) -> Option<T>;
+}
+```
+
+## `read_txt` & `read_json`
+```rust
+fn read_txt(file: @File) -> Array<felt252>;
+fn read_json(file: @File) -> Array<felt252>;
+```
+
+
+## File format
+Some rules have to be checked when providing a file for snforge, in order for correct parsing behavior.
+Different ones apply for JSON and plain text files.
+
+### Plain text files
+- Elements have to be separated with newlines
+- Elements have to be either:
+ - integers in range of `[0, P)` where P is [`Cairo Prime`](https://book.cairo-lang.org/ch02-02-data-types.html?highlight=prime#felt-type) either in decimal or `0x` prefixed hex format
+ - single line short strings (`felt252`) of length `<=31` surrounded by `''` i.e., `'short string'`, new lines can be used with `\n` and `'` with `\'`
+ - single line strings (`ByteArray`) surrounded by `""` i.e., `"very very very very loooooong string"`, new lines can be used with `\n` and `"` with `\"`
+
+
+### JSON files
+- Elements have to be either:
+ - integers in range of `[0, P)` where P is [`Cairo Prime`](https://book.cairo-lang.org/ch02-02-data-types.html?highlight=prime#felt-type)
+ - single line strings (`ByteArray`) i.e. `"very very very very loooooong string"`, new lines can be used with `\n` and `"` with `\"`
+ - array of integers or strings fulfilling the above conditions
+
+> ⚠️ **Warning**
+>
+> A JSON object is an unordered data structure. To make reading JSONs deterministic, the values are read from the JSON in an order that is alphabetical in respect to JSON keys.
+> Nested JSON values are sorted by the flattened format keys `(a.b.c)`.
+
+
+## Example
+
+For example, this plain text file content:
+```txt
+1
+2
+'hello'
+10
+"world"
+```
+or this JSON file content:
+```json
+{
+ "a": 1,
+ "nested": {
+ "b": 2,
+ "c": 448378203247
+ },
+ "d": 10,
+ "e": "world"
+}
+``` 
+
+(note that short strings cannot be used in JSON file)
+
+could be parsed to the following struct in cairo, via `parse_txt`/`parse_json`:
+```rust
+A {
+ a: 1, 
+ nested: B {
+ b: 2,
+ c: 'hello',
+ }, 
+ d: 10,
+ e: "world"
+}
+```
+
+or to an array, via `read_txt`/`read_json`:
+```rust
+array![1, 2, 'hello', 10, 0, 512970878052, 5]
+```

snforge_std/src/fs/file_operations.cairo

@@ -4,10 +4,12 @@ use super::super::_cheatcode::handle_cheatcode;
 
 #[derive(Drop, Clone)]
 struct File {
- path: ByteArray // relative path
+ path: ByteArray
 }
 
 trait FileTrait {
+ /// Creates a file struct used for reading json / text
+ /// `path` - a path to file in ByteArray form, relative to the package root
  fn new(path: ByteArray) -> File;
 }
 
@@ -17,6 +19,8 @@ impl FileTraitImpl of FileTrait {
  }
 }
 
+/// `file` - a `File` struct to read text data from
+/// Returns an array of felts read from the file, panics if read was not possible
 fn read_txt(file: @File) -> Array<felt252> {
  let content = handle_cheatcode(
  cheatcode::<'read_txt'>(byte_array_as_felt_array(file.path).span())
@@ -35,6 +39,8 @@ fn read_txt(file: @File) -> Array<felt252> {
  result
 }
 
+/// `file` - a `File` struct to read json data from
+/// Returns an array of felts read from the file, panics if read was not possible, or json was incorrect
 fn read_json(file: @File) -> Array<felt252> {
  let content = handle_cheatcode(
  cheatcode::<'read_json'>(byte_array_as_felt_array(file.path).span())
@@ -54,7 +60,13 @@ fn read_json(file: @File) -> Array<felt252> {
 }
 
 trait FileParser<T, impl TSerde: Serde<T>> {
+ /// Reads from the text file and tries to deserialize the result into given type with `Serde`
+ /// `file` - File instance
+ /// Returns an instance of `T` if deserialization was possible
  fn parse_txt(file: @File) -> Option<T>;
+ /// Reads from the json file and tries to deserialize the result into given type with `Serde`
+ /// `file` - File instance
+ /// Returns an instance of `T` if deserialization was possible
  fn parse_json(file: @File) -> Option<T>;
 }