File Coverage

blib/lib/CryptoTron/GetAccount.pm
Criterion Covered Total %
statement 20 26 76.9
branch n/a
condition n/a
subroutine 7 8 87.5
pod 0 1 0.0
total 27 35 77.1


line stmt bran cond sub pod time code
1              
2             # Load the Perl pragmas.
3             use 5.010001;
4 1     1   70754 use strict;
  1         4  
5 1     1   6 use warnings;
  1         2  
  1         18  
6 1     1   5  
  1         2  
  1         59  
7             # Load the Perl pragma Exporter.
8             use vars qw(@ISA @EXPORT @EXPORT_OK);
9 1     1   7 use Exporter 'import';
  1         1  
  1         77  
10 1     1   7  
  1         2  
  1         81  
11             # Base class of this module.
12             our @ISA = qw(Exporter);
13              
14             # Exporting the implemented subroutine.
15             our @EXPORT = qw(GetAccount);
16              
17             # Set the package version.
18             our $VERSION = '0.17';
19              
20             # Load the required Perl module.
21             use File::Basename;
22 1     1   7  
  1         3  
  1         141  
23             # Load the required package module.
24             use CryptoTron::JsonHttp;
25 1     1   453  
  1         3  
  1         247  
26             # Get the package name.
27             our ($MODULE_NAME, undef, undef) = fileparse(__FILE__, '\..*');
28              
29             # ---------------------------------------------------------------------------- #
30             # Subroutine GetAccount() #
31             # #
32             # Description: #
33             # Get the account information of a Tron account from the Tron blockchain using #
34             # the full-node HTTP Tron API. #
35             # #
36             # @argument {PublicKey => $PublicKey, #
37             # VisibleFlag => ["True"|"False"|""], #
38             # ControlFlag => ["True"|"False"|""], #
39             # OutputFormat => ["RAW"|"STR"|""]} (hash) #
40             # @return $output_data Response content (scalar) #
41             # ---------------------------------------------------------------------------- #
42             # Assign the subroutine arguments to the local array.
43             my ($param) = @_;
44             # Create the payload.
45 0     0 0   my $payload = payload_standard($param);
46             # Add the payload to the given hash.
47 0           $param->{'PayloadString'} = $payload;
48             # Add the module name to the given hash.
49 0           $param->{'ModuleName'} = $MODULE_NAME;
50             # Get the ouput data.
51 0           my $output_data = json_data($param);
52             # Return the ouput data.
53 0           return $output_data;
54             };
55 0            
56             1;
57              
58              
59             =head1 NAME
60              
61             CryptoTron::GetAccount - Perl extension for use with the blockchain of the crypto coin Tron.
62              
63             =head1 SYNOPSIS
64              
65             use CryptoTron::GetAccount;
66              
67             # Set the public key as Base58 address.
68             my $PublicKeyBase58 = "TY2fJ7AcsnQhfW3UJ1cjEUak5vkM87KC6R";
69              
70             # Set the visible flag.
71             my $VisibleFlag = ["True"|"False"|""];
72              
73             # Set the control flag.
74             my $ControlFlag = ["True"|"False"|""];
75              
76             # Set the output format.
77             my $OutputFormat = ["RAW"|"STR"|""];
78              
79             # Request the account info from the mainnet.
80             my $account_info = GetAccount({
81             PublicKey => $PublicKeyBase58
82             [, VisibleFlag => $VisibleFlag]
83             [, ControlFlag => $ControlFlag]
84             [, OutputFormat => $OutputFormat]
85             });
86              
87             # Print the account info into the terminal window.
88             print $account_info;
89              
90             =head1 DESCRIPTION
91              
92             The module requests the account information of an Tron account from the
93             Tron blockchain using the so-called full-node HTTP API from the Tron
94             developer network. The module is designed for use with Tron Mainnet. For
95             HTTP requests the methods C<POST> or C<GET> can be used in general. For
96             the method C<GetAccount> the needed method is C<POST>. The payload of the
97             HTTP request consists of the key 'address' and the key 'visible' and the
98             related values. The switch 'visible' can be set to "True" or "False". If
99             the switch is set to "True" a Base58 address is used. If the switch is set
100             to "False" a Hex address is used. A request of the service API results in
101             a response in JSON format. The module returns formatted string JSON data as
102             well as unformated raw JSON data based on the output format flag. The parsing
103             of the account information is done by a separate module.
104              
105             =head1 METHOD
106              
107             GetAccount()
108              
109             =head1 OPTIONS
110              
111             The named subroutine argument key C<PublicKey> and the related value are
112             mandatory, the named subroutine arguments keys C<OutputFormat> as well as
113             C<VisibleFlag> and there values are optional. The value of the subroutine
114             argument key C<PublicKey> can be a Base58 address or a Hex address. The
115             value of the subroutine argument key C<VisibleFlag> can be "True" or
116             "False".
117              
118             PublicKey: Base58 address => VisibleFlag: True
119             PublicKey: Hex address => VisibleFlag: False
120              
121             If the given combination is not valid, an error will be returned from the
122             request.
123              
124             The subroutine argument key C<ControlFlag> and his value controls if the given
125             combination address and visible should be checked. If visible is not set in a
126             correct way, the value will be corrected if the flag is "True" and if the flag
127             is "False" it will not be corrected.
128              
129             The subroutine argument key C<OutputFormat> and his value controls wether the
130             output is raw JSON or or formatted JSON.
131              
132             =head1 EXAMPLES
133              
134             =head2 Example 1
135              
136             # Load the required module.
137             use CryptoTron::GetAccount;
138              
139             # Set the public key as Base58 address.
140             my $PublicKeyBase58 = "TY2fJ7AcsnQhfW3UJ1cjEUak5vkM87KC6R";
141              
142             # Set the visible flag.
143             my $VisibleFlag = "True";
144              
145             # Set the control flag.
146             my $ControlFlag = "True";
147              
148             # Set the output format.
149             my $OutputFormat = "RAW";
150              
151             # Request the account info from the mainnet.
152             my $account_info = GetAccount({
153             PublicKey => $PublicKeyBase58,
154             VisibleFlag => $VisibleFlag,
155             ControlFlag => $ControlFlag,
156             OutputFormat => $OutputFormat
157             });
158              
159             # Print the account info into the terminal window.
160             print $account_info;
161              
162             =head2 Example 2
163              
164             # Load the required module.
165             use CryptoTron::GetAccount;
166              
167             # Set the public key as Base58 address.
168             my $PublicKeyBase58 = "TY2fJ7AcsnQhfW3UJ1cjEUak5vkM87KC6R";
169              
170             # Set the output format.
171             my $OutputFormat = "STR";
172              
173             # Request the account info from the mainnet.
174             my $response = GetAccount({PublicKey => $PublicKeyBase58});
175              
176             # Print the account info into the terminal window.
177             print $response;
178              
179             =head1 LIMITATIONS
180              
181             The module is working with the Tron Mainnet, but not with other existing
182             Tron Testnets.
183              
184             =head1 OPEN ISSUES
185              
186             None
187              
188             =head1 ERROR CODES
189              
190             None
191              
192             =head1 NOTES
193              
194             None
195              
196             =head1 BUGS
197              
198             None
199              
200             =head1 TODO
201              
202             None
203              
204             =head1 SEE ALSO
205              
206             CryptoTron::JsonHttp
207              
208             CryptoTron:ParseAccount
209              
210             CryptoTron:AddressCheck
211              
212             CryptoTron:AddressConvert
213              
214             File::Basename
215              
216             TRON Developer Hub
217              
218             =head1 AUTHOR
219              
220             Dr. Peter Netz, E<lt>ztenretep@cpan.orgE<gt>
221              
222             =head1 COPYRIGHT AND LICENSE
223              
224             Copyright (C) 2022 by Dr. Peter Netz
225              
226             This library is free software; you can redistribute it and/or modify it
227             under the same terms of The MIT License. For more details, see the full
228             text of the license in the attached file LICENSE in the main module folder.
229             This program is distributed in the hope that it will be useful, but without
230             any warranty; without even the implied warranty of merchantability or fitness
231             for a particular purpose.
232              
233             =cut