ic_agent 0.1.4 → 0.2.1

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/candid.rb

@@ -174,6 +174,8 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Null
+    # check None == Null ?
     class NullClass < PrimitiveType
       def initialize()
         super
@@ -205,6 +207,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Empty, a type which has no inhabitants.
     class EmptyClass < PrimitiveType
       def initialize
         super
@@ -235,6 +238,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Bool
     class BoolClass < PrimitiveType
       def initialize
         super
@@ -275,6 +279,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Reserved
     class ReservedClass < PrimitiveType
       def initialize
         super
@@ -308,6 +313,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Text
     class TextClass < PrimitiveType
       def initialize
         super
@@ -343,6 +349,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Int
     class IntClass < PrimitiveType
       def initialize
         super
@@ -374,6 +381,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Nat
     class NatClass < PrimitiveType
       def initialize
         super
@@ -405,6 +413,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Float
     class FloatClass < PrimitiveType
       def initialize(bits)
         super()
@@ -460,6 +469,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL fixed-width Int(n)
     class FixedIntClass < PrimitiveType
       def initialize(bits)
         super()
@@ -535,6 +545,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL fixed-width Nat(n)
     class FixedNatClass < PrimitiveType
       def initialize(bits)
         super()
@@ -605,6 +616,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL principal reference
     class PrincipalClass < PrimitiveType
       def initialize
         super
@@ -658,6 +670,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Array
     class VecClass < ConstructType
       def initialize(_type)
         super()
@@ -704,6 +717,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Option
     class OptClass < ConstructType
       def initialize(_type)
         super()
@@ -756,6 +770,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Record
     class RecordClass < ConstructType
       def initialize(field)
         super()
@@ -845,6 +860,7 @@ module IcAgent
       end
     end
 
+    # Represents Tuple, a syntactic sugar for Record.
     class TupleClass < RecordClass
       attr_accessor :components
 
@@ -908,6 +924,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Variant
     class VariantClass < ConstructType
       attr_accessor :fields
 
@@ -996,6 +1013,7 @@ module IcAgent
       end
     end
 
+    # Represents a reference to an IDL type, used for defining recursive data types.
     class RecClass < ConstructType
       @@counter = 0
 
@@ -1073,6 +1091,7 @@ module IcAgent
       end
     end
 
+    #Represents an IDL Func reference
     class FuncClass < ConstructType
       attr_accessor :arg_types, :ret_types, :annotations
 
@@ -1170,6 +1189,7 @@ module IcAgent
       end
     end
 
+    # Represents an IDL Service reference
     class ServiceClass < ConstructType
       def initialize(field)
         super()
@@ -1344,6 +1364,7 @@ module IcAgent
       end
     end
 
+    # through Pipe to decode bytes
     def self.leb128u_decode(pipe)
       res = StringIO.new
       loop do
@@ -1575,8 +1596,8 @@ module IcAgent
       return table[t]
     end
 
-    # params = [{type, value}]
-    # data = b'DIDL' + len(params) + encoded types + encoded values
+    # @param [Object] params = [{type, value}]
+    # @return data = b'DIDL' + len(params) + encoded types + encoded values
     def self.encode(params)
       arg_types = []
       args = []
@@ -1617,7 +1638,8 @@ module IcAgent
       return pre + table + length + typs + vals
     end
 
-    # decode a bytes value
+    # @param [Object] data: decode a bytes value
+    # @param [nil] ret_types
     # def decode(retTypes, data):
     def self.decode(data, ret_types = nil)
       pipe = Pipe.new(data)
@@ -1664,8 +1686,7 @@ module IcAgent
                          'value' => t.decode_value(pipe, types[i])
                        })
       end
-
-      return outputs
+      outputs
     end
   end
 end

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)