ic_agent 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c87eb2ad8a0305a051b52137d44398b743540432609f7468eb61318b183caf4
-  data.tar.gz: c51a300fd8596bce7e064f3f47cd4d025bff47af4dfe84113f55bf70a8d4c5bb
+  metadata.gz: b1bb3c395959ef0b33094ab3e34a6087b061a76287ce34b312286703c568fade
+  data.tar.gz: f71667c7d06d470c89afd7d9e8734bfded8abc2f7d85a89a77d84fa3ce7e210c
 SHA512:
-  metadata.gz: 432a2d181f6bd503f87c0cca4b60086aa059032c88da35382b78b2f587116fea18c7c9692e533cdffa39889dc44325e603320c245ecb5c8038ecd971068b12a0
-  data.tar.gz: 7ce801835791d320a52d9f0f35e494d8c2e7c5482cc9cddf71742bda0b69ed0fa6d10d05afbc95c90eb30f690f914851baf3487ad94bc8c6ac81d680b1156502
+  metadata.gz: 437bab4be804cc57aa1098aa91275d88623e79c98f9190129956eb2ceb0447dd5dbd305ec7425b3a3fd7fc945035a79329b6a73052c876bc31118a94387cb61a
+  data.tar.gz: 05adc3829656980d0a833ac495cbfbf67e84fee5474dda75e39d6f94fb538ee22120de034ba7b81c36680ef4444a586409ecb2c6f0f43d53f9cd7aa28b51e394

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ic_agent (0.2.0)
+    ic_agent (0.2.1)
       base32 (~> 0.3.4)
       bitcoin-ruby (~> 0.0.20)
       bls12-381 (~> 0.3.0)

data/README.md

@@ -4,6 +4,8 @@
 
 `ic_agent` provides basic modules to interact with canisters on the DFINITY Internet Computer.
 
+[![Gem Version](https://badge.fury.io/rb/ic_agent.svg)](https://badge.fury.io/rb/ic_agent)[![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
+
 
 ## Installation
 

data/lib/ic_agent/agent.rb

@@ -248,6 +248,9 @@ module IcAgent
       end
     end
 
+    # Verify a BLS signature
+    # The signature must be exactly 48 bytes (compressed G1 element)
+    # The key must be exactly 96 bytes (compressed G2 element)
     def verify(cert, canister_id)
       signature_hex = IcAgent::Certificate.signature(cert).str2hex
       tree = IcAgent::Certificate.tree(cert)
@@ -262,6 +265,7 @@ module IcAgent
       BLS.verify(signature, msg, public_key)
     end
 
+    # Check the delegation and return the corresponding root key.
     def check_delegation(delegation, effective_canister_id, disable_range_check)
       return @root_key unless delegation
 
@@ -303,6 +307,7 @@ module IcAgent
       false
     end
 
+    # Extract the BLS public key from the DER buffer.
     def extract_der(der_buf)
       bls_der_prefix = OpenSSL::BN.from_hex(IcAgent::BLS_DER_PREFIX).to_s(2)
       expected_length = bls_der_prefix.bytesize + IcAgent::BLS_KEY_LENGTH

data/lib/ic_agent/ast/assembler.rb

@@ -5,24 +5,30 @@ module IcAgent
     class Assembler
       TYPE_MAPPING = {}
 
+      # Builds a single Candid type from a given child type.
       def self.build_single_type(child_type)
         IcAgent::Candid::BaseTypes.send(child_type)
       end
 
+
+      # Builds a Candid blob type.
       def self.build_blob
         IcAgent::Candid::BaseTypes.vec(IcAgent::Candid::BaseTypes.nat8)
       end
 
+      # Builds a Candid optional type from a given child type.
       def self.build_opt(child_type, key_types = {})
         child_type = key_types[child_type].nil? ? build_type(child_type, key_types) : key_types[child_type]
         IcAgent::Candid::BaseTypes.opt(child_type)
       end
 
+      # Builds a Candid vector type from a given child type.
       def self.build_vec(child_type, key_types = {})
         child_type = key_types[child_type].nil? ? build_type(child_type, key_types) : key_types[child_type]
         IcAgent::Candid::BaseTypes.vec(child_type)
       end
 
+      # Builds a Candid record type from a given hash of field names and types.
       def self.build_record(child_hash, multi_types = {}, key_types = {})
         child_types = {}
         child_hash.each_key do |key|
@@ -38,6 +44,7 @@ module IcAgent
         IcAgent::Candid::BaseTypes.record(child_types)
       end
 
+      # Builds a Candid variant type from a given hash of field names and types.
       def self.build_variant(child_hash, multi_types = {}, key_types = {})
         child_types = {}
         child_hash.each_key do |key|
@@ -53,6 +60,7 @@ module IcAgent
         IcAgent::Candid::BaseTypes.variant(child_types)
       end
 
+      # Builds a Candid type based on the given type string.
       def self.build_type(type_str, key_types = {}, multi_types = {})
         opt_code = get_opt_code(type_str)
 
@@ -91,6 +99,7 @@ module IcAgent
         end
       end
 
+      # Replaces the last occurrence of a pattern in a string with the given replacement.
       def self.replace_last_occurrence(string, pattern, replacement)
         last_index = string.rindex(pattern)
         return string unless last_index
@@ -99,18 +108,21 @@ module IcAgent
         string
       end
 
+      # Extracts the content of a Candid record type from the type string.
       def self.get_record_content(record_str)
         record_str = record_str.sub('record', '').sub('{', '')
         record_str = replace_last_occurrence(record_str, '}', '')
         record_str.strip
       end
 
+      # Extracts the content of a Candid variant type from the type string.
       def self.get_variant_content(variant_str)
         variant_str = variant_str.sub('variant', '').sub('{', '')
         variant_str = replace_last_occurrence(variant_str, '}', '')
         variant_str.strip
       end
 
+      # Extracts the key-value pairs from a Candid record item string.
       def self.get_record_key_value(item_str, index_str, key_index = 0)
         first_index = item_str.index(index_str)
         if first_index
@@ -123,16 +135,19 @@ module IcAgent
         return key, value
       end
 
+      # Extracts the Candid code (e.g., "record", "variant", "opt", etc.) from the type string.
       def self.get_opt_code(item_str)
         opt_code = item_str.strip
         opt_code.split(' ')[0]
       end
 
+      # Extracts the child Candid code from the type string.
       def self.get_child_code(item_str, index_str)
         first_index = item_str.index(index_str)
         item_str[(first_index + index_str.size)..].strip
       end
 
+      # Replaces occurrences of Candid record and variant types with unique type names.
       def self.replace_multi_type(type_str)
         replaced_hash = {}
         modified_str = type_str.gsub(/record\s*{[^{}]*}/) do |match|
@@ -152,6 +167,7 @@ module IcAgent
         return modified_str, replaced_hash
       end
 
+      # Gets the refer types used in the type string.
       def self.get_params_refer_values(type_str)
         parser = IcAgent::Ast::StatementParser.new
         parser.parse(type_str)
@@ -159,6 +175,7 @@ module IcAgent
         refer_type
       end
 
+      # Recovers the original type string from the multi_types hash.
       def self.recover_type(type_str, multi_types)
         multi_types.each_key do |key|
           type_str = type_str.gsub(key, multi_types[key])

data/lib/ic_agent/ast/nodes/named_nodes.rb

@@ -3,15 +3,19 @@ require 'treetop'
 module IcAgent
   module Ast
     module Nodes
+      # Represents a named node in the abstract syntax tree.
       class NamedNode < Treetop::Runtime::SyntaxNode
+        # The title of the named node.
         def title
           :named_node
         end
 
+        # Converts the node and its children to an array representation.
         def to_array
           [title] + elements.map(&:to_array)
         end
 
+        # Converts the node and its children to a string representation.
         def to_s
           "#{title.to_s.upcase} #{elements_to_s}"
         end
@@ -25,53 +29,68 @@ module IcAgent
         end
       end
 
+      # Represents an instruction node in the abstract syntax tree, a subclass of NamedNode.
       class Instruction < NamedNode
+        # The title of the instruction node.
         def title
           :instruction
         end
 
+        # Converts the instruction node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a comment node in the abstract syntax tree, a subclass of NamedNode.
       class Comment < NamedNode
+        # The title of the comment node.
         def title
           :comment
         end
 
+        # Converts the comment node to a string representation with '#' prefix.
         def to_s
           "# #{elements[0].to_s}"
         end
       end
 
+      # Represents a DID file node in the abstract syntax tree, a subclass of NamedNode.
       class DIDFile < NamedNode
+        # The title of the DID file node.
         def title
           :did_file
         end
 
+        # Converts the DID file node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a type declaration node in the abstract syntax tree, a subclass of NamedNode.
       class TypeDeclaration < NamedNode
+        # The title of the type declaration node.
         def title
           :type_declaration
         end
 
+        # Returns the name of the type parameter.
         def type_param_name
           elements[0].source_content
         end
 
+        # Returns the content of the type parameter without newlines and trailing ';}' replaced with '}'.
         def type_param_content
           elements[1].source_content.gsub("\n", '').gsub(';}', '}')
         end
 
+        # Returns the opt code of the root type element.
         def type_root_opt_code
           elements[1].opt_code
         end
 
+        # Returns an array of type child items.
         def type_child_items
           if elements && elements[1] && elements[1].elements && elements[1].elements[0]
             elements[1].elements[0].elements
@@ -80,6 +99,7 @@ module IcAgent
           end
         end
 
+        # Returns an array of keys of type child items.
         def type_child_item_keys
           names = []
           type_child_items.each do |ele|
@@ -88,6 +108,7 @@ module IcAgent
           names
         end
 
+        # Returns an array of referenced types in the type parameter content.
         def type_refer_items
           source_string = self.type_param_content
           parser = IcAgent::Ast::StatementParser.new
@@ -96,10 +117,12 @@ module IcAgent
           refer_type
         end
 
+        # Converts the type declaration node to a string representation.
         def to_s
           text_value
         end
 
+        # Converts the type declaration node to a hash representation.
         def to_obj
           {
             'type_param_name' => type_param_name,
@@ -110,199 +133,257 @@ module IcAgent
         end
       end
 
+      # Represents a base type node in the abstract syntax tree, a subclass of NamedNode.
       class BaseType < NamedNode
+        # The title of the base type node.
         def title
           :base_type
         end
 
+        # Converts the base type node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a single base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeSingle < NamedNode
+        # The title of the single base type node.
         def title
           :base_type_single
         end
 
+        # Converts the single base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the single base type.
         def opt_code
           'single'
         end
       end
 
+      # Represents a record base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeRecord < NamedNode
+        # The title of the record base type node.
         def title
           :base_type_record
         end
 
+        # Converts the record base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the record base type.
         def opt_code
           'record'
         end
       end
 
+      # Represents a key base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeKey < NamedNode
+        # The title of the key base type node.
         def title
           :base_type_key
         end
 
+        # Converts the key base type node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a variant base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeVariant < NamedNode
+        # The title of the variant base type node.
         def title
           :base_type_variant
         end
 
+        # Converts the variant base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the variant base type.
         def opt_code
           'variant'
         end
       end
 
+      # Represents a function base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeFunc < NamedNode
+        # The title of the function base type node.
         def title
           :base_type_func
         end
 
+        # Converts the function base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the function base type.
         def opt_code
           'func'
         end
       end
 
+      # Represents an optional base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeOpt < NamedNode
+        # The title of the optional base type node.
         def title
           :base_type_opt
         end
 
+        # Converts the optional base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the optional base type.
         def opt_code
           'opt'
         end
       end
 
+      # Represents a vector base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeVec < NamedNode
+        # The title of the vector base type node.
         def title
           :base_type_vec
         end
 
+        # Converts the vector base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the vector base type.
         def opt_code
           'vec'
         end
       end
 
+      # Represents an other base type node in the abstract syntax tree, a subclass of BaseType.
       class BaseTypeOther < NamedNode
+        # The title of the other base type node.
         def title
           :base_type_other
         end
 
+        # Converts the other base type node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the other base type.
         def opt_code
           text_value
         end
       end
 
+      # Represents the content of a base type node in the abstract syntax tree, a subclass of NamedNode.
       class BaseTypeContent < NamedNode
+        # The title of the base type content node.
         def title
           :base_type_content
         end
 
+        # Converts the base type content node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a child of a base type node in the abstract syntax tree, a subclass of NamedNode.
       class BaseTypeChild < NamedNode
+        # The title of the base type child node.
         def title
           :base_type_child
         end
 
+        # Converts the base type child node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a type name node in the abstract syntax tree, a subclass of NamedNode.
       class TypeName < NamedNode
+        # The title of the type name node.
         def title
           :type_name
         end
 
+        # Converts the type name node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC service node in the abstract syntax tree, a subclass of NamedNode.
       class Service < NamedNode
+        # The title of the IC service node.
         def title
           :ic_service
         end
 
+        # Converts the IC service node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC service name node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceName < NamedNode
+        # The title of the IC service name node.
         def title
           :ic_service_name
         end
 
+        # Converts the IC service name node to a string representation with '#' prefix.
         def to_s
           "# #{elements[0].to_s}"
         end
       end
 
+      # Represents IC service methods node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceMethods < NamedNode
+        # The title of the IC service methods node.
         def title
           :ic_service_methods
         end
 
+        # Returns an array of IC service method nodes.
         def value
           elements.map { |update| update.value }
         end
       end
 
+      # Represents an IC service method name node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceMethodName < NamedNode
+        # The title of the IC service method name node.
         def title
           :ic_service_method_name
         end
       end
 
+      # Represents an IC service item node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceItem < NamedNode
+        # The title of the IC service item node.
         def title
           :ic_service_item
         end
 
+        # Converts the IC service item node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Converts the IC service item node to a hash representation.
         def to_obj
           obj = {}
           elements.each do |element|
@@ -312,61 +393,79 @@ module IcAgent
         end
       end
 
+      # Represents an IC service param node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceParam < NamedNode
+        # The title of the IC service param node.
         def title
           :ic_service_param
         end
 
+        # Converts the IC service param node to a string representation with '#' prefix.
         def to_s
           "# #{elements[0].to_s}"
         end
       end
 
+      # Represents an IC service name node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceName < NamedNode
+        # The title of the IC service name node.
         def title
           :ic_service_name
         end
 
+        # Converts the IC service name node to a string representation with '#' prefix.
         def to_s
           "# #{elements[0].to_s}"
         end
       end
 
+      # Represents an IC service method params node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceMethodParams < NamedNode
+        # The title of the IC service method params node.
         def title
           :ic_service_method_params
         end
 
+        # Converts the IC service method params node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC service method return node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceMethodReturn < NamedNode
+        # The title of the IC service method return node.
         def title
           :ic_service_method_return
         end
 
+        # Converts the IC service method return node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC service method query node in the abstract syntax tree, a subclass of NamedNode.
       class IcServiceMethodQuery < NamedNode
+        # The title of the IC service method query node.
         def title
           :ic_service_method_query
         end
 
+        # Converts the IC service method query node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents the content of a base type node in the abstract syntax tree, a subclass of NamedNode.
       class BaseTypeContent < NamedNode
+        # The title of the IC service method query node.
         def title
           :ic_service_method_query
         end
 
+        # Converts the IC service method query node to a string representation.
         def to_s
           elements_to_s
         end
@@ -374,4 +473,3 @@ module IcAgent
     end
   end
 end
-

data/lib/ic_agent/ast/nodes/statement_nodes.rb

@@ -3,217 +3,280 @@ require 'treetop'
 module IcAgent
   module Ast
     module Nodes
+      # Represents a statement node in the abstract syntax tree with additional attributes.
       class StatementNode < Treetop::Runtime::SyntaxNode
+        # Additional attributes to store child count and depth.
         attr_accessor :child_count, :depth
 
+        # The title of the statement node, by default :named_node.
         def title
           :named_node
         end
 
+        # Converts the statement node and its children to an array representation.
         def to_array
           [title] + elements.map(&:to_array)
         end
 
+        # Converts the statement node and its children to a string representation.
         def to_s
           "#{title.to_s.upcase} #{elements_to_s}"
         end
 
+        # Converts the children of the statement node to a string.
         def elements_to_s
           elements.map(&:to_s).join("\n")
         end
 
+        # Adds a child to the statement node.
         def add_child
           @child_count ||= 0 + 1
         end
 
+        # Returns the source content of the statement node by removing leading and trailing whitespaces.
         def source_content
           self.text_value.strip
         end
       end
 
+      # Represents an IC base type node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseType < StatementNode
+        # The title of the IC base type node.
         def title
           :base_type
         end
 
+        # Converts the IC base type node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC base type single node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeSingle < StatementNode
+        # The title of the IC base type single node.
         def title
           :base_type_single
         end
 
+        # Converts the IC base type single node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type single node, which is 'single'.
         def opt_code
           'single'
         end
       end
 
+      # Represents an IC base type record node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeRecord < StatementNode
+        # The title of the IC base type record node.
         def title
           :base_type_record
         end
 
+        # Converts the IC base type record node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type record node, which is 'record'.
         def opt_code
           'record'
         end
       end
 
+      # Represents an IC base type key node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeKey < StatementNode
+        # The title of the IC base type key node.
         def title
           :base_type_key
         end
 
+        # Converts the IC base type key node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC base type value node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeValue < StatementNode
+        # The title of the IC base type value node.
         def title
           :base_type_value
         end
 
+        # Converts the IC base type value node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC type definition node in the abstract syntax tree, a subclass of StatementNode.
       class IcTypeDef < StatementNode
+        # The title of the IC type definition node.
         def title
           :base_type_def
         end
 
+        # Converts the IC type definition node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC base type variant node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeVariant < StatementNode
+        # The title of the IC base type variant node.
         def title
           :base_type_variant
         end
 
+        # Converts the IC base type variant node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type variant node, which is 'variant'.
         def opt_code
           'variant'
         end
       end
 
+      # Represents an IC base type function node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeFunc < StatementNode
+        # The title of the IC base type function node.
         def title
           :base_type_func
         end
 
+        # Converts the IC base type function node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type function node, which is 'func'.
         def opt_code
           'func'
         end
       end
 
+      # Represents an IC base type optional node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeOpt < StatementNode
+        # The title of the IC base type optional node.
         def title
           :base_type_opt
         end
 
+        # Converts the IC base type optional node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type optional node, which is 'opt'.
         def opt_code
           'opt'
         end
       end
 
+      # Represents an IC base type vector node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeVec < StatementNode
+        # The title of the IC base type vector node.
         def title
           :base_type_vec
         end
 
+        # Converts the IC base type vector node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type vector node, which is 'vec'.
         def opt_code
           'vec'
         end
       end
 
+      # Represents an IC base type other node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeOther < StatementNode
+        # The title of the IC base type other node.
         def title
           :base_type_other
         end
 
+        # Converts the IC base type other node to a string representation.
         def to_s
           elements_to_s
         end
 
+        # Returns the opt code for the IC base type other node.
         def opt_code
           text_value
         end
       end
 
+      # Represents the content of an IC base type node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeContent < StatementNode
+        # The title of the IC base type content node.
         def title
           :base_type_content
         end
 
+        # Converts the IC base type content node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a child of an IC base type node in the abstract syntax tree, a subclass of StatementNode.
       class IcBaseTypeChild < StatementNode
+        # The title of the IC base type child node.
         def title
           :base_type_child
         end
 
+        # Converts the IC base type child node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents an IC type name node in the abstract syntax tree, a subclass of StatementNode.
       class IcTypeName < StatementNode
+        # The title of the IC type name node.
         def title
           :type_name
         end
 
+        # Converts the IC type name node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents a statement block node in the abstract syntax tree, a subclass of StatementNode.
       class StatementBlock < StatementNode
+        # The title of the statement block node.
         def title
           :statement_block
         end
 
+        # Converts the statement block node to a string representation.
         def to_s
           elements_to_s
         end
       end
 
+      # Represents the content of a statement node in the abstract syntax tree, a subclass of StatementNode.
       class StatementContent < StatementNode
+        # The title of the statement content node.
         def title
           :statement_content
         end
 
+        # Converts the statement content node to a string representation.
         def to_s
           elements_to_s
         end
@@ -221,4 +284,3 @@ module IcAgent
     end
   end
 end
-

data/lib/ic_agent/ast/nodes/string_literal.rb

@@ -3,11 +3,16 @@ require 'treetop'
 module IcAgent
   module Ast
     module Nodes
+      # Represents a string literal node in the abstract syntax tree.
       class StringLiteral < Treetop::Runtime::SyntaxNode
+        # Converts the string literal node to an array representation.
+        # In this case, the array contains the text value of the string literal.
         def to_array
           self.text_value
         end
 
+        # Converts the string literal node to a string representation.
+        # In this case, it returns the text value of the string literal.
         def to_s
           self.text_value
         end

data/lib/ic_agent/ast/parser.rb

@@ -2,26 +2,41 @@ require 'treetop'
 
 module IcAgent
   module Ast
+    # The Parser class provides methods to parse data using a Treetop grammar and work with the resulting Abstract Syntax Tree (AST).
     class Parser
       attr_accessor :parser, :tree
 
+      # Initializes the Parser by loading the Treetop grammar file.
       def initialize
         Treetop.load(File.expand_path(File.join(File.dirname(__FILE__), 'did_grammar.treetop')))
         @parser = DIDGrammarParser.new
       end
 
+      # Parses the given data using the Treetop parser and returns the AST.
+      #
+      # Parameters:
+      # - data: The data to be parsed.
+      # - return_type: The desired return type for the parse result (:string by default).
+      #
+      # Returns:
+      # - The root node of the Abstract Syntax Tree (AST).
+      #
+      # Raises:
+      # - Exception if there is a parse error.
       def parse(data, return_type = :string)
         tree = @parser.parse(data)
 
         raise Exception, "Parse error at offset: #{@parser.index} #{@parser.failure_reason}" if tree.nil?
 
-        # this edits the tree in place
+        # This method edits the tree in place to remove unnecessary syntax nodes.
         clean_tree(tree)
 
         @tree = tree
         tree
       end
 
+      # Recursively cleans the syntax tree by removing nodes of class 'Treetop::Runtime::SyntaxNode'.
+      # This method is used to remove unnecessary nodes generated during parsing.
       def clean_tree(root_node)
         return if root_node.elements.nil?
 
@@ -29,6 +44,10 @@ module IcAgent
         root_node.elements.each { |node| self.clean_tree(node) }
       end
 
+      # Retrieves the root node of the IC service from the AST.
+      #
+      # Returns:
+      # - The root node representing the IC service, or nil if not found.
       def ic_service
         tree.elements.each do |ele|
           return ele if ele.title == :ic_service
@@ -36,6 +55,7 @@ module IcAgent
         nil
       end
 
+      # Retrieves an array of AST nodes representing IC type declarations.
       def ic_types
         type_arr = []
         tree.elements.each do |ele|
@@ -44,6 +64,7 @@ module IcAgent
         type_arr
       end
 
+      # Converts the IC type declarations to an array of corresponding objects.
       def ic_types_obj
         obj_arr = []
         ic_types.each do |ic_type|
@@ -52,6 +73,10 @@ module IcAgent
         obj_arr
       end
 
+      # Retrieves the root node of the IC service methods from the AST.
+      #
+      # Returns:
+      # - The root node representing the IC service methods, or nil if not found.
       def ic_service_methods
         ic_service_tree = ic_service
         unless ic_service_tree.empty?
@@ -62,10 +87,12 @@ module IcAgent
         nil
       end
 
+      # Retrieves the name of an IC type from its AST node.
       def ic_type_name(ic_type)
         ic_type.type_param_name
       end
 
+      # Retrieves an array of names of all IC types from the AST.
       def ic_type_names
         names_arr = []
         ic_types.each do |ic_type|
@@ -74,6 +101,13 @@ module IcAgent
         names_arr
       end
 
+      # Retrieves the AST node of an IC type by its name.
+      #
+      # Parameters:
+      # - type_name: The name of the IC type to retrieve.
+      #
+      # Returns:
+      # - The AST node representing the IC type, or nil if not found.
       def ic_type_by_name(type_name)
         ic_types.each do |ic_type|
           return ic_type if type_name == ic_type_name(ic_type)

data/lib/ic_agent/ast/statement_parser.rb

@@ -2,6 +2,8 @@ require 'treetop'
 
 module IcAgent
   module Ast
+    # The StatementParser class provides methods to parse data and generate an Abstract Syntax Tree (AST)
+    # for nested types based on the specified grammar.
     class StatementParser
       attr_accessor :parser, :tree, :source_tree
 
@@ -21,10 +23,19 @@ module IcAgent
       REFER_TYPE_KEYS = ['record', 'variant']
 
       def initialize
+        # Loads the Treetop grammar from the specified file.
         Treetop.load(File.expand_path(File.join(File.dirname(__FILE__), 'nested_type_grammar.treetop')))
         @parser = TypeGrammarParser.new
       end
 
+      # Parses the input data and generates the Abstract Syntax Tree (AST) for nested types based on the grammar.
+      #
+      # Parameters:
+      # - data: The input data to be parsed.
+      # - return_type: The desired format for the parsed AST (:string by default).
+      #
+      # Returns:
+      # - The generated AST in the specified format.
       def parse(data, return_type = :string)
         tree = @parser.parse(data)
         raise Exception, "Parse error at offset: #{@parser.index} #{@parser.failure_reason}" if tree.nil?
@@ -38,6 +49,7 @@ module IcAgent
         tree
       end
 
+      # Cleans up the AST tree by removing unnecessary nodes.
       def clean_tree(root_node)
         return if root_node.elements.nil?
 
@@ -45,6 +57,7 @@ module IcAgent
         root_node.elements.each { |node| self.clean_tree(node) }
       end
 
+      # Generates the source tree from the AST tree.
       # @param [Object] root_node
       # @param [nil] tree_root_node
       # @param [nil] tree_current_node
@@ -87,10 +100,12 @@ module IcAgent
         self.source_tree = tree_root_node
       end
 
+      # Returns the root node of the AST statement.
       def ic_statement_root
         tree.elements[0]
       end
 
+      # Returns the child nodes of the AST statement.
       def ic_statement_childs
         if tree.elements[0] && tree.elements[0].elements[0].elements[0]
           tree.elements[0].elements[0].elements[0].elements

data/lib/ic_agent/ast/writer.rb

@@ -1,10 +1,25 @@
 module IcAgent
   module Ast
+    # The Writer class provides methods to represent an Abstract Syntax Tree (AST) in different formats.
     class Writer
+      # Initializes the Writer with an Abstract Syntax Tree (AST).
+      #
+      # Parameters:
+      # - tree: The Abstract Syntax Tree (AST) to be represented.
       def initialize(tree)
         @tree = tree
       end
 
+      # Writes the AST in the desired format.
+      #
+      # Parameters:
+      # - return_type: The desired format to represent the AST (:string by default).
+      #
+      # Returns:
+      # - The AST in the specified format:
+      #   - :tree: Returns the original AST.
+      #   - :array: Returns the AST as an array.
+      #   - :string: Returns the AST as a string.
       def write(return_type = :string)
         if return_type == :tree
           @tree

data/lib/ic_agent/canister.rb

@@ -2,6 +2,12 @@ require 'rubytree'
 
 module IcAgent
   class Canister
+    # Constructor for the Canister class.
+    #
+    # Parameters:
+    # - agent: An instance of the agent.
+    # - canister_id: ID of the canister.
+    # - candid: (Optional) The Candid description of the canister. If not provided, it will be queried.
     def initialize(agent, canister_id, candid=nil)
       @agent = agent
       @canister_id = canister_id
@@ -17,6 +23,7 @@ module IcAgent
         raise BaseException, "canister #{@canister_id} has no __get_candid_interface_tmp_hack method."
       end
 
+      # Parse the Candid description to extract information about service methods.
       parser = IcAgent::Ast::Parser.new
       parser.parse(@candid)
 

data/lib/ic_agent/common/cycles_wallet.rb

@@ -261,6 +261,11 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the CyclesWallet class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
+      # - wallet_id: The ID of the CyclesWallet.
       def initialize(iden = nil, wallet_id)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/common/governance.rb

@@ -355,6 +355,10 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the Governance class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
       def initialize(iden = nil)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/common/ledger.rb

@@ -166,6 +166,10 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the Ledger class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
       def initialize(iden = nil)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/common/management.rb

@@ -182,6 +182,10 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the Management class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
       def initialize(iden = nil)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IcAgent
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ic_agent
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Terry.Tu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-21 00:00:00.000000000 Z
+date: 2023-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32