/usr/share/doc/gnat-gps/html/Extract-Subprogram.html

<html lang="en">
<head>
<title>Extract Subprogram - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Refactoring.html#Refactoring" title="Refactoring">
<link rel="prev" href="Name-Parameters.html#Name-Parameters" title="Name Parameters">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
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 3 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/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
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>
<div class="node">
<a name="Extract-Subprogram"></a>
<p>
Previous:&nbsp;<a rel="previous" accesskey="p" href="Name-Parameters.html#Name-Parameters">Name Parameters</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Refactoring.html#Refactoring">Refactoring</a>
<hr>
</div>

<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>Here is an example from the "Refactoring" book. The refactoring will take
place in the body of the package <samp><span class="file">pkg.adb</span></samp>, but the spec is needed so that
you can compile the source code (a preliminary step mandatory before you can
refactor the code).

<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>
   <p>The initial implementation for this code is given by the following code:

<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>--  &lt;&lt;&lt; line 30</i>
           <i>--  Print Banner</i>
     
           Put_Line ("********************************");
           Put_Line ("***** Customer Owes         ****");
           Put_Line ("********************************");  <i>--  &lt;&lt; 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: " &amp; To_String (Self.Name));
           Put_Line ("Outstanding:" &amp; Outstanding'Img);
        <b>end</b> Print_Owing;
     <b>end Pkg</b>;
</pre>
   <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>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:

<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   &lt;&lt;&lt; line  54</i>
     
           Put_Line ("Name: " &amp; To_String (Self.Name));
           Put_Line ("Outstanding:" &amp; Outstanding'Img);  <i>--  line 57</i>
        <b>end</b> Print_Owing;
     
     <b>end</b> Pkg;
</pre>
   <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>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.

<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: " &amp; To_String (Self.Name));
           Put_Line ("Outstanding:" &amp; 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>
   <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.

<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>
   <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>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.

<!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / Extract-Subprogram.html
