Skip to content

Commit

Permalink
Updated generated module dsl documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@wayneeseguin
wayneeseguin committed Apr 30, 2011
1 parent 708eb3b commit c6efade
Show file tree
Hide file tree
Showing 20 changed files with 4,245 additions and 0 deletions.
224 changes: 224 additions & 0 deletions content/modules/bash/array/dsl.haml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,227 @@
%h1
Module array

%h2 array_is_nonempty()
%p Checks to see if an array with the name given as the first parameter is nonempty.
%h4 Input Parameters
%p The first parameter is the name of the array variable.
%h4 Stream Outputs
%p None.
%h4 Return Codes
%p
0 if the array is non-empty.
1 if the array is empty.
%h4 Failure Scenarios
%p Fails if the array name, the first parameter, is not given.
%h4 Usage Examples
%pre
%code
:preserve
user$ the_array=(1 2 3 4 5)
user$ array_is_nonempty the_array
user$ echo $?
0

user$ the_array=()
user$ array_is_nonempty the_array
user$ echo $?
1
%h2 array_length()
%p Return the length of the given array.
%h4 Input Parameters
%p First parameter is the name of the array variable.
%h4 Stream Outputs
%p
Prints the length of the named array to the STDOUT stream of the calling
environment.
%h4 Return Codes
%p returns 0
%h4 Failure Scenarios
%p Fails if the array name, first parameter, is not given.
%h4 Usage Examples
%pre
%code
:preserve
user$ the_array=(1 2 3 4 5)
user$ array_length the_array
5
%h2 array_last_element()
%p Print the last element of the given array.
%h4 Input Parameters
%p First parameter is the name of the array variable.
%h4 Stream Outputs
%p
Prints the last element of the named array to the STDOUT stream of the
calling environment.
%h4 Failure Scenarios
%p Fails if the array name, first parameter, is not given.
%h4 Return Codes
%p 0 denoting success
%h4 Usage Examples
%pre
%code
:preserve
$ the_array=(one two three four five)
$ array_last_element the_array
five
%h2 array_first_element()
%p Print the first element of the given array.
%h4 Input Parameters
%p First parameter is the name of the array variable.
%h4 Stream Outputs
%p
Prints the first element of the named array to the STDOUT stream of the
calling environment.
%h4 Return Codes
%p 0 denoting success
%h4 Failure Scenarios
%p Fails if the array name, the first parameter, is not given.
%h4 Usage Examples
%pre
%code
:preserve
$ the_array=(one two three four five)
$ array_first_element the_array
one
%h2 array_push()
%p Appends one or more elements to the array with the given name.
%h4 Input Parameters
%p
The first parameter is the name of the array variable.
Remaining parameters are the elements to be appended to the array.
%h4 Stream Outputs
%p None.
%h4 Returns
%p 0 denoting success
%h4 Failure Scenarios
%p
Fails if the array name, the first parameter, is not given.
Fails if no elements were given (second paramater and beyond).
%h4 Usage Examples
%pre
%code
:preserve
$ the_array=(1 2 3 4 5)
$ array_length the_array
5
%h2 array_append()
%p Return the length of the given array.
%h4 Input Parameters
%p
The first parameter is the name of the array variable.
Remaining parameters are the elements to append to the end of the array.
%h4 Stream Outputs
%p None.
%h4 Returns
%p 0 denoting success
%h4 Failure Scenarios
%p
Fails if the array name, the first parameter, is not given.
Fails if no elements were given to append to the array.
%h4 Usage Examples
%pre
%code
:preserve
user$ the_array=(1)
user$ array_append the_array 2 3 4 5
user$ array_join the_array # print the contents of the array, space separated.
1 2 3 4 5
%h2 array_length()
%p Return the length of the given array.
%h4 Input Parameters
%p The first parameter is the name of the array variable.
%h4 Stream Outputs
%p Prints the length of the named array to the STDOUT stream of the calling environment.
%h4 Usage Examples
%pre
%code
:preserve
user$ cat $HOME/test
#!/usr/bin/env bash
source "/usr/local/bdsm/modules/bash/core/initialize" # Load BDSM framework core.
modules array

my_array=(1 2 3 4)
echo ${my_array[@]}
array_shift my_array
echo ${my_array[@]}

user$ $HOME/test
1 2 3 4
1
2 3 4
%h2 array_unshift()
%p
Prepends one or more elements to the array whose name is given, in the order
given.
%h4 Input Parameters Parameters
%p
The first parameter is the name of the array variable.
Remaining parameters are the elements to prepend to the array.
%h4 Stream Outputs
%p
None.
Yields a failure message if no array name was given.
Yields a failure message if no elements were given to unshift.
%h4 Return Codes
%p 0 denoting success
%h4 Usage Examples
%pre
%code
:preserve
$ the_array=(2 3 4 5)
$ array_unshift 1
user$ array_join the_array # print the contents of the array, space separated.
1 2 3 4 5

$ the_array=(4 5)
$ array_unshift 3 2 1
user$ array_join the_array # print the contents of the array, space separated.
1 2 3 4 5
%h2 array_join()
%p Joins the named array into a string separated by either a space or a given string.
%h4 Input Parameters
%p
The first parameter is the name of the array variable.
The second parameter is the separator between elements in the string, this is optional and defaults to a space.
%h4 Stream Outputs
%p
Prints the elements of the named array, separted by either the 2nd parameter
if given or else a space character, to the STDOUT stream of the calling
environment.
%h4 Return Codes
%p 0 denoting success
%h4 Failure Scenarios
%p Fails if the array name, the first parameter, is not given.
%h4 Usage Examples
%pre
%code
:preserve
$ the_array=(1 2 3 4 5)
$ array_join the_array
1 2 3 4 5

$ array_join the_array '.'
1.2.3.4.5
%h2 array_largest()
%p Outputs the largest element of the array, in the sense of longest string.
%h4 Input Parameters
%p The first element is an array variable name.
%h4 Stream Outputs
%p
Prints the largest elements of the named array to the STDOUT
stream of the calling environment.
%h4 Return Codes
%p 0 denoting success
%h4 Failure Scenarios
%p Fails if the array name, the first parameter, is not given.
%h4 Usage Examples
%pre
%code
:preserve
$ the_array=(1 2 3 4 5)
$ array_join the_array
1 2 3 4 5

$ array_join the_array '.'
1.2.3.4.5
69 changes: 69 additions & 0 deletions content/modules/bash/core/dsl.haml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,72 @@
%h1
Module core

%h2 bdsm_exports()
%p
Exports bdsm framework relevant environment variables for extension action
processes.
%h4 Input Parameters
%p None.
%h4 Stream Outputs
%p None.
%h4 Return Codes
%p 0 for success.
%h4 Failure Scenarios
%p No failure scenarios currently.
%h4 Usage Examples
%pre
%code
:preserve
user$ bdsm_exports
%h2 bdsm_version()
%p Reads the currently installed bdsm version into the variable 'bdsm_version'.
%h4 Input Parameters
%p None.
%h4 Stream Outputs
%p None.
%h4 Environmental effects
%p The variable 'bdsm_version' will be set after the function is executed.
%h4 Return Codes
%p 0 for success.
%h4 Failure Scenarios
%p No failure scenarios currently.
%h4 Usage Examples
%pre
%code
:preserve
user$ bdsm_version
user$ echo $bdsm_version
69.69.69
%h2 NIY()
%p
Prints a failure message and backtrace to the screen letting the caller know
that the requested feature has not yet been implemented.
%h4 Input Parameters
%p None.
%h4 Stream Outputs
%p
Prints "This feature has not yet been implemented." to STDERR of the calling
environment.
%h4 Environmental effects
%p None.
%h4 Return Codes
%p None, only exit is through failure.
%h4 Failure Scenarios
%p Fails always.
%h4 Usage Examples
%pre
%code
:preserve
user$ cat $HOME/test
#!/usr/bin/env bash
source "/usr/local/bdsm/modules/bash/core/initialize" # Load BDSM framework core.
NIY

user$ $HOME/test
ERROR: This feature has not yet been implemented.
Backtrace:
Trace Line Function File
3. 262 fail() /usr/local/bdsm/modules/bash/logging/dsl
2. 5 NIY() /usr/local/bdsm/modules/bash/extensions/dsl
1. 5 main() /Users/wayneeseguin/test
> modules/bash/logging/dsl fail() 263 $ exit 1
29 changes: 29 additions & 0 deletions content/modules/bash/defaults/dsl.haml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,32 @@
%h1
Module defaults

%h2 read_default()
%p Reads default values from an extension's config/defaults file.
%h4 Input Parameters
%p
First parameter is the defaults file key to read (key=value).
Second parameter is the variable name to store the retrieved value in.
Remaining parameters are parsed out as token, value and prefix
into|as
%variable{:name => ""}
prefix
%name
%variable # If no specifier.
%h4 Stream Outputs
%p None.
%h4 Environmental effects
%p
A variable will be set to the value, if the value is nonempty. If no variable
name is specified the variable will be assigned the same name as the key.
%h4 Return Codes
%p 0 for success.
%h4 Failure Scenarios
%p Fails if no arguments are passed in, at least need to specify a key.
%h4 Usage Examples
%pre
%code
:preserve
user$ read_default "version" prefix "package" # extension is nginx for example
user$ echo $package_version
1.0.0
Loading

0 comments on commit c6efade

Please sign in to comment.