add docs and readme

Author: andrewayoub

README.md

@@ -0,0 +1,82 @@
+# Dmidecoder parser with rust
+
+Convert Dmidecoder output into properly formated data (HashMap)
+
+## installation
+
+add dmidecoder parser to your dependencies
+```toml
+dmidecoder = {git="https://github.com/andrewayoub/dmidecoder.git"}
+```
+
+import as external crate
+```rust
+extern crate dmidecoder;
+use dmidecoder::dmidecoder::parse;
+```
+
+pass dmidecoder raw data to parse method
+```rust
+let sample = r#"
+Getting SMBIOS data from sysfs.
+SMBIOS 2.7 present.
+
+Handle 0x0000, DMI type 0, 24 bytes
+BIOS Information
+	Vendor: LENOVO
+	Version: 9BCN26WW
+	Release Date: 07/31/2014
+	Address: 0xE0000
+	Runtime Size: 128 kB
+	ROM Size: 4096 kB
+	Characteristics:
+		PCI is supported
+		BIOS is upgradeable
+		BIOS shadowing is allowed
+		Boot from CD is supported
+		Selectable boot is supported
+		EDD is supported
+		Japanese floppy for NEC 9800 1.2 MB is supported (int 13h)
+		Japanese floppy for Toshiba 1.2 MB is supported (int 13h)
+		5.25"/360 kB floppy services are supported (int 13h)
+		5.25"/1.2 MB floppy services are supported (int 13h)
+		3.5"/720 kB floppy services are supported (int 13h)
+		3.5"/2.88 MB floppy services are supported (int 13h)
+		8042 keyboard services are supported (int 9h)
+		CGA/mono video services are supported (int 10h)
+		ACPI is supported
+		USB legacy is supported
+		BIOS boot specification is supported
+		Targeted content distribution is supported
+		UEFI is supported
+	BIOS Revision: 0.26
+	Firmware Revision: 0.26
+
+Handle 0x0010, DMI type 13, 22 bytes
+BIOS Language Information
+	Language Description Format: Long
+	Installable Languages: 4
+		en|US|iso8859-1
+		fr|CA|iso8859-1
+		ja|JP|unicode
+		zh|TW|unicode
+	Currently Installed Language: en|US|iso8859-1
+
+    "#;
+
+    let sections = parse(sample);
+    println!("{:?}", sections["BIOS Information"].properties["Characteristics"].items)
+    
+```
+
+## Contribution
+Feel free to contribute by any modifications or improvements.
+
+## Tests
+you can rus tests using cargo
+```bash
+cargo test
+```
+
+## Thanks
+To [xmonader](https://github.com/xmonader) for his support.

src/lib.rs

@@ -1,49 +1,75 @@
 pub mod dmidecoder {
     use std::collections::HashMap;
- 
+    
+    /// Property represents a single item inside a section
+    /// it contains value and items as vector
+    /// you should have at least on of these fields set
     #[derive(Debug)]
     pub struct Property {
         pub value: String,
         pub items: Vec<String>,
     }
 
     impl Property {
+        /// Returns empty property
+        /// # examples
+        /// ```
+        /// let property: Property = Property::new();
+        /// ```
         pub fn new() -> Property {
             Property {
                 value: String::new(),
                 items: Vec::new(),
             }
         }
+        /// Check if the property is empty
+        /// # examples
+        /// ```
+        /// property.is_empty()
+        /// ```
         pub fn is_empty(&self) -> bool {
             return self.value.is_empty() && self.items.is_empty()
         }
     }
 
+    /// Section represents a full section of data
     #[derive(Debug)]
     pub struct Section {
         pub handle_line: String,
         pub properties: HashMap<String, Property>,
     }
 
     impl Section {
+        /// Returns empty Section
+        /// # examples
+        /// ```
+        /// let section: Section = Section::new();
+        /// ```
         fn new() -> Section {
             Section {
                 handle_line: String::new(),
                 properties: HashMap::new(),
             }
         }
+        /// Check if the section is empty
+        /// # examples
+        /// ```
+        /// section.is_empty()
+        /// ```
         fn is_empty(&self) -> bool {
             return self.handle_line.is_empty() && self.properties.is_empty()
         }
     }
 
+    /// State will be used in parsing
+    /// will indecate how to handle the current line
     #[derive(Debug)]
     enum State {
         Section,
         Kv,
         List,
     }
-
+    /// clean string by removing white spaces from the begining
     fn clean_str(line :&str) -> String {
         let mut i = 0;
         for c in line.chars() {
@@ -55,6 +81,7 @@ pub mod dmidecoder {
         }
         return String::from(line.to_string())
     }
+    /// get the current indentation level by counting the white spaces or taps
     fn get_indentation(line :&str) -> u8 {
         let mut count = 0;
         for c in line.chars() {
@@ -66,7 +93,7 @@ pub mod dmidecoder {
         }
         return count;
     }
-
+    /// decide the current state of the line
     fn get_state(state :State, line :&str, last_indentation :u8) -> State {
         let mut new_state = State::Section;
         let indentation = get_indentation(line);
@@ -93,7 +120,7 @@ pub mod dmidecoder {
         }
         return new_state;
     }
-
+    // Parse data into sections hashmap
     pub fn parse(data :&str) -> HashMap<String, Section> {
         let mut sections = HashMap::new();
         let mut state = State::Section;
@@ -104,12 +131,17 @@ pub mod dmidecoder {
         let mut last_indentation = 0;
 
         for line in data.lines() {
+            // decide state
             let indentation = get_indentation(line);
             state = get_state(state, line, last_indentation);
             last_indentation = indentation;
+            // match the state to parse each line
             match state {
                 State::Section => {
                     if line.starts_with("Handle") {
+                        // when we find handle line this means it's the begining of a new section
+                        // so we will push the last section if it's not empty
+                        // and create another one with the found handle line
                         if !current_section.is_empty() && !current_section_name.is_empty() {
                             if !current_property.is_empty() && !current_property_name.is_empty() {
                                 current_section.properties.insert(current_property_name, current_property);
@@ -121,11 +153,13 @@ pub mod dmidecoder {
                             current_section_name = String::new();
                         }
                         current_section.handle_line = clean_str(line);
+                        // if we have the handle line already we will read the follopwing line as the title
                     } else if !current_section.handle_line.is_empty() && !line.is_empty() {
                         current_section_name = clean_str(line);
                     }
                 },
                 State::Kv => {
+                    // will check if we have current properety data to push before creating another one from the current line
                     if !current_property.is_empty() && !current_property_name.is_empty() {
                         current_section.properties.insert(current_property_name, current_property);
                         current_property = Property::new();
@@ -141,6 +175,7 @@ pub mod dmidecoder {
                 }
             }
         }
+        // finalize by pushing the last property and the current section if there is data00 
         if !current_property.is_empty() && !current_property_name.is_empty() {
             current_section.properties.insert(current_property_name, current_property);
         }