/usr/share/doc/gnat-gps/html/Extract-Subprogram.html is in gnat-gps-doc 5.0-16.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 2002-2010 AdaCore.
This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, see http://www.gnu.org/licenses/.
A copy of the license is included in the section entitled
"GNU General Public License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNAT Programming Studio: Extract Subprogram</title>
<meta name="description" content="Using the GNAT Programming Studio: Extract Subprogram">
<meta name="keywords" content="Using the GNAT Programming Studio: Extract Subprogram">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-table.html#Index-table" rel="index" title="Index table">
<link href="Refactoring.html#Refactoring" rel="up" title="Refactoring">
<link href="Using-an-External-Editor.html#Using-an-External-Editor" rel="next" title="Using an External Editor">
<link href="Name-Parameters.html#Name-Parameters" rel="previous" title="Name Parameters">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
pre.smallexample {background-color:rgb(240,240,240);
font-family: courier new,courier,fixed;
font-size: 14px;
margin: 0px 40px 0px 40px;
border-width: 1px 2px 2px 1px;
border-top-style: dotted;
border-left-style: dotted;
border-right-style: solid;
border-bottom-style: solid;
border-color: black;}
code {color:black;
font-family: courier new,courier,fixed;
font-size: 14px;}
body {font-family: arial,helvetica,sans-serif;
font-size: 16px;
max-width: 800px;
text-align: justify}
samp {font-family: courier new,courier,fixed;
font-size: 14px}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Extract-Subprogram"></a>
<div class="header">
<p>
Previous: <a href="Name-Parameters.html#Name-Parameters" accesskey="p" rel="previous">Name Parameters</a>, Up: <a href="Refactoring.html#Refactoring" accesskey="u" rel="up">Refactoring</a> [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Extract-Subprogram-1"></a>
<h4 class="subsection">5.9.3 Extract Subprogram</h4>
<p>This refactoring is used to move some code from one place to a separate
subprogram. The goal is to simplify the original subprogram, by moving part of
its code elsewhere.
</p>
<p>Here is an example from the "Refactoring" book. The refactoring will take
place in the body of the package <samp>pkg.adb</samp>, but the spec is needed so that
you can compile the source code (a preliminary step mandatory before you can
refactor the code).
</p>
<div class="smallexample">
<pre class="smallexample"><b>pragma</b> Ada_05;
<b>with</b> Ada.Containers.Indefinite_Doubly_Linked_Lists;
<b>with</b> Ada.Strings.Unbounded;
<b>package</b> Pkg <b>is</b>
<b>type</b> Order <b>is tagged null record</b>;
<b>function</b> Get_Amount (Self : Order) <b>return</b> Integer;
<b>package</b> Order_Lists<b>is new</b>
Ada.Containers.Indefinite_Doubly_Linked_Lists (Order);
<b>type</b> Invoice <b>is tagged record</b>
Orders : Order_Lists.List;
Name : Ada.Strings.Unbounded.Unbounded_String;
<b>end record</b>;
procedure Print_Owing (Self : Invoice);
<b>end</b> Pkg;
</pre></div>
<p>The initial implementation for this code is given by the following code:
</p>
<div class="smallexample">
<pre class="smallexample"><b>pragma</b> Ada_05;
<b>with</b> Ada.Strings.Unbounded; <b>use</b> Ada.Strings.Unbounded;
<b>with</b> Ada.Text_IO; <b>use</b> Ada.Text_IO;
<b>package</b> body Pkg <b>is</b>
<b>use</b> Order_Lists;
<i>—————-</i>
<i>– Get_Amount –</i>
<i>—————-</i>
<b>function</b> Get_Amount (Self : Order) <b>return</b> Integer <b>is</b>
<b>begin</b>
<b>return</b> 0;
<b>end</b> Get_Amount;
<i>—————–</i>
<i>– Print_Owing –</i>
<i>—————–</i>
<b>procedure</b> Print_Owing (Self : Invoice) <b>is</b>
E : Order_Lists.Cursor := First (Self.Orders);
Outstanding : Natural := 0;
Each : Order;
<b>begin</b>
<i>– <<< line 30</i>
<i>– Print Banner</i>
Put_Line ("********************************");
Put_Line ("***** Customer Owes ****");
Put_Line ("********************************"); <i>– << line 35</i>
<i>– Calculate Outstanding</i>
<b>while</b> Has_Element (E) <b>loop</b>
Each := Element (E);
Outstanding := Outstanding + Each.Get_Amount;
Next (E);
<b>end loop</b>;
<i>– Print Details</i>
Put_Line ("Name: " & To_String (Self.Name));
Put_Line ("Outstanding:" & Outstanding'Img);
<b>end</b> Print_Owing;
<b>end Pkg</b>;
</pre></div>
<p>The procedure <code>Print_Owing</code> is too long and does several independent
actions. We will perform a series of three successive refactoring steps to
extract the code and move it elsewhere.
</p>
<p>The first is the code that prints the banner. Moving it is easy, since this
code does not depend on any context. We could just do a copy-paste, but then
we would have to create the new subprogram. Instead, we select lines 30 to
35, and then select the contextual menu <code>Refactoring/Extract Subprogram</code>.
GPS will then automatically change <code>Print_Owing</code> and create a new
procedure <code>Print_Banner</code> (the name is specified by the user, GPS does
not try to guess it). Also, since the chunk of code that is extracted starts
with a comment, GPS automatically uses that comment as the documentation for
the new subprogram. Here is part of the resulting file:
</p>
<div class="smallexample">
<pre class="smallexample"><b>package body</b> Pkg <b>is</b>
<b>procedure</b> Print_Banner;
<i>– Print Banner</i>
<i>——————</i>
<i>– Print_Banner –</i>
<i>——————</i>
<b>procedure</b> Print_Banner <b>is</b>
<b>begin</b>
Put_Line ("********************************");
Put_Line ("***** Customer Owes ****");
Put_Line ("********************************");
<b>end</b> Print_Banner;
... (code not shown)
<b>procedure</b> Print_Owing (Self : Invoice) <b>is</b>
E : Order_Lists.Cursor := First (Self.Orders);
Outstanding : Natural := 0;
Each : Order;
<b>begin</b>
Print_Banner;
<i>– Calculate Outstanding</i>
<b>while</b> Has_Element (E) <b>loop</b>
Each := Element (E);
Outstanding := Outstanding + Each.Get_Amount;
Next (E);
<b>end loop</b>;
<i>– Print Details <<< line 54</i>
Put_Line ("Name: " & To_String (Self.Name));
Put_Line ("Outstanding:" & Outstanding'Img); <i>– line 57</i>
<b>end</b> Print_Owing;
<b>end</b> Pkg;
</pre></div>
<p>A more interesting example is when we want to extract the code to print
the details of the invoice. This code depends on one local variable and
the parameter to Print_Owing. When we select lines 54 to 57 and extract
it into a new <code>Print_Details</code> subprogram, we get the following
result. GPS automatically decides which variables to extract, and whether
they should become parameters of the new subprogram, or local variables. In
the former case, it will also automatically decide whether to create
<code>"in"</code>, <code>"out"</code> or <code>"in out"</code> parameters. If there is
a single <code>"out"</code> parameter, it will automatically create a function
rather than a procedure.
</p>
<p>GPS will use, for the parameters, the same name that was used for the local
variable. Very often, it will make sense to recompile the new version of the
source, and then apply the <code>Rename Entity</code> refactoring to have more
specific names for the parameters, or the <code>Name Parameters</code> refactoring
so that the call to the new method uses named parameters to further clarify
the code.
</p>
<div class="smallexample">
<pre class="smallexample"> ... code not shown
<b>procedure</b> Print_Details
(Self : Invoice'<b>Class</b>;
Outstanding : Natural);
<i>– Print Details</i>
<i>——————-</i>
<i>– Print_Details –</i>
<i>——————-</i>
<b>procedure</b> Print_Details
(Self : Invoice'<b>Class</b>;
Outstanding : Natural)
<b>is</b>
<b>begin</b>
Put_Line ("Name: " & To_String (Self.Name));
Put_Line ("Outstanding:" & Outstanding'Img);
<b>end</b> Print_Details;
<b>procedure</b> Print_Owing (Self : Invoice) <b>is</b>
E : Order_Lists.Cursor := First (Self.Orders);
Outstanding : Natural := 0;
Each : Order;
<b>begin</b>
Print_Banner;
<i>– Calculate Outstanding</i>
<b>while</b> Has_Element (E) <b>loop</b>
Each := Element (E);
Outstanding := Outstanding + Each.Get_Amount;
Next (E);
<b>end loop</b>;
Print_Details (Self, Outstanding);
<b>end</b> Print_Owing;
</pre></div>
<p>Finally, we want to extract the code that computes the outstanding
amount. When this code is moved, the variables <code>E</code> and <code>Each</code>
become useless in <code>Print_Owing</code> and are moved into the new
subprogram (which we will call <code>Get_Outstanding</code>. Here is the result
of that last refactoring (the initial selection should include the blank
lines before and after the code, to keep the resulting <code>Print_Owing</code>
simpler). GPS will automatically ignore those blank lines.
</p>
<div class="smallexample">
<pre class="smallexample"> ... code not shown
<b>procedure</b> Get_Outstanding (Outstanding : <b>in out</b> Natural);
<i>– Calculate Outstanding</i>
<i>———————</i>
<i>– Get_Outstanding –</i>
<i>———————</i>
<b>procedure</b> Get_Outstanding (Outstanding : <b>in out</b> Natural) <b>is</b>
E : Order_Lists.Cursor := First (Self.Orders);
Each : Order;
<b>begin</b>
<b>while</b> Has_Element (E) <b>loop</b>
Each := Element (E);
Outstanding := Outstanding + Each.Get_Amount;
Next (E);
<b>end loop</b>;
<b>end</b> Get_Outstanding;
<b>procedure</b> Print_Owing (Self : Invoice) <b>is</b>
Outstanding : Natural := 0;
<b>begin</b>
Print_Banner;
Get_Outstanding (Outstanding);
Print_Details (Self, Outstanding);
<b>end</b> Print_Owing;
</pre></div>
<p>Note that the final version of <code>Print_Owing</code> is not perfect. For
instance, passing the initial value 0 to <code>Get_Outstanding</code> is
useless, and in fact that should probably be a function with no
parameter. But GPS already saves a lot of time and manipulation.
</p>
<p>Finally, a word of caution: this refactoring does not check that you are
giving a valid input. For instance, if the text you select includes a
<code>declare</code> block, you should always include the full block, not just
a part of it (or select text between <code>begin</code> and <code>end</code>). Likewise,
GPS does not expect you to select any part of the variable declarations,
just the code.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Name-Parameters.html#Name-Parameters" accesskey="p" rel="previous">Name Parameters</a>, Up: <a href="Refactoring.html#Refactoring" accesskey="u" rel="up">Refactoring</a> [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|