Repository: huff-language/huff-rs
Pull request #158 (2022-07-04 12:32:06)

docs + nightly stage release
## Overview

Prepares huff-rs for stable release 🚀 

Add stage checkout for nightly release

## Checklist

~~- [ ] Readme with benchmarks~~
- [x] CLI Docs
- [x] Lexer Docs
- [x] Parser Docs
- [x] Codegen Docs
- [x] Core Docs


Patch:
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 3d1607e..9ef139a 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -111,6 +111,11 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v2
 
+      - name: Checkout stage branch if Nightly
+        if: ${{ env.IS_NIGHTLY }}
+        run: |
+          git checkout stage
+
       - name: Install toolchain
         uses: actions-rs/toolchain@v1
         with:
@@ -216,6 +221,11 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v2
 
+      - name: Checkout stage branch if Nightly
+        if: ${{ env.IS_NIGHTLY }}
+        run: |
+          git checkout stage
+
       # Moves the `nightly` tag to `HEAD`
       - name: Move nightly tag
         if: ${{ env.IS_NIGHTLY }}
diff --git a/README.md b/README.md
index 94c15a9..a05c800 100644
--- a/README.md
+++ b/README.md
@@ -4,14 +4,6 @@
 
 > `huff-rs` is a [Huff](https://github.com/huff-language) compiler built in rust.
 
-<br />
-<hr />
-
-> **Warning**
->
-> This repo contains highly experimental code. Expect rapid iteration. **Use at your own risk.**
-
-<hr />
 
 ## What is a Huff?
 
@@ -138,6 +130,21 @@ When the PR checklist isn't complete, it is **highly** recommended to make it a
 For breaking changes: make sure to edit the [excalidraw asset](https://excalidraw.com/#json=9YvTZp-rY9NOQnX9TC8Dz,sVM8vpgvQqGiXNXrBNshTg) and export the file to [./assets/huffc.excalidraw](./assets/huffc.excalidraw) along with an image to [./assets/huffc.png](./assets/huffc.png).
 
 
+## Safety
+
+> **Warning**
+>
+> This is **experimental software** and is provided on an "as is" and "as available" basis.
+> Expect rapid iteration and **use at your own risk**.
+>
+> This code is **not designed for safety**.
+> - There are untested invariants in the code that may break.
+> - **You can easily shoot yourself in the foot if you're not careful.**
+> - You should thoroughly read the documentation and examples.
+>
+> We **do not give any warranties** and **will not be liable for any loss** incurred through any use of this codebase.
+
+
 ## Acknowledgements
 
 The original [Huff Language](https://github.com/huff-language) compiler: [`huffc`](https://github.com/huff-language/huffc).
diff --git a/huff_cli/README.md b/huff_cli/README.md
index 9e38b75..e8f5651 100644
--- a/huff_cli/README.md
+++ b/huff_cli/README.md
@@ -13,18 +13,19 @@ USAGE:
     huffc [OPTIONS] [--] [PATH]
 
 ARGS:
-    <PATH>    The main path
+    <PATH>    The contract(s) to compile
 
 OPTIONS:
     -a, --artifacts                       Whether to generate artifacts or not
     -b, --bytecode                        Generate and log bytecode
     -d, --output-directory <OUTPUTDIR>    The output directory [default: ./artifacts]
+    -g, --interface                       Generate solidity interface for a Huff artifact
     -h, --help                            Print help information
     -i, --inputs <INPUTS>...              The input constructor arguments
     -n, --interactive                     Interactively input the constructor args
     -o, --output <OUTPUT>                 The output file path
     -p, --print                           Prints out to the terminal
-    -s, --source-path <SOURCE>            The contracts source path [default: ./src]
+    -s, --source-path <SOURCE>            The contracts source path [default: ./contracts]
     -v, --verbose                         Verbose output
     -V, --version                         Print version information
     -z, --optimize                        Optimize compilation [WIP]
@@ -133,6 +134,7 @@ $ huffc -b -i 100, 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef ./contracts/exampl
 - `-v` or `--verbose`: Outputs detailed logs to the terminal using the [tracing](https://crates.io/crates/tracing) crate.
 - `-V` or `--version`: Prints the version of `huffc`.
 - `-z` or `--optimize`: Optimizes the contract compilation - a work in progress.
+- `-g` or `--interface`: Generates a solidity interface for the contract.
 
 
 ## Building huffc from source
diff --git a/huff_cli/src/huffc.rs b/huff_cli/src/huffc.rs
index 8f998c9..c20a643 100644
--- a/huff_cli/src/huffc.rs
+++ b/huff_cli/src/huffc.rs
@@ -24,7 +24,7 @@ use yansi::Paint;
 #[derive(ClapParser, Debug, Clone)]
 #[clap(name = "huffc", version, about, long_about = None)]
 struct Huff {
-    /// The main path
+    /// The contract(s) to compile.
     pub path: Option<String>,
 
     /// The contracts source path.
diff --git a/huff_codegen/src/irgen/statements.rs b/huff_codegen/src/irgen/statements.rs
index 7a26477..21a881b 100644
--- a/huff_codegen/src/irgen/statements.rs
+++ b/huff_codegen/src/irgen/statements.rs
@@ -101,7 +101,6 @@ pub fn statement_gen(
         StatementType::BuiltinFunctionCall(bf) => {
             // Generate code for a `BuiltinFunctionCall`
             // __codesize, __tablesize, or __tablestart
-            // TODO: Inline docs
             tracing::info!(target: "codegen", "RECURSE BYTECODE GOT BUILTIN FUNCTION CALL: {:?}", bf);
             match bf.kind {
                 BuiltinFunctionKind::Codesize => {
diff --git a/huff_lexer/README.md b/huff_lexer/README.md
index 59b9bc0..eb13af5 100644
--- a/huff_lexer/README.md
+++ b/huff_lexer/README.md
@@ -2,7 +2,10 @@
 
 Lexical analyzer for the Huff Language.
 
-The Huff Lexer is instantiable with a `FullFileSource` containing the source code, a `FileSource`, and "spans" (a `Vec<(FileSource, Span)>`).
+The Huff Lexer is instantiable with a `FullFileSource`. `FullFileSource` is composed of
+- the file source code
+- a `FileSource`
+- `spans` == (`Vec<(FileSource, Span)>`).
 
 Once instantiated, the lexer can be used to iterate over the tokens in the source code.
 It also exposes a number of practical methods for accessing information about the source code
diff --git a/huff_lexer/src/lib.rs b/huff_lexer/src/lib.rs
index 5e27933..3c9216b 100644
--- a/huff_lexer/src/lib.rs
+++ b/huff_lexer/src/lib.rs
@@ -39,7 +39,7 @@ pub enum Context {
 /// The lexer encapsulated in a struct.
 pub struct Lexer<'a> {
     /// The source code as peekable chars.
-    /// SHOULD NOT BE MODIFIED EVER!
+    /// WARN: SHOULD NEVER BE MODIFIED!
     pub reference_chars: Peekable<Chars<'a>>,
     /// The source code as peekable chars.
     pub chars: Peekable<Chars<'a>>,
@@ -48,7 +48,7 @@ pub struct Lexer<'a> {
     /// The current lexing span.
     pub span: RefCell<Span>,
     /// The previous lexed Token.
-    /// Cannot be a whitespace.
+    /// NOTE: Cannot be a whitespace.
     pub lookback: Option<Token>,
     /// If the lexer has reached the end of file.
     pub eof: bool,
@@ -73,8 +73,8 @@ impl<'a> Lexer<'a> {
         }
     }
 
-    // `// #include "./Utils.huff"`
     /// Lex all imports
+    /// Example import: `// #include "./Utils.huff"`
     pub fn lex_imports(source: &str) -> Vec<String> {
         let mut imports = vec![];
         let mut peekable_source = source.chars().peekable();
diff --git a/huff_parser/README.md b/huff_parser/README.md
index 76d5b3f..904c072 100644
--- a/huff_parser/README.md
+++ b/huff_parser/README.md
@@ -4,7 +4,7 @@ A parser for the Huff Language.
 
 The Huff Parser accepts a vector of Tokens during instantiation.
 
-Once instantiated, the par&ser will construct an AST from the Token Vector when the `parse`
+Once instantiated, the parser will construct an AST from the Token Vector when the `parse`
 method is called.
 
 It also exposes a number of practical methods for accessing information about the source code
@@ -32,6 +32,27 @@ let tokens = lexer.into_iter().map(|x| x.unwrap()).collect::<Vec<Token>>();
 let mut parser = Parser::new(tokens, None);
 
 // Parse into an AST
-parser.parse();
+let unwrapped_contract = parser.parse().unwrap();
 assert_eq!(parser.current_token.kind, TokenKind::Eof);
+
+// Validate the unwrapped contract
+let expected_contract = Contract {
+  macros: vec![
+    MacroDefinition {
+      name: "HELLO_WORLD".to_string(),
+      parameters: vec![],
+      statements: vec![],
+      takes: 0,
+      returns: 0,
+      span: AstSpan(vec![Span { start: 0, end: 7, file: None }, Span { start: 8, end: 13, file: None }, Span { start: 14, end: 25, file: None }, Span { start: 25, end: 26, file: None }, Span { start: 26, end: 27, file: None }, Span { start: 28, end: 29, file: None }, Span { start: 30, end: 35, file: None }, Span { start: 35, end: 36, file: None }, Span { start: 36, end: 37, file: None }, Span { start: 37, end: 38, file: None }, Span { start: 39, end: 46, file: None }, Span { start: 46, end: 47, file: None }, Span { start: 47, end: 48, file: None }, Span { start: 48, end: 49, file: None }, Span { start: 50, end: 51, file: None }, Span { start: 51, end: 52, file: None }]),
+    }
+  ],
+  invocations: vec![],
+  imports: vec![],
+  constants: vec![],
+  functions: vec![],
+  events: vec![],
+  tables: vec![],
+};
+assert_eq!(unwrapped_contract, expected_contract);
 ```
\ No newline at end of file
diff --git a/huffup/README.md b/huffup/README.md
index ed6c4e3..0edb59f 100644
--- a/huffup/README.md
+++ b/huffup/README.md
@@ -7,7 +7,9 @@ _Forked from [foundry](https://github.com/foundry-rs/foundry/tree/master/foundry
 
 ## Installing
 
-`curl -L https://get.huff.sh | bash`
+`curl -L get.huff.sh | bash` (installs the `huffup` installer)
+
+Run `huffup` to install the latest version of `huffc`.
 
 
 ## Usage


Test patch:
diff --git a/huff_core/tests/erc20.rs b/huff_core/tests/erc20.rs
index 90a7279..94fd5cd 100644
--- a/huff_core/tests/erc20.rs
+++ b/huff_core/tests/erc20.rs
@@ -44,6 +44,5 @@ fn test_erc20_compile() {
     // Full expected bytecode output (generated from huffc)
     let expected_bytecode = "336000556101ac80600e3d393df360003560e01c8063a9059cbb1461004857806340c10f19146100de57806370a082311461014e57806318160ddd1461016b578063095ea7b314610177578063dd62ed3e1461018e575b600435336024358160016000526000602001526040600020548082116100d8578190038260016000526000602001526040600020558281906001600052600060200152604060002054018360016000526000602001526040600020556000527fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef60206000a3600160005260206000f35b60006000fd5b60005433146100ed5760006000fd5b600435600060243582819060016000526000602001526040600020540183600160005260006020015260406000205580600254016002556000527fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef60206000a35b600435600160005260006020015260406000205460005260206000f35b60025460005260206000f35b602435600435336000526000602001526040600020555b60243560043560005260006020015260406000205460005260206000f3";
 
-    // TODO: Check the bytecode
     assert_eq!(artifact.bytecode.to_lowercase(), expected_bytecode.to_lowercase());
 }
diff --git a/huff_core/tests/erc721.rs b/huff_core/tests/erc721.rs
index 3a0fd64..2d022b5 100644
--- a/huff_core/tests/erc721.rs
+++ b/huff_core/tests/erc721.rs
@@ -43,9 +43,5 @@ fn test_erc721_compile() {
     // depth first)
     let expected_bytecode = "336000556103b180600e3d393df360003560e01c8063a9059cbb146100a057806342842e0e146101a3578063b88d4fde146101a9578063095ea7b31461027b578063a22cb46514610310578063081812fc146102f357806340c10f19146101af57806370a082311461025e5780636352211e1461039457806306fdde031461035e57806395d89b4114610364578063c87b56dd1461036a57806301ffc9a714610370578063e985e9c514610376575b6044356024356004358083600160005260006020015260406000205491146100c75761019d565b8033146101005733816000526000602001526040600020546101005782600260005260006020015260406000205433146101005761019d565b6001816003600052600060200152604060002054038160036000526000602001526040600020558160036000526000602001526040600020546001018260036000526000602001526040600020558183600160005260006020015260406000205560008360026000526000602001526040600020557fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef60206000a4005b60006000fd5b60006000fd5b60006000fd5b60005433146101be5760006000fd5b6024356004356000826001600052600060200152604060002054156101e257610258565b8160036000526000602001526040600020546001018260036000526000602001526040600020558183600160005260006020015260406000205560008360026000526000602001526040600020557fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef60006000a4005b60006000fd5b600435600360005260006020015260406000205460005260206000f35b6024358060016000526000602001526040600020548033143382600052600060200152604060002054176102ae576102ed565b60043580836002600052600060200152604060002055907f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b92560006000a4005b60006000fd5b600435600260005260006020015260406000205460005260206000f35b60243560043533600052600060200152604060002055600435336024356000527f17307eab39ab6107e8899845ad3d59bd9653f200f220920489ca2b5937696c3160006000a4005b60006000fd5b60006000fd5b60006000fd5b60006000fd5b60006000fd5b60243560043560005260006020015260406000205460005260206000f35b600435600160005260006020015260406000205460005260206000f3";
 
-    println!("Expected bytecode: {}", expected_bytecode.to_lowercase());
-    println!("Current bytecode: {}", artifact.bytecode.to_lowercase());
-
-    // TODO: Check the bytecode
     assert_eq!(artifact.bytecode.to_lowercase(), expected_bytecode.to_lowercase());
 }