codesnip/Src/Help/HTML/snippet_routine.htm at develop · delphidabbler/codesnip · GitHub

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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--
 * This Source Code Form is subject to the terms of the Mozilla Public License,
 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
 * obtain one at https://mozilla.org/MPL/2.0/
 *
 * Copyright (C) 2009-2021, Peter Johnson (gravatar.com/delphidabbler).
 *
 * Help topic dscribing the routine snippet kind.
-->
<html>
  <head>
    <meta http-equiv="Content-Type" content="text-html; charset=Windows-1252">
    <title>
      Routine Snippets
    </title>
    <link rel="stylesheet" href="../css/codesnip.css" type="text/css">
  </head>
  <body>
    <object
      type="application/x-oleobject"
      classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e"
    >
      <param name="ALink Name" value="SnippetRoutine">
    </object>
    <h1>
      <a name="snippet_routine"></a>Routine Snippets
    </h1>
    <p>
      A routine snippet, defines exactly one Pascal procedure or function.
      Methods are not permitted (see the <a href="snippet_class.htm">class &amp
      advanced record</a> kind for how to deal with methods).
    </p>
    <p>
      Each routine snippet begins with either the <strong>function</strong> or
      <strong>procedure</strong> keyword followed by a valid Pascal routine
      prototype (see below). No source code or comments may precede the
      <strong>function</strong> or <strong>procedure</strong> keywords. The
      following directives may be included in the prototype:
    </p>
    <ul class="unspaced">
      <li>
        <strong>register</strong>
      </li>
      <li>
        <strong>pascal</strong>
      </li>
      <li>
        <strong>cdecl</strong>
      </li>
      <li>
        <strong>stdcall</strong>
      </li>
      <li>
        <strong>safecall</strong>
      </li>
      <li>
        <strong>overload</strong>
      </li>
    </ul>
    <p>
      After the routine prototype there must be at least one space or a new line
      before the routine's implementation. Private functions, procedures, type
      definitions, variables and constants are permitted.
    </p>
    <p>
      A routine must be
      fully implemented in Pascal &ndash; it can't be simply a DLL import.
      Therefore the <strong>external</strong> and <strong>varargs</strong>
      directives are not supported.
    </p>
    <p>
      Here's an example of a valid routine snippet:
    </p>
<pre class="source-code">function MyFunc(const Param1, Param2: string): string; stdcall;
begin
  Result := Param1 + ' - ' + Param2;
end;</pre>
    <p>
      Routine snippets may refer to other routines,
      <a href="snippet_type.htm">simple type</a> definitions,
      <a href="snippet_class.htm">class &amp; advanced record</a> definitions or
      <a href="snippet_constant.htm">constants</a>, providing they are defined
      in Delphi units or elsewhere in the database. The snippet's <em>units</em>
      and <em>dependency</em> references should indicate where to find
      referenced types, constants and routines. Routine snippets may not
      reference <a href="snippet_freeform.htm">freeform</a> or
      <a href="snippet_unit.htm">unit</a> snippets.
    </p>
    <p>
      It is important that the routine prototype is recognisable by
      <em>CodeSnip</em> because it must be able to extract the prototype for
      inclusion in a generated unit's interface section, amongst other things.
    </p>
    <h2>
      Overloading
    </h2>
    <p>
      You may use overloaded routines by creating a separate routine snippet for
      each overloaded version of the routine. The <strong>overload</strong>
      directive must be used for each snippet.
    </p>
    <p>
      While the name of the routines in source code must obviously be the same,
      each snippet must be given a unique name for use by the database. For
      example if there are two overloaded routines named <code>MyFunc</code> you
      could use <em>MyFunc_A</em> and <em>MyFunc_B</em> as the snippet's name in
      the database. The main DelphiDabbler Snippets Database has plenty of
      examples.
    </p>
  </body>
</html>