Ruff! - Runtime Formatting Function Reference (V1.0.6)

# ::ruff::sampleTop, Main, Index

## Introductionsample, Top, Main, Index

The code in this namespace illustrates the various documentation features in Ruff!. The corresponding source is here or click the Show source link below each procedure or method documentation to see the source from which the documentation was generated. See the main ::ruff documentation for a full description.

The documentation (such as this section) not specific to a procedure or method is placed in the variable `_ruff_preamble` within each namespace.

## Formattingsample, Top, Main, Index

The formatting elements described below may appear both within `_ruff_preamble` content as well as proc and method comments.

### Listssample, Top, Main, Index

This is an unnumbered list.

      * First item
      * Second
      item
      across multiple lines
      * Third item

This is displayed as

- First item
- Second item across multiple lines
- Third item

This is a definition list.

      itema - Definition of item A
      itemb - Definition of item B
        across multiple lines.

Definition lists are displayed in an output-specific format.

itema | Definition of item A.
itemb | Definition of item B across multiple lines.

### Inline formattingsample, Top, Main, Index

    Basic markdown inline formatting is supported as
    `code`, *emphasis*, **strong** and ***strong emphasis***.

Basic markdown inline formatting is supported as `code`, emphasis, strong and strong emphasis.

### Linkssample, Top, Main, Index

    Links may be references to program elements, e.g. [Derived], to
    external resources, e.g. [example](https://www.example.com) or
    explicit, e.g. <https://ruff.magicsplat.com>.

Links may be references to program elements, e.g. Derived, to external resources, e.g. example or explicit, e.g. https://ruff.magicsplat.com.

### Preformatted blockssample, Top, Main, Index

    ```
    Lines consisting of *3* or more backquotes can be used
    to bracket unformatted content
    like
    this paragraph.
    ```

The remaining sections show how commands and classes are documented. Click on the Show source link to see the underlying source code for the procedure or method from which the documentation was generated.

## Commandssample, Top, Main, Index

#### character_at [::ruff::sample]sample, Top, Main, Index

Get the character from a string.

character_at text ?pos?

##### Parameters

`text` | Text string.
`pos` | Character position. Optional, default `0`.

##### Description

The command will treat negative values of `$pos` as offset from the end of the string.

An error exception is raised if `$pos` is not within bounds.

##### Return value

Returns the character at index `$pos` in string `$text`.

Show source

    proc ::ruff::sample::character_at {text {pos 0}} {

        # Get the character from a string.
        #  text - Text string.
        #  pos  - Character position.
        # The command will treat negative values of $pos as offset from
        # the end of the string.
        #
        # Returns the character at index $pos in string $text.
        set n [string length $text]
        if {[tcl::mathfunc::abs $pos] >= [string length $text]} {
            #ruff
            # An error exception is raised if $pos is not within bounds.
            error "Index $pos out of bounds."
        }
        if {$pos < 0} {
            return [string index $text end$pos]
        } else {
            return [string index $text $pos]
        }
    }

#### ensemble_proc cmdA [::ruff::sample]sample, Top, Main, Index

Implements cmdA for an ensemble procedure

ensemble_proc cmdA

Show source

    proc ::ruff::sample::ensemble_proc::cmdA {} {

        # Implements cmdA for an ensemble procedure
    }
    # NOTE: showing source of procedure implementing ensemble subcommand.

#### ensemble_proc cmdB [::ruff::sample]sample, Top, Main, Index

Implements cmdB for an ensemble procedure

ensemble_proc cmdB

Show source

    proc ::ruff::sample::ensemble_proc::cmdB {} {

        # Implements cmdB for an ensemble procedure
    }
    # NOTE: showing source of procedure implementing ensemble subcommand.

#### proc_full [::ruff::sample]sample, Top, Main, Index

This first line is the summary line for documentation.

proc_full arg ?optarg? ?args?

##### Parameters

`arg` | First parameter.
`optarg` | An optional parameter. Optional, default `AVALUE`.
`args` | Optional arguments.
`-switch VALUE` | An optional switch.

##### Description

This is the general description of the procedure composed of multiple paragraphs. It is separated from the parameter list above by one or more empty comments.

This is the second paragraph. The next paragraph (in the source comments) starts with the word Returns and hence will be treated by Ruff! as describing the return value.

A definition list has a similar form to the argument list. For example, optarg may take the following values:

AVALUE | One possible value.
BVALUE | Another possible value.
CVALUE | A third value but note the intervening blank comment above in the source code.

Bullet lists are indicated by a starting `-` or `*` character.

- This is a bullet list iterm

- This is also a bullet list item

An optional See also section may be used to cross-reference other program elements. Each line of this section must be parsable as a Tcl list.

Thanks to the #ruff marker, this paragraph will be included by Ruff! even though it is not in the initial block of comments. This is useful for putting documentation for a feature right next to the code implementing it.

##### Return value

Returns a value. Because it started with the Returns keyword, this paragraph is treated as the return value description no matter where it appears.

##### See also

proc_without_docs, Base, https://www.magicsplat.com, ensemble_proc cmdA, ensemble_proc cmdB

Show source

    proc ::ruff::sample::proc_full {arg {optarg AVALUE} args} {

        # This first line is the summary line for documentation.
        # arg - first parameter
        # optarg - an optional parameter
        # -switch VALUE - an optional switch
        #
        # This is the general description of the procedure
        # composed of multiple paragraphs. It is separated from
        # the parameter list above by one or more empty comments.
        #
        # This is the second paragraph. The next paragraph (in the *source* comments)
        # starts with the word Returns and hence will be treated
        # by Ruff! as describing the return value.
        #
        # Returns a value. Because it started with the **Returns**
        # keyword, this paragraph is treated as the return value
        # description no matter where it appears.
        #
        # A definition list has a similar form to the argument
        # list. For example, optarg may take the following values:
        #  AVALUE - one possible value
        #  BVALUE - another possible value
        #
        #  CVALUE - a third value but note the intervening blank comment
        #  above in the source code.
        # Bullet lists are indicated by a starting `-` or `*` character.
        # - This is a bullet list iterm
        # * This is also a bullet list item
        #
        # An optional *See also* section may be used to
        # cross-reference other program elements. Each line of this section
        # must be parsable as a Tcl list.
        #
        # See also: proc_without_docs [Base] <https://www.magicsplat.com>
        #   "ensemble_proc cmdA" {ensemble_proc cmdB}

        # This paragraph will be ignored by Ruff! as it is not part
        # of the initial block of comments.

        some code

        #ruff
        # Thanks to the #ruff marker, this paragraph will be
        # included by Ruff! even though it is not in the initial block
        # of comments. This is useful for putting documentation for
        # a feature right next to the code implementing it.

        some more code.
    }

#### proc_without_docs [::ruff::sample]sample, Top, Main, Index

proc_without_docs first_arg second_arg

##### Parameters

`first_arg` | Not documented.
`second_arg` | Not documented.

Show source

    proc ::ruff::sample::proc_without_docs {first_arg second_arg} {

    }

## Classessample, Top, Main, Index

### Base [::ruff::sample]sample, Top, Main, Index

##### Method summary

constructor | Constructor for the class.
destructor | Destructor for the class.
& | Method to test & escaping in HTML.
* | Method to test regexp special chars.
+ | Method to test regexp special chars.
< | Method to test < escaping in HTML.
<tag> | An explicitly exported method looking like a html tag.
> | Method to test > escaping in HTML.
_ | Method to test underscores.
base_method | Base_method is defined only in the base class.
fwd_method | Method forwarded to string range.
overridable_method | This method will be overridden in the derived class.

##### Subclasses

Derived

#### constructor [::ruff::sample::Base]Base, Top, Main, Index

Constructs the class

Base create arg

##### Parameters

`arg` | Argument to constructor.

##### Description

The constructor for the class should also include general information for the class.

Show source

    method constructor {arg} {

        # Constructs the class
        #   arg - argument to constructor
        # The constructor for the class should also include
        # general information for the class.
    }

#### destructor [::ruff::sample::Base]Base, Top, Main, Index

Releases all resources and destroys the class

OBJECT destroy

Show source

    method destructor {} {

        # Releases all resources and destroys the class
    }

#### & [::ruff::sample::Base]Base, Top, Main, Index

Method to test & escaping in HTML

OBJECT &

Show source

    method & {} {

        # Method to test & escaping in HTML
    }

#### * [::ruff::sample::Base]Base, Top, Main, Index

Method to test regexp special chars

OBJECT *

Show source

    method * {} {

        # Method to test regexp special chars
    }

#### + [::ruff::sample::Base]Base, Top, Main, Index

Method to test regexp special chars

OBJECT +

Show source

    method + {} {

        # Method to test regexp special chars
    }

#### < [::ruff::sample::Base]Base, Top, Main, Index

Method to test < escaping in HTML

OBJECT <

Show source

    method < {} {

        # Method to test < escaping in HTML
    }

#### <tag> [::ruff::sample::Base]Base, Top, Main, Index

An explicitly exported method looking like a html tag

OBJECT <tag>

##### Description

Verify it also shows in base_method description as well as See also section.

Show source

    method <tag> {} {

        # An explicitly exported method looking like a html tag
        #
        # Verify it also shows in [base_method] description as well
        # as See also section.
    }

#### > [::ruff::sample::Base]Base, Top, Main, Index

Method to test > escaping in HTML

OBJECT >

Show source

    method > {} {

        # Method to test > escaping in HTML
    }

#### _ [::ruff::sample::Base]Base, Top, Main, Index

Method to test underscores

OBJECT _

Show source

    method _ {} {

        # Method to test underscores
    }

#### base_method [::ruff::sample::Base]Base, Top, Main, Index

base_method is defined only in the base class

OBJECT base_method arga argb

##### Parameters

`arga` | First argument.
`argb` | Second argument from.

##### Description

This is method m1

This is a reference to method <tag>.

##### See also

<tag>

Show source

    method base_method {arga argb} {

        # base_method is defined only in the base class
        # arga - first argument
        # argb - second argument from
        #
        # This is method m1
        #
        # This is a reference to method [<tag>].
        #
        # See also: <tag>
    }

#### fwd_method [::ruff::sample::Base]Base, Top, Main, Index

Forwarded to `string range`.

#### overridable_method [::ruff::sample::Base]Base, Top, Main, Index

This method will be overridden in the derived class

OBJECT overridable_method

##### Description

Calls base_method

Show source

    method overridable_method {} {

        # This method will be overridden in the derived class
        #
        # Calls [base_method]
    }

### Derived [::ruff::sample]sample, Top, Main, Index

##### Method summary

`&` | See Base.&
`*` | See Base.*
`+` | See Base.+
`<` | See Base.<
`<tag>` | See Base.<tag>
`>` | See Base.>
`_` | See Base._
added_method | Method defined only in Derived.
`base_method` | See Base.base_method
`fwd_method` | See Base.fwd_method
`mixed_in_method` | See Mixin.mixed_in_method
overridable_method | This method overrides the one defined in Base.

##### Superclasses

Base

##### Mixins

Mixin

#### added_method [::ruff::sample::Derived]Derived, Top, Main, Index

Method defined only in Derived.

OBJECT added_method

Show source

    method added_method {} {

        # Method defined only in [Derived].
    }

#### overridable_method [::ruff::sample::Derived]Derived, Top, Main, Index

This method overrides the one defined in Base.

OBJECT overridable_method

Show source

    method overridable_method {} {

        # This method overrides the one defined in [Base].
    }

### Mixin [::ruff::sample]sample, Top, Main, Index

##### Method summary

mixed_in_method | This method will be mixed into a class.

##### Subclasses

Derived

#### mixed_in_method [::ruff::sample::Mixin]Mixin, Top, Main, Index

This method will be mixed into a class.

OBJECT mixed_in_method arg

##### Parameters

`arg` | An argument to the method.

Show source

    method mixed_in_method {arg} {

        # This method will be mixed into a class.
        # arg - an argument to the method
    }

# Start page

# Index

# ruff

# ruff::app

# ruff::sample

## Introduction

## Formatting

### Lists

### Inline formatting

### Links

### Preformatted blocks

## Commands

#### character_at Get the character from a string.

#### ensemble_proc cmdA Implements cmdA for an ensemble procedure

#### ensemble_proc cmdB Implements cmdB for an ensemble procedure

#### proc_full This first line is the summary line for documentation.

#### proc_without_docs

## Classes

### Base

#### constructor Constructs the class

#### destructor Releases all resources and destroys the class

#### &Method to test & escaping in HTML

#### *Method to test regexp special chars

#### +Method to test regexp special chars

#### <Method to test < escaping in HTML

#### <tag>An explicitly exported method looking like a html tag

#### >Method to test > escaping in HTML

#### _Method to test underscores

#### base_method base_method is defined only in the base class

#### fwd_method

#### overridable_method This method will be overridden in the derived class

### Derived

#### added_method Method defined only in Derived.

#### overridable_method This method overrides the one defined in Base.

### Mixin

#### mixed_in_method This method will be mixed into a class.

Document generated by Ruff!
© 2021 Ashok P. Nadkarni