var interface change and docs (#1962)

<!-- Reference any GitHub issues resolved by this PR -->

Closes #1950

## Introduced changes

<!-- A brief description of the changes -->

-

## 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`

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Forge
+
+#### Changed
+
+- `var` now supports `ByteArray` with double quoting, and returns `Array<felt252>` instead of a single `felt252`
+
+
 ## [0.21.0] - 2024-04-03
 
 ### Forge

crates/forge/tests/data/env/src/lib.cairo

@@ -6,8 +6,15 @@ mod tests {
  fn reading_env_vars() {
  let felt252_value = var("FELT_ENV_VAR");
  let short_string_value = var("STRING_ENV_VAR");
+ let mut byte_array_value = var("BYTE_ARRAY_ENV_VAR").span();
 
- assert(felt252_value == 987654321, 'invalid felt value');
- assert(short_string_value == 'abcde', 'invalid short string value');
+ assert(felt252_value == array![987654321], 'invalid felt value');
+ assert(short_string_value == array!['abcde'], 'invalid short string value');
+
+ let byte_array = Serde::<ByteArray>::deserialize(ref byte_array_value).unwrap();
+ assert(
+ byte_array == "that is a very long environment variable that would normally not fit",
+ 'Invalid ByteArray value'
+ )
  }
 }

crates/forge/tests/e2e/env.rs

@@ -9,6 +9,10 @@ fn env_var_reading() {
  let output = test_runner(&temp)
  .env("FELT_ENV_VAR", "987654321")
  .env("STRING_ENV_VAR", "'abcde'")
+ .env(
+ "BYTE_ARRAY_ENV_VAR",
+ r#""that is a very long environment variable that would normally not fit""#,
+ )
  .assert()
  .code(0);
 

crates/forge/tests/integration/env.rs

@@ -16,7 +16,7 @@ fn read_short_string() {
  #[test]
  fn read_short_string() {
  let result = var("MY_ENV_VAR");
- assert(result == 'env_var_value', 'failed reading env var');
+ assert(result == array!['env_var_value'], 'failed reading env var');
  }
  "#
  ));
@@ -36,7 +36,7 @@ fn read_felt252() {
  #[test]
  fn read_felt252() {
  let result = var("MY_ENV_VAR");
- assert(result == 1234567, 'failed reading env var');
+ assert(result == array![1234567], 'failed reading env var');
  }
  "#
  ));
@@ -47,6 +47,30 @@ fn read_felt252() {
  assert_passed(&result);
 }
 
+#[test]
+fn read_bytearray() {
+ let mut test = test_case!(indoc!(
+ r#"
+ use snforge_std::env::var;
+
+ #[test]
+ fn read_bytearray() {
+ let mut result = var("MY_ENV_VAR").span();
+ let result_bytearray = Serde::<ByteArray>::deserialize(ref result).unwrap();
+ assert(result_bytearray == "very long string literal very very long very very long", 'failed reading env var');
+ }
+ "#
+ ));
+ test.set_env(
+ "MY_ENV_VAR",
+ r#""very long string literal very very long very very long""#,
+ );
+
+ let result = run_test_case(&test);
+
+ assert_passed(&result);
+}
+
 #[test]
 fn read_overflow_felt252() {
  let mut test = test_case!(indoc!(
@@ -56,7 +80,7 @@ fn read_overflow_felt252() {
  #[test]
  fn read_overflow_felt252() {
  let result = var("MY_ENV_VAR");
- assert(result == 1, '');
+ assert(result == array![1], '');
  }
  "#
  ));

docs/src/appendix/snforge-library/env/var.md

@@ -1,21 +1,15 @@
 # `var`
 
-> `fn var(name: ByteArray) -> felt252`
+> `fn var(name: ByteArray) -> Array<felt252>`
 
-Read and parse felt252 or cairo short string (encoded as felt) value from an environment variable.
+Reads an environment variable, without parsing it.
 
-- `name` - name of an environment variable
+The serialized output is correlated with the inferred input type, same as during [reading from a file](../fs/read_txt.md#accepted-format).
 
-```rust
-use snforge_std::env::var;
+> 📝 **Note**
+> 
+> If you want snfoundry to treat your variable like a short string, surround it with 'single quotes'.
+>  
+> If you would like it to be serialized as a ByteArray, use "double quoting". It will be then de-serializable with `Serde`.
 
-#[test]
-fn reading_env_vars() {
- // ...
- let felt252_value = var("FELT_ENV_VAR");
- let short_string_value = var("STRING_ENV_VAR");
 
- assert(felt252_value == 987654321, 'invalid felt value');
- assert(short_string_value == 'abcde', 'invalid short string value');
-}
-```

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

@@ -35,6 +35,7 @@ fn test_parse_json() {
 }
 ```
 
+## Accepted format
 File content must have proper JSON Format with values satisfying the conditions:
  - 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)
  - strings of length `<=31`

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

@@ -29,7 +29,7 @@ fn test_parse_txt() {
  // ...
 }
 ```
-
+## Accepted format
 File content must consists of elements that:
 - have to be separated with newlines
 - have to be either:

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

@@ -23,6 +23,7 @@ fn test_read_json() {
 }
 ```
 
+## Accepted format
 File content must have proper JSON Format with values satisfying the conditions:
  - 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`) ie. `"very very very very loooooong string"`, new lines can be used with `\n` and `"` with `\"`

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

@@ -5,7 +5,7 @@
 Read and parses plain text file content to an array of felts.
 
 - `file` - a snapshot of an instance of the struct `File` that consists of the following fields:
- - `path` - Cairo string representing a path to a file relative to a package root.
+- `path` - Cairo string representing a path to a file relative to a package root.
 
 ```rust
 use snforge_std::fs::{ FileTrait, read_txt };
@@ -18,6 +18,7 @@ fn test_read_txt() {
 }
 ```
 
+## Accepted format
 File content must consists of elements that:
 - have to be separated with newlines
 - have to be either:

snforge_std/src/env/env_vars.cairo

@@ -1,7 +1,12 @@
 use starknet::testing::cheatcode;
 use super::super::byte_array::byte_array_as_felt_array;
 
-fn var(name: ByteArray) -> felt252 {
- let outputs = cheatcode::<'var'>(byte_array_as_felt_array(@name).span());
- *outputs[0]
+/// Reads an environment variable, without parsing it
+/// `name` - name of an environment variable
+/// Returns the read array of felts
+fn var(name: ByteArray) -> Array<felt252> {
+ let mut output_array: Array<felt252> = array![];
+ let result = cheatcode::<'var'>(byte_array_as_felt_array(@name).span());
+ output_array.append_span(result);
+ output_array
 }