Template:Function2: Difference between revisions

From Kolmafia
Jump to navigation Jump to search
No edit summary
Add missing description for function1.param1.type
 
(27 intermediate revisions by the same user not shown)
Line 1: Line 1:
<includeonly>{{TOCright}}{{DISPLAYTITLE:{{{name}}}()}}{{#if: {{{needscode|}}}|{{CodeRequest}}}}{{#if: {{{improvecode|}}}|{{CodeRequest|better=yes}}}}
<includeonly>{{TOCright}}{{DISPLAYTITLE:{{{name}}}}}{{#if: {{{needscode|}}}|{{CodeRequest}}}}{{#if: {{{improvecode|}}}|{{CodeRequest|better=yes}}}}
{{#if: {{{name|}}}||{{error|Parameter 'name' is missing for User:Philmasterplus/TemplateSandbox2}}}}
{{#if: {{{name|}}}||{{error|Parameter 'name' is missing for User:Philmasterplus/TemplateSandbox2}}}}
==Function Syntax==
<h2>Function Syntax</h2>
{{#if: {{{function1.return_type|}}}
{{#if: {{{function1.return_type|}}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=1|desc=yes}}</p>}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=1|desc=yes|param_desc=yes}}</p>}}
{{#if: {{{function2.return_type|}}}
{{#if: {{{function2.return_type|}}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=2|desc=yes}}</p>}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=2|desc=yes|param_desc=yes}}</p>}}
{{#if: {{{function3.return_type|}}}
{{#if: {{{function3.return_type|}}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=3|desc=yes}}</p>}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=3|desc=yes|param_desc=yes}}</p>}}
{{#if: {{{function4.return_type|}}}
{{#if: {{{function4.return_type|}}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=4|desc=yes}}</p>}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=4|desc=yes|param_desc=yes}}</p>}}
{{#if: {{{function5.return_type|}}}
{{#if: {{{function5.return_type|}}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=5|desc=yes}}</p>}}
   |<p>{{FunctionDeclaration|name={{{name}}}|func=5|desc=yes|param_desc=yes}}</p>}}
 
{{{description}}}
{{{description}}}
{{#if: {{{code1|}}}|{{{code1}}}}}{{#if: {{{code2|}}}|{{{code2}}}}}{{#if: {{{code3|}}}|{{{code3}}}}}{{#if: {{{code4|}}}|{{{code4}}}}}{{#if: {{{code5|}}}|{{{code5}}}}}
{{#if: {{{code1|}}}|{{{code1}}}}}{{#if: {{{code2|}}}|{{{code2}}}}}{{#if: {{{code3|}}}|{{{code3}}}}}{{#if: {{{code4|}}}|{{{code4}}}}}{{#if: {{{code5|}}}|{{{code5}}}}}
{{#if: {{{cli_equiv|}}}|
{{#if: {{{cli_equiv|}}}|
==CLI Equivalent==
<h2>CLI Equivalent</h2>
{{{cli_equiv}}}}}
{{{cli_equiv}}}}}
{{#if: {{{see_also|}}}|{{{see_also|}}}}}
{{#if: {{{see_also|}}}|{{{see_also|}}}}}
{{#if: {{{more_info|}}}|
{{#if: {{{more_info|}}}|
==More Information==
<h2>More Information</h2>
{{{more_info}}}}}
{{{more_info}}}}}
{{#if: {{{special|}}}|
{{#if: {{{special|}}}|
==Special==
<h2>Special</h2>
{{{special}}}}}
{{{special}}}}}
[[Category:Ash Functions]]
[[Category:Ash Functions]]
Line 29: Line 28:
<templatedata>
<templatedata>
{
{
   "description": "Replacement for Template:FunctionPage. Must be used with function pages that follow a specific format.",
   "description": "Replacement for Template:FunctionPage. Must be used with data-driven function pages.",
   "params": {
   "params": {
     "name": {
     "name": {
Line 41: Line 40:
       "label": "Description",
       "label": "Description",
       "description": "Long description that covers all functions. Note: Use <p></p> to separate paragraphs, because double line breaks don't work",
       "description": "Long description that covers all functions. Note: Use <p></p> to separate paragraphs, because double line breaks don't work",
      "required": true,
       "type": "content"
       "type": "content"
     },
     },
Line 46: Line 46:
       "label": "Function 1, description",
       "label": "Function 1, description",
       "description": "Short description for the overloaded function 1 (and so on for functions 2 through 3)",
       "description": "Short description for the overloaded function 1 (and so on for functions 2 through 3)",
      "required": true,
       "type": "content",
       "type": "content",
       "example": "Visits a web page and returns its HTML source."
       "example": "Visits a web page and returns its HTML source."
Line 61: Line 62:
       "type": "line",
       "type": "line",
       "example": "url"
       "example": "url"
    },
    "function1.param1.type": {
      "label": "Function 1, parameter 1 type",
      "description": "Data type of the parameter 1 of the overloaded function 1.",
      "type": "line",
      "example": "int"
     },
     },
     "function1.param1.description": {
     "function1.param1.description": {
Line 79: Line 86:
       "type": "line",
       "type": "line",
       "example": "\"\""
       "example": "\"\""
    },
    "code1": {
      "label": "Example code 1",
      "description": "Example code showing how to use this function. Use [[Template:CodeSample]] to create sample code. (Same for code2 through code5)",
      "type": "content"
    },
    "cli_equiv": {
      "label": "Equivalent gCLI command",
      "description": "If provided, must be a gCLI command that provides functionality equivalent to this function.",
      "type": "line"
    },
    "see_also": {
      "label": "See Also section",
      "description": "If provided, this is used as the content for the See Also section. Use [[Template:SeeAlso]] to build a See Also section.",
      "type": "content"
    },
    "more_info": {
      "label": "More Information section",
      "description": "If provided, this is used as the content for the More Information section",
      "type": "content"
    },
    "special": {
      "label": "Special section",
      "description": "If provided, this is used as the content for the Special section",
      "type": "content"
    },
    "needscode": {
      "label": "Needs code samples?",
      "description": "If set to \"yes\", adds a \"needs code samples\" banner and categorizes the page under [[Category:Needs Code Sample]].",
      "type": "line"
    },
    "improvecode": {
      "label": "Needs improved code samples?",
      "description": "If set to \"yes\", adds a \"needs better code samples\" banner and categorizes the page under [[Category:Needs Code Sample]].",
      "type": "line"
     }
     }
   }
   }
Line 84: Line 126:
</templatedata>
</templatedata>


==Examples==
==Notes==
<pre>{{User:Philmasterplus/TemplateSandbox2
This template is not meant to be used directly, but rather through the use of <pre>{{{format|Function2}}}</pre> in a data-driven function page.
|name=User:Philmasterplus/Sandbox
|function1.return_type=buffer
|function1.short_description=Returns the original HTML source of the page being overridden inside a relay override script.
|function1.description=Returns the original HTML source of the page being overridden. ''This function works only inside a relay override script.''
|function2.return_type=buffer
|function2.short_description=Visits a web page and returns its HTML source.
|function2.description=Makes an HTTP request to a web page and returns its HTML source.
|function2.param1=url
|function2.param1.type=string
|function2.param1.optional=yes
|function2.param1.default=""
|function2.param1.description=URL of the page to visit. If a relative URL is provided, it is treated as an in-game page.
|function2.param2=use_POST
|function2.param2.type=boolean
|function2.param2.optional=yes
|function2.param2.default=true
|function2.param2.description=If <code>true</code>, makes an HTTP POST request when visiting the URL. Otherwise, makes a GET request.
|function2.param3=encoded
|function2.param3.type=boolean
|function2.param3.optional=yes
|function2.param3.default=false
|function2.param3.description=If <code>true</code>, KoLmafia assumes that <code>url</code> has already been [[wikipedia:Percent-encoding|URL-encoded]] and will not encode it.
|description=
<p>Returns the HTML from the visited page (not just what is displayed when visiting the page, but all markup) by performing a POST request if {{pspan|use_POST}} is omitted or true, or a GET request if false. Note that for addresses inside of KoL, it is only necessary to supply the page name for {{pspan|page}}, and KoLmafia will populate the rest of the url. However, pages outside of KoL require the full url to be supplied for {{pspan|page}}.</p>
 
<p>The version with no parameters is only meaningful in a relay override script; it retrieves the server page that your script is overriding.  All four versions behave slightly differently in a relay script; they retrieve a version of the page with any KoLmafia decorations added, rather than the raw page from the server.</p>


<p>In a POST request, if &pwd is part of the {{pspan|page}} string, it will automatically be replaced by &pwd=###### where ###### is the password hash for the current session. For a GET request the password hash will not be added so you'll want to use {{f|my_hash}}.</p>
Use this as the starting point for a data-driven function page:
}}</pre>


{{User:Philmasterplus/TemplateSandbox2
<pre>
|name=User:Philmasterplus/Sandbox
&lt;onlyinclude&gt;{{{{{format|Function2}}}
|function1.return_type=buffer
|name=
|function1.short_description=Returns the original HTML source of the page being overridden inside a relay override script.
|function1.return_type=
|function1.description=Returns the original HTML source of the page being overridden. ''This function works only inside a relay override script.''
|function1.description=
|function2.return_type=buffer
|function1.param1=
|function2.short_description=Visits a web page and returns its HTML source.
|function1.param1.type=
|function2.description=Makes an HTTP request to a web page and returns its HTML source.
|function1.param1.optional=
|function2.param1=url
|function1.param1.default=
|function2.param1.type=string
|function1.param1.description=
|function2.param1.optional=yes
|function1.param2=
|function2.param1.default=""
|function1.param2.type=
|function2.param1.description=URL of the page to visit. If a relative URL is provided, it is treated as an in-game page.
|function1.param2.optional=
|function2.param2=use_POST
|function1.param2.default=
|function2.param2.type=boolean
|function1.param2.description=
|function2.param2.optional=yes
|function1.param3=
|function2.param2.default=true
|function1.param3.type=
|function2.param2.description=If <code>true</code>, makes an HTTP POST request when visiting the URL. Otherwise, makes a GET request.
|function1.param3.optional=
|function2.param3=encoded
|function1.param3.default=
|function2.param3.type=boolean
|function1.param3.description=
|function2.param3.optional=yes
|function1.param4=
|function2.param3.default=false
|function1.param4.type=
|function2.param3.description=If <code>true</code>, KoLmafia assumes that <code>url</code> has already been [[wikipedia:Percent-encoding|URL-encoded]] and will not encode it.
|function1.param4.optional=
|function1.param4.default=
|function1.param4.description=
|function1.param5=
|function1.param5.type=
|function1.param5.optional=
|function1.param5.default=
|function1.param5.description=
|function2.return_type=
|function2.description=
|function2.param1=
|function2.param1.type=
|function2.param1.optional=
|function2.param1.default=
|function2.param1.description=
|function2.param2=
|function2.param2.type=
|function2.param2.optional=
|function2.param2.default=
|function2.param2.description=
|function2.param3=
|function2.param3.type=
|function2.param3.optional=
|function2.param3.default=
|function2.param3.description=
|function2.param4=
|function2.param4.type=
|function2.param4.optional=
|function2.param4.default=
|function2.param4.description=
|function2.param5=
|function2.param5.type=
|function2.param5.optional=
|function2.param5.default=
|function2.param5.description=
|function3.return_type=
|function3.description=
|function3.param1=
|function3.param1.type=
|function3.param1.optional=
|function3.param1.default=
|function3.param1.description=
|function3.param2=
|function3.param2.type=
|function3.param2.optional=
|function3.param2.default=
|function3.param2.description=
|function3.param3=
|function3.param3.type=
|function3.param3.optional=
|function3.param3.default=
|function3.param3.description=
|function3.param4=
|function3.param4.type=
|function3.param4.optional=
|function3.param4.default=
|function3.param4.description=
|function3.param5=
|function3.param5.type=
|function3.param5.optional=
|function3.param5.default=
|function3.param5.description=
|function4.return_type=
|function4.description=
|function4.param1=
|function4.param1.type=
|function4.param1.optional=
|function4.param1.default=
|function4.param1.description=
|function4.param2=
|function4.param2.type=
|function4.param2.optional=
|function4.param2.default=
|function4.param2.description=
|function4.param3=
|function4.param3.type=
|function4.param3.optional=
|function4.param3.default=
|function4.param3.description=
|function4.param4=
|function4.param4.type=
|function4.param4.optional=
|function4.param4.default=
|function4.param4.description=
|function4.param5=
|function4.param5.type=
|function4.param5.optional=
|function4.param5.default=
|function4.param5.description=
|function5.return_type=
|function5.description=
|function5.param1=
|function5.param1.type=
|function5.param1.optional=
|function5.param1.default=
|function5.param1.description=
|function5.param2=
|function5.param2.type=
|function5.param2.optional=
|function5.param2.default=
|function5.param2.description=
|function5.param3=
|function5.param3.type=
|function5.param3.optional=
|function5.param3.default=
|function5.param3.description=
|function5.param4=
|function5.param4.type=
|function5.param4.optional=
|function5.param4.default=
|function5.param4.description=
|function5.param5=
|function5.param5.type=
|function5.param5.optional=
|function5.param5.default=
|function5.param5.description=
|description=
|description=
<p>Returns the HTML from the visited page (not just what is displayed when visiting the page, but all markup) by performing a POST request if {{pspan|use_POST}} is omitted or true, or a GET request if false. Note that for addresses inside of KoL, it is only necessary to supply the page name for {{pspan|page}}, and KoLmafia will populate the rest of the url. However, pages outside of KoL require the full url to be supplied for {{pspan|page}}.</p>
|code1={{CodeSample
  |title=Code Samples
  |description=
  |code=
  |moreinfo=
}}
|code2={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|code3={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|code4={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|code5={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|see_also={{SeeAlso|}}
|cli_equiv=
|more_info=
|special=
|{{{1|}}}
}}&lt;/onlyinclude&gt;
&lt;!-- Add an appropriate function subcategory here, e.g. [[Category:Adventuring]],
    then delete this comment --&gt;
</pre>


<p>The version with no parameters is only meaningful in a relay override script; it retrieves the server page that your script is overriding.  All four versions behave slightly differently in a relay script; they retrieve a version of the page with any KoLmafia decorations added, rather than the raw page from the server.</p>
Data-driven function pages are incompatible with old-style function pages (i.e. ones that use [[Template:FunctionPage]]).


<p>In a POST request, if &pwd is part of the {{pspan|page}} string, it will automatically be replaced by &pwd=###### where ###### is the password hash for the current session. For a GET request the password hash will not be added so you'll want to use {{f|my_hash}}.</p>
[[Category:Basic Templates]]
}}
</noinclude>
</noinclude>

Latest revision as of 14:10, 13 July 2021

Replacement for Template:FunctionPage. Must be used with data-driven function pages.

Template parameters[Edit template data]

ParameterDescriptionTypeStatus
ASH function namename

Name of the ASH function. This should match the function page name.

Example
visit_url
Linerequired
Descriptiondescription

Long description that covers all functions. Note: Use <p></p> to separate paragraphs, because double line breaks don't work

Contentrequired
Function 1, descriptionfunction1.description

Short description for the overloaded function 1 (and so on for functions 2 through 3)

Example
Visits a web page and returns its HTML source.
Contentrequired
Function 1, return typefunction1.return_type

Return type of the overloaded function 1.

Example
buffer
Linerequired
Function 1, parameter 1function1.param1

Name of the parameter 1 of the overloaded function 1 (and so on for parameters 2 through 5).

Example
url
Lineoptional
Function 1, parameter 1 typefunction1.param1.type

Data type of the parameter 1 of the overloaded function 1.

Example
int
Lineoptional
Function 1, parameter 1 descriptionfunction1.param1.description

Description of parameter 1 of the overloaded function 1.

Example
URL of the page to visit. If a relative URL is provided, it is treated as an in-game page.
Contentoptional
Function 1, parameter 1 is optional?function1.param1.optional

"yes" = optional. Any non-empty string will do, but please use "yes" to make standardization easier.

Example
yes
Lineoptional
Function 1, parameter 1 default valuefunction1.param1.default

If this is specified, function1.param1.optional must be "yes"

Example
""
Lineoptional
Example code 1code1

Example code showing how to use this function. Use [[Template:CodeSample]] to create sample code. (Same for code2 through code5)

Contentoptional
Equivalent gCLI commandcli_equiv

If provided, must be a gCLI command that provides functionality equivalent to this function.

Lineoptional
See Also sectionsee_also

If provided, this is used as the content for the See Also section. Use [[Template:SeeAlso]] to build a See Also section.

Contentoptional
More Information sectionmore_info

If provided, this is used as the content for the More Information section

Contentoptional
Special sectionspecial

If provided, this is used as the content for the Special section

Contentoptional
Needs code samples?needscode

If set to "yes", adds a "needs code samples" banner and categorizes the page under [[Category:Needs Code Sample]].

Lineoptional
Needs improved code samples?improvecode

If set to "yes", adds a "needs better code samples" banner and categorizes the page under [[Category:Needs Code Sample]].

Lineoptional

Notes

This template is not meant to be used directly, but rather through the use of

{{{format|Function2}}}

in a data-driven function page.

Use this as the starting point for a data-driven function page:

<onlyinclude>{{{{{format|Function2}}}
|name=
|function1.return_type=
|function1.description=
|function1.param1=
|function1.param1.type=
|function1.param1.optional=
|function1.param1.default=
|function1.param1.description=
|function1.param2=
|function1.param2.type=
|function1.param2.optional=
|function1.param2.default=
|function1.param2.description=
|function1.param3=
|function1.param3.type=
|function1.param3.optional=
|function1.param3.default=
|function1.param3.description=
|function1.param4=
|function1.param4.type=
|function1.param4.optional=
|function1.param4.default=
|function1.param4.description=
|function1.param5=
|function1.param5.type=
|function1.param5.optional=
|function1.param5.default=
|function1.param5.description=
|function2.return_type=
|function2.description=
|function2.param1=
|function2.param1.type=
|function2.param1.optional=
|function2.param1.default=
|function2.param1.description=
|function2.param2=
|function2.param2.type=
|function2.param2.optional=
|function2.param2.default=
|function2.param2.description=
|function2.param3=
|function2.param3.type=
|function2.param3.optional=
|function2.param3.default=
|function2.param3.description=
|function2.param4=
|function2.param4.type=
|function2.param4.optional=
|function2.param4.default=
|function2.param4.description=
|function2.param5=
|function2.param5.type=
|function2.param5.optional=
|function2.param5.default=
|function2.param5.description=
|function3.return_type=
|function3.description=
|function3.param1=
|function3.param1.type=
|function3.param1.optional=
|function3.param1.default=
|function3.param1.description=
|function3.param2=
|function3.param2.type=
|function3.param2.optional=
|function3.param2.default=
|function3.param2.description=
|function3.param3=
|function3.param3.type=
|function3.param3.optional=
|function3.param3.default=
|function3.param3.description=
|function3.param4=
|function3.param4.type=
|function3.param4.optional=
|function3.param4.default=
|function3.param4.description=
|function3.param5=
|function3.param5.type=
|function3.param5.optional=
|function3.param5.default=
|function3.param5.description=
|function4.return_type=
|function4.description=
|function4.param1=
|function4.param1.type=
|function4.param1.optional=
|function4.param1.default=
|function4.param1.description=
|function4.param2=
|function4.param2.type=
|function4.param2.optional=
|function4.param2.default=
|function4.param2.description=
|function4.param3=
|function4.param3.type=
|function4.param3.optional=
|function4.param3.default=
|function4.param3.description=
|function4.param4=
|function4.param4.type=
|function4.param4.optional=
|function4.param4.default=
|function4.param4.description=
|function4.param5=
|function4.param5.type=
|function4.param5.optional=
|function4.param5.default=
|function4.param5.description=
|function5.return_type=
|function5.description=
|function5.param1=
|function5.param1.type=
|function5.param1.optional=
|function5.param1.default=
|function5.param1.description=
|function5.param2=
|function5.param2.type=
|function5.param2.optional=
|function5.param2.default=
|function5.param2.description=
|function5.param3=
|function5.param3.type=
|function5.param3.optional=
|function5.param3.default=
|function5.param3.description=
|function5.param4=
|function5.param4.type=
|function5.param4.optional=
|function5.param4.default=
|function5.param4.description=
|function5.param5=
|function5.param5.type=
|function5.param5.optional=
|function5.param5.default=
|function5.param5.description=
|description=
|code1={{CodeSample
  |title=Code Samples
  |description=
  |code=
  |moreinfo=
}}
|code2={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|code3={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|code4={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|code5={{CodeSample
  |description=
  |code=
  |moreinfo=
}}
|see_also={{SeeAlso|}}
|cli_equiv=
|more_info=
|special=
|{{{1|}}}
}}</onlyinclude>
<!-- Add an appropriate function subcategory here, e.g. [[Category:Adventuring]],
     then delete this comment -->

Data-driven function pages are incompatible with old-style function pages (i.e. ones that use Template:FunctionPage).