Paragraphs

A '''paragraph''' (A.K.A. '''function''' or '''paragraph''') is FiM++'s way of encapsulating code that runs. Very little code (Such as global variable declaration) runs outside paragraphs.

== Related Phrases ==
Here are the [[reserved phrases]] used in paragraphs:

* [[Paragraph Declaration]]
** {{code|keyword|I learned}}
** {{code|keyword|<strong>Today</strong> I learned}}
** {{code|keyword|using}}
** {{code|keyword|as}}
** {{code|keyword|with}}

* [[Paragraph Returning]]
** {{code|keyword|Then you get}}

* [[Paragraph Ending]]
** {{code|keyword|That's all about}}

* [[Paragraph Calling]]
** {{code|keyword|I remembered}}
** {{code|keyword|I would}}

== Name ==
=== Restrictions ===
Each paragraph name has the following restrictions:
* Must '''not''' contain any [[keywords]] (However, [[operators]] and [[literals]] are okay)
* Must '''not''' contain any [[punctuation]]
* Must begin with one non-[[whitespace]], non-[[literal]] character
* Must end with one non-whitespace character character

=== Freedoms ===
Each paragraph name also has the following freedoms:
* There is no hard limit on the length
* May have any whitespace character in them
* May contain [[operators]] that do not share a name with keywords
* May contain [[literals]], as long as they are not at the beginning of the name
* May contain apostrophes, as they are not [[punctuation]]
* Encoded in [[Wikipedia:UTF-8|UTF-8]]

=== Examples ===
Here are some examples of '''good''' paragraph names:
* {{codeblock|{{code|paragraph|how to fly}}}}
** Paragraph names can have spaces in them.

* {{codeblock|{{code|paragraph|something simple}}}}
** Paragraph names don't have to start with "how to".

* {{codeblock|{{code|paragraph|how to sing Applejack's Drinking Song}}}}
** Even though {{code|apostrophe|'}} is used to declare [[characters|character]] literals, it is used in the middle of a name, so it is okay.

* {{codeblock|{{code|paragraph|when to tell True Facts}}}}
** Even though {{code|literal|true}} is a literal, FiM++ is '''case-sensitive''', so {{code|not a literal|True}} is valid for paragraph naming.

* {{codeblock|{{code|paragraph|why Cloud 9 is the best hotel in Cloudsdale}}}}
** Even though {{code|literal|9}} is a number literal, it is not at the beginning of the paragraph name



Here are some examples of '''bad''' paragraph names:
* {{codeblock|{{code|paragraph|why {{codeerror|I learned}}}}}}
** {{code|keyword|I learned}} is a keyword, so this will not compile.

* {{codeblock|{{code|paragraph|how to {{codeerror|multiply}}}}}}
** "{{code|operator|multiply}}" is an operator, so this will not compile.

* {{codeblock|{{code|paragraph|about Applejack}}{{code|punctuation|,}}{{code|whitespace|&nbsp;}}{{codeerror|Rarity{{code|punctuation|,}}{{code|whitespace|&nbsp;}}{{code|keyword|and}}{{code|whitespace|&nbsp;}}Rainbow Dash}}}}
** compiler thinks "{{code|punctuation|,}}" is the end of the paragraph name "{{code|paragraph|about Applejack}}", and doesn't know what to do with the rest

* {{codeblock|{{code|paragraph|about Friendship}}{{code|whitespace|&nbsp;}}{{codeerror|and{{code|whitespace|&nbsp;}}Magic}}}}
** "{{code|keyword|and}}" 'is an operator and keyword.

* {{codeblock|{{code|literal|'s}}{{codeerror|arcasm}}{{code|literal|' }}{{codeerror|uses quotes}}}}
** {{code|apostrophe|'}} is used to start a character literal (such as {{code|literal|'a'}}, so the compiler sees this as an unclosed character literal.

* {{codeblock|{{code|literal|{{codeerror|99}}}}{{code|whitespace|&nbsp;}}{{codeerror|ways to get salted}}}}
** {{code|literal|99}} is ''always'' a literal, so it cannot be the beginning of a paragraph name. Additionally, the compiler doesn't know how to handle the rest of the line.

== Declaration ==
{{Main|Paragraph Declaration}}

Paragraphs are declared with the text "{{code|keyword|I learned}}", followed by the name of the paragraph and a [[punctuation]]. [[#Mane Paragraphs|Mane paragraphs]] start with "{{code|keyword|<strong>Today</strong> I learned}}". Return types can be left blank for a void return type, or will follow the paragraph name and the word "{{code|keyword|with}}" or "{{code|keyword|as}}. Parameters ([[values]] that are sent to the paragraph) follow the return type and the word "{{code|keyword|using}}" and are separated from each other with "{{code|keyword|and}}".

== Returning ==
In order to return a value from a paragraph, the the phrase "{{code|keyword|Then you get}}" is used, followed by the returned [[value]], followed by punctuation. Returned values can be paragraphs, variables, or literals. Returned values must be the same type as is specified in the paragraph declaration.

=== Example ===
: {{codeblock|{{code|keyword|Then you get}}{{code|whitespace|&nbsp;}}{{code|variable|the result}}{{code|punctuation|.}}}}


== Closing ==
Paragraphs are closed with the phrase "{{code|keyword|That's all about}}", followed by the paragraph's name, followed by a punctuation.

=== Example ===
: {{codeblock|{{code|keyword|That's all about}}{{code|whitespace|&nbsp;}}{{code|paragraph|how to multiply}}{{code|punctuation|!}}}}


== Calling ==
When used to read, store, or return a value, paragraphs are called in the same context as a variable; simply use the name of a paragraph instead of the name of a variable. Parameters can be specified just like they are declared (using "{{code|keyword|using}}"). To call a paragraph and ignore its returned value, start a line with "{{code|keyword|I remembered}}" or "{{code|keyword|I would}}, followed by the paragraph name and any parameters, then the punctuation.

* {{codeblock|{{tag|keyword|I remembered}}{{tag|whitespace}}{{tag|paragraph}}{{tag|punctuation}}}}
* {{codeblock|{{tag|variable}}{{tag|whitespace}}{{tag|keyword|assign}}{{tag|whitespace}}{{tag|paragraph}}{{tag|punctuation}}}}

=== Examples ===
Calling a paragraph and ignoring its return value:
: {{codeblock|{{code|keyword|I remembered}}{{code|whitespace|&nbsp;}}{{code|paragraph|how to count}}{{code|punctuation|.}}}}

Storing the return value of a paragraph into a variable after passing the paragraph two parameters:
: {{codeblock|{{code|variable|The number of pies}}{{code|whitespace|&nbsp;}}{{code|keyword|is now}}{{code|whitespace|&nbsp;}}{{code|paragraph|how to multiply}}{{code|whitespace|&nbsp;}}{{code|keyword|using}}{{code|whitespace|&nbsp;}}{{code|variable|cakes}}{{code|whitespace|&nbsp;}}{{code|keyword|and}}{{code|whitespace|&nbsp;}}{{code|variable|cookies}}{{code|punctuation|.}}}}


== Mane Paragraphs ==
Mane paragraphs are paragraphs that run without being explicitly called by code. They can also be run by being called in the code. When the program is run, each mane paragraph is run once, in order of declaration.