Documentation and Cargot.toml updates for publishing

gabhijit · gabhijit · commit b819f8e545e3 · 2021-11-08T13:43:57.000+05:30
diff --git a/README.md b/README.md
@@ -1,11 +1,15 @@
 # Hampi - ASN.1 compiler in Rust
 
-The Goal of this project is to implement an ASN.1 Compiler in Rust which can generate Rust bindings for different ASN.1 specifications, which can be used in those protocol implementations in Rust.
+The Goal of this project is to implement an ASN.1 Compiler in Rust which can generate Rust bindings for different ASN.1 specifications, which can be used in various protocol implementations in Rust.
+
+While it is certainly desirable to have a fully compliant ASN.1 Compiler, initial focus of the project is to be able to generate code that can be used in other software. First goal is to work with 3GPP specifications for protocols like Radio Network Access Protocl (RANAP), S1 Application protocl (S1AP) and NG Application Protocol (NGAP). Consequently current implementation also focuses on codecs used by these specifications viz. Aligned Packed Encoding Rules (APER).
+
+The use cases targeted by this implementation are similar to the use cases targeted by `asn1c` compiler, which generates `C` bindings from the ASN.1 Specifications.
 
 This project is divided into three crates -
 
-1. asn1-compiler: This crate provides the actual ASN.1 Compiler.
-2. asn-codecs: Support for different encodings supported by individual ASN.1 specifications is provided in this crate. Currently only APER Codec is supported. Each Codec is supported as a `trait` implementing `encode` and `decode` functions.
+1. asn1-compiler: This crate provides the actual ASN.1 Compiler. Typically a utility will be provided, that will generate Rust structures starting with ASN.1 Specifications. Basic working features required to work with the 3GPP specifications is provided by the compiler, this includes Parameterized Types, Information Object Classes and Type Constraints.
+2. asn-codecs: Support for different encodings supported by individual ASN.1 specifications is provided in this crate. Currently only APER Codec is supported. Each Codec is supported as a `trait` implementing `encode` and `decode` functions. Support for different 'encoding rules' will be implemented in this trait and then the derive macros will utilize this code to actually generate the encoding support for Rust Structures generated by the compiler above.
 3. asn-codecs-derive: This crate provides the `derive` macros for the codecs in `asn-codecs`. The code generated using `asn-compiler` can be directed to `derive` appropriate codecs by passing the flags during compilation.
 
 ## Status
@@ -14,10 +18,11 @@ Currently specifications from the `specs/` directory can be compiled into respec
 
 ## Getting Started
 
+The simplest way to try out this in action is - `cargo run --release specs/ngap/NGAP-*  > ngap.rs` and then take a look at generated `ngap` module. (Better CLI support is coming soon.)
+
 ### Running Test Cases
 
 1. Test cases can be run through `cargo test`.
 2. Right now `examples/` directory contains simple `decode` test cases for modules generated using the `asn-compiler`. This support will be improved to include the generated modules using mechanisms like `build.rs`.
 
 
-
diff --git a/asn-compiler/Cargo.toml b/asn-compiler/Cargo.toml
@@ -1,14 +1,17 @@
 [package]
-name = "hampi"
-version = "0.0.1"
+name = "asn1-compiler"
+version = "0.1.0"
 authors = ["Abhijit Gadgil <gabhijit@iitbombay.org>"]
 edition = "2018"
 description = "ASN.1 Compiler in Rust."
-repository = "https://github.com/gabhijit/intermodal.git"
-license = "MIT or Apache-2.0"
+keywords = ["asn1", "per"]
+repository = "https://github.com/gabhijit/hampi.git"
+license-file = "LICENSE"
 readme = "README.md"
+include = ["src/**/*.rs", "README.md", "Cargo.toml", "LICENSE", "LICENSE-MIT", "LICENSE-Apache2"]
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[badges]
+maintenance = { status = "actively-developed" }
 
 [dependencies]
 lazy_static = { version = "1.4.0" }
diff --git a/asn-compiler/LICENSE b/asn-compiler/LICENSE
@@ -0,0 +1 @@
+../LICENSE
diff --git a/asn-compiler/LICENSE-Apache2 b/asn-compiler/LICENSE-Apache2
@@ -0,0 +1 @@
+../LICENSE-Apache2
diff --git a/asn-compiler/LICENSE-MIT b/asn-compiler/LICENSE-MIT
@@ -0,0 +1 @@
+../LICENSE-MIT
diff --git a/asn-compiler/README.md b/asn-compiler/README.md
@@ -0,0 +1 @@
+../README.md
diff --git a/asn-compiler/src/bin/hampi-asn1c.rs b/asn-compiler/src/bin/hampi-asn1c.rs
@@ -3,7 +3,7 @@
 use std::fs::File;
 use std::io;
 
-use hampi::Asn1Compiler;
+use asn1_compiler::Asn1Compiler;
 
 fn main() -> io::Result<()> {
     let args: Vec<String> = std::env::args().collect();
@@ -13,9 +13,9 @@ fn main() -> io::Result<()> {
     for arg in &args[1..] {
         eprintln!("File: {}", arg);
         let file = File::open(arg)?;
-        let mut tokens = hampi::tokenizer::tokenize(file)?;
+        let mut tokens = asn1_compiler::tokenizer::tokenize(file)?;
         eprintln!("tokens: {}", tokens.len());
-        let mut modules = hampi::parser::parse(&mut tokens)?;
+        let mut modules = asn1_compiler::parser::parse(&mut tokens)?;
 
         loop {
             let module = modules.pop();
diff --git a/asn-compiler/src/error.rs b/asn-compiler/src/error.rs
@@ -31,7 +31,7 @@ pub enum Error {
     /// Error related to resolving constraints for a type.
     ConstraintError(String),
 
-    /// Error related to resolving constraints for a type.
+    /// Error related to code generation from resolved types.
     CodeGenerationError(String),
 }
 
diff --git a/asn-compiler/src/generator/int.rs b/asn-compiler/src/generator/int.rs
@@ -1,6 +1,6 @@
 //! Code Generation module
 
-use heck::{CamelCase, ShoutySnakeCase, SnakeCase};
+use heck::{ShoutySnakeCase, SnakeCase};
 use proc_macro2::{Ident, Literal, Span, TokenStream};
 
 use quote::quote;
diff --git a/asn-compiler/src/lib.rs b/asn-compiler/src/lib.rs
@@ -3,21 +3,26 @@
 //!
 //! Goal of the project is to develop a compiler for ASN.1 specifications primarily for
 //! applicatoins in working with 3GPP standards. The idea is to be able to generate Rust (and
-//! possibly other language(s)) bindings from ASN.1 Specifications.
+//! possibly other language(s)) bindings from ASN.1 Specifications. Initial support is targetted
+//! for generating Rust bindings.
 
+//! Error type for different types of Compilation Errors.
 #[macro_use]
 pub mod error;
 
 /// ASN.1 Tokenizer and Related Types
 #[macro_use]
 pub mod tokenizer;
 
-/// ASN1. Parser and Related Types
+/// ASN.1 Parser and Related Types
 pub mod parser;
 
+/// ASN.1 Compiler Wrapper implmentation.
 mod compiler;
 pub use compiler::Asn1Compiler;
 
+/// Types and Constraints resolution from the parsed types.
 pub mod resolver;
 
+/// Code Generation from the resolved types.
 pub mod generator;
diff --git a/asn-compiler/src/parser/asn/mod.rs b/asn-compiler/src/parser/asn/mod.rs
@@ -1,14 +1,20 @@
 //! Submodule for ASN.1 Specific handling of the Parser
 
+/// ASN.1 Modules (Single ASN.1 Files) handling functionality.
 mod module;
 pub(super) use module::parse_module;
 
+/// ASN.1 Definitions (Type, Value, CLASS etc.)
 mod defs;
 
+/// Implementation of Parsing of ASN.1 Types.
 pub(crate) mod types;
 
+/// Implementation of Parsing of ASN.1 Values (`Type := Value`)
 pub(crate) mod values;
 
+/// Implementation of Object Identifier.
 mod oid;
 
+/// Output Types of the Parsers.
 pub(crate) mod structs;
diff --git a/asn-compiler/src/parser/asn/structs/defs.rs b/asn-compiler/src/parser/asn/structs/defs.rs
@@ -141,7 +141,7 @@ macro_rules! is_assignment_kind {
                 if let $variant(ref _x) = self.kind {
                     true
                 } else {
-                false
+                    false
                 }
             }
         }
diff --git a/asn-compiler/src/tokenizer/mod.rs b/asn-compiler/src/tokenizer/mod.rs
@@ -1082,7 +1082,7 @@ mod tests {
             BitHexStringTestCase {
                 input: b"'01 0101\n\t0101\n00'h",
                 success: true,
-                span_end_line: 2,
+                span_end_line: 3,
             },
         ];
         for t in test_cases {
@@ -1092,6 +1092,14 @@ mod tests {
             if result.is_ok() {
                 let tokens = result.unwrap();
                 assert!(tokens.len() == 1, "{:#?}", tokens[0]);
+                let token = &tokens[0];
+                assert!(
+                    token.span.end.line == t.span_end_line,
+                    "input: {:#?}, token end: {}, tc: span_end_line {}",
+                    t.input,
+                    token.span.end.line,
+                    t.span_end_line
+                );
             }
         }
     }
diff --git a/codecs/Cargo.toml b/codecs/Cargo.toml
@@ -1,10 +1,16 @@
 [package]
 name = "asn-codecs"
 version = "0.1.0"
+description = "ASN.1 Codecs for Rust Types."
 authors = ["Abhijit Gadgil <gabhijit@iitbombay.org>"]
+keywords = ["asn1", "per", "decoder", "encoder"]
 edition = "2018"
+license-file = "LICENSE"
+repository = "https://github.com/gabhijit/hampi.git"
+include = ["src/**/*.rs", "Cargo.toml", "LICENSE", "LICENSE-MIT", "LICENSE-Apache2"]
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[badges]
+maintenance = { status = "actively-developed" }
 
 [dependencies]
 bitvec = { version = "0.22" }
diff --git a/codecs/LICENSE b/codecs/LICENSE
@@ -0,0 +1 @@
+../LICENSE
diff --git a/codecs/LICENSE-Apache2 b/codecs/LICENSE-Apache2
@@ -0,0 +1 @@
+../LICENSE-Apache2
diff --git a/codecs/LICENSE-MIT b/codecs/LICENSE-MIT
@@ -0,0 +1 @@
+../LICENSE-MIT
diff --git a/codecs/src/aper/mod.rs b/codecs/src/aper/mod.rs
@@ -185,14 +185,26 @@ impl AperCodecData {
         Ok(bytes)
     }
 
+    /// Get's the current `key` value.
+    ///
+    /// This value will be used by a decoder to determine which 'decode' function is to be called
+    /// (for example in an `enum`, it will be used to determine which `variant` of the `enum` will
+    /// be decoded.
     pub fn get_key(&self) -> Option<i128> {
         self.key
     }
 
+    /// Sets the current `key` value.
+    ///
+    /// During decoding 'open' types, the 'key' used to decode the type further is determined by a
+    /// `key_value` field. ie. a field with attribute `key_value` set in a struct (derived from a
+    /// SEQUENCE ASN.1 type.) This value is passed to the 'decoder' logic further through `set_key`
+    /// function, which updates the internal state of the decoder data.
     pub fn set_key(&mut self, key: i128) -> () {
         let _ = self.key.replace(key);
     }
 
+    /// Dump current 'offset'.
     pub fn dump(&self) -> () {
         eprintln!("Offset: {}", self.offset);
     }
diff --git a/codecs/src/lib.rs b/codecs/src/lib.rs
@@ -1,2 +1,4 @@
+//! Codec support for ASN.1 Types.
+
 #![allow(dead_code)]
 pub mod aper;
diff --git a/codecs_derive/Cargo.toml b/codecs_derive/Cargo.toml
@@ -1,22 +1,27 @@
 [package]
 name = "asn_codecs_derive"
 authors = ["Abhijit Gadgil <gabhijit@iitbombay.org>"]
+description = "ASN.1 Codecs derive Macros"
+keywords = ["asn1", "per"]
 version = "0.1.0"
 edition = "2018"
+license-file = "LICENSE"
+repository = "https://github.com/gabhijit/hampi.git"
+include = ["src/**/*.rs", "Cargo.toml", "LICENSE", "LICENSE-MIT", "LICENSE-Apache2"]
 
+[badges]
+maintenance = { status = "actively-developed" }
 
 [lib]
 proc-macro = true
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
-asn-codecs = { path = "../codecs" }
+asn-codecs = { path = "../codecs" , version = "=0.1.0"}
 bitvec = { version = "0.22" }
 proc-macro2 = { version = "1.0" }
 quote = { version = "1.0" }
 syn = { version = "1.0" , features = ["extra-traits"]}
 
 [dev-dependencies]
 trybuild = { version = "1.0" }
-hex = "*"
+hex =  { version = "0.4.3" }
diff --git a/codecs_derive/LICENSE b/codecs_derive/LICENSE
@@ -0,0 +1 @@
+../LICENSE
diff --git a/codecs_derive/LICENSE-Apache2 b/codecs_derive/LICENSE-Apache2
@@ -0,0 +1 @@
+../LICENSE-Apache2
diff --git a/codecs_derive/LICENSE-MIT b/codecs_derive/LICENSE-MIT
@@ -0,0 +1 @@
+../LICENSE-MIT
diff --git a/codecs_derive/src/lib.rs b/codecs_derive/src/lib.rs
@@ -1,3 +1,5 @@
+//! Derive Macros for Rust Structures generated by ASN.1 Compiler
+
 use proc_macro::TokenStream;
 use syn::{parse_macro_input, DeriveInput};
 
@@ -7,6 +9,7 @@ mod symbol;
 
 mod aper;
 
+/// APER Codec Derive Macro support.
 #[proc_macro_derive(AperCodec, attributes(asn))]
 pub fn derive(input: TokenStream) -> TokenStream {
     let ast = parse_macro_input!(input as DeriveInput);
diff --git a/examples/tests/11-ranap.rs b/examples/tests/11-ranap.rs
@@ -1,4 +1,4 @@
-#![allow(non_camel_case_types, dead_code)]
+#![allow(non_camel_case_types, dead_code, unreachable_patterns)]
 
 use asn_codecs::aper::*;
 use asn_codecs_derive::*;
diff --git a/examples/tests/12-s1ap.rs b/examples/tests/12-s1ap.rs
@@ -1,6 +1,5 @@
-#![allow(non_camel_case_types, dead_code)]
+#![allow(non_camel_case_types, dead_code, unreachable_patterns)]
 
-use asn_codecs::aper::*;
 use asn_codecs_derive::*;
 use bitvec::order::Msb0;
 use bitvec::vec::BitVec;
diff --git a/examples/tests/13-ngap.rs b/examples/tests/13-ngap.rs
@@ -1,6 +1,5 @@
 #![allow(non_camel_case_types, dead_code)]
 
-use asn_codecs::aper::*;
 use asn_codecs_derive::*;
 use bitvec::order::Msb0;
 use bitvec::vec::BitVec;

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ pub enum Error {`
`31`	`31`	`/// Error related to resolving constraints for a type.`
`32`	`32`	`ConstraintError(String),`
`33`	`33`
`34`		`- /// Error related to resolving constraints for a type.`
	`34`	`+ /// Error related to code generation from resolved types.`
`35`	`35`	`CodeGenerationError(String),`
`36`	`36`	`}`
`37`	`37`