GO PL/SQL

markdown_plsql_doc_example

GO PLSQL Package Documentation
=====

[TOC]

#**PROCEDURES AND FUNCTIONS**
#**PACKAGES**
##**GO**
GO will be a helpful PL/SQL package which everyone should install and use...someday.

Contact | Details
-|-
author|Ethan Post
email|last_name dot first_name @ gmail.com
url|http://popkola.com
twitter|https://twitter.com/poststop


----

###**(( Comment Parsing ))**

#### <i class="icon-right-open"></i>**doc_to_markdown** - Format PL/SQL documentation into Markdown syntax.

> <i class=" icon-info-circled"></i>Parses PL/SQL comments into Markdown. Load the output file at https://stackedit.io

----

###**(( String Functions ))**

#### <i class="icon-right-open"></i>**single_space** - Convert series of spaces to single space in a string.

----

#### <i class="icon-right-open"></i>**count_leading_spaces** - Get a count of the # of spaces up until the first word.

----

#### <i class="icon-right-open"></i>**first_word** - Get the first word in a string.

----

#### <i class="icon-right-open"></i>**remove_first_word** - Remove first word from string.

----

#### <i class="icon-right-open"></i>**get_item_from_list** - Get an item from a string of delimited values.

----

#### <i class="icon-right-open"></i>**replace_item_in_list** - Replace one of the items in a string of delimited values.

----

#**PACKAGE BODIES**
##**GO**
This package contains a comment parser. Other types of functionality will be added.

----

###**(( Comment Parsing ))**

#### <i class="icon-right-open"></i>**doc_to_markdown** - Parses PL/SQL comments into Markdown syntax. Stored in DOC_LINES table.

The example below shows how to get the documentation for the GO project into a file.
The file can then be viewed at https://stackedit.io
```
 exec go.doc_to_markdown('GO PLSQL Package Documentation', project_name=>'go');
 set lines 1000 pages 100 feed off head off term off trims on
 col text format a999
 spool c:\temp\go_docs_markdown.md
 select text from doc_lines order by line_number;
 spool off;
```

Parameter | Description
-|-
title|   Document title.
project_name|  All PL/SQL objects with at least one matching @project descriptor will be parsed. If null schema_name must be provided.
schema_name|   All PL/SQL objects in this schema will be parsed. If null project_name must be provided.


<i class="icon-attention-circled"></i>**Throws** -     Errors are raised.

----

###**(( GO Internals ))**

#### <i class="icon-right-open"></i>**private_get_doc_objects** - Procedure which parses comments and inserts them into the DOC_TEXT table.

Called from doc_to_markdown. This procedure parses the comments into DOC_TEXT and then
doc_to_markdown parses them from DOC_TEXT into DOC_LINES. Documention is generated by
pulling the data from DOC_LINES.

----

###**(( String Functions ))**

#### <i class="icon-right-open"></i>**single_space** - Returns a string with all spaces reduced to a single space.

```
 > select go.single_space(text=>'A B  C    D') from dual;
 'A B C D'
```

Parameter | Description
-|-
text|   Input text string.


<i class="icon-reply-all"></i>**Return** -        Returns the modified string.

----

#### <i class="icon-right-open"></i>**count_leading_spaces** - Return the number of leading spaces in a string.

Parameter | Description
-|-
text| Input string.


<i class="icon-reply-all"></i>**Return** -  The number of leading spaces in the input string.

----

#### <i class="icon-right-open"></i>**first_word** - Return the first word in a string. Blanks are trimmed.

```
 > select go.first_word('red blue green') from dual;
 'red'
```

Parameter | Description
-|-
text|String to extract the first word from.


<i class="icon-reply-all"></i>**Return** -     First word of string up to first space in string. If there are no spaces it return the original string.

----

#### <i class="icon-right-open"></i>**remove_first_word** - Return everything but the first word in a string. Blanks are trimmed.

```
 > select go.remove_first_word('red blue green') from dual;
 'blue green'
```

Parameter | Description
-|-
text|String to extract the first word from.


<i class="icon-reply-all"></i>**Return** -     Everything in the string with the exception of the first word.

----

#### <i class="icon-right-open"></i>**get_item_from_list** - Return a single item by index from a delimited string of values.

```
 > select go.get_item_from_list('red, blue, green', 2, ',') from dual;
 'blue'
```

Parameter | Description
-|-
the_list|   List of values such as "red, green, blue"
the_index|  Integer value of index, "red" is 1, "green" is 2 and so on.
delim|      Delimitor, defaults to comma. If using spaces make sure you call single_space function first.


<i class="icon-reply-all"></i>**Return** -  Either return the item from the index or null if the indexed value does not exist.

----

#### <i class="icon-right-open"></i>**replace_item_in_list** - Replace a single item by index in a delimited string of values.

```
 > select go.replace_item_in_list('red, blue, green', 2, ',', 'yellow') from dual;
 'red, yellow, green'
```

Parameter | Description
-|-
the_list|   List of values such as "red, green, blue"
the_index|  Integer value of index, "red" is 1, "green" is 2 and so on.
delim|      Delimiter, defaults to comma. If using spaces make sure you call single_space function first.
new_value|  The value you want to use for the replacement.


<i class="icon-reply-all"></i>**Return** -     Either return the item from the index or null if the indexed value does not exist.

----