# $EPIC: ignorectl,v 1.2 2005/03/12 05:23:23 jnelson Exp $
Synopsis:
   $ignorectl(REFNUMS)
   $ignorectl(REFNUM <refnum>)
   $ignorectl(ADD <ignore-pattern> [level-desc])
   $ignorectl(CHANGE <refnum> [level-desc])
   $ignorectl(DELETE <refnum>)
   $ignorectl(PATTERN <wildcard-pattern>)
   $ignorectl(RPATTERN <nick!user@host>)
   $ignorectl(WITH_TYPES [level-desc])
   $ignorectl(GET <refnum> <item>)
   $ignorectl(SET <refnum> <item> <value>)

Technical:
   $ignorectl(REFNUMS)
   - Return all integer refnums for all active ignores.
   $ignorectl(REFNUM <ignore-pattern>)
   - Given an exact ignore pattern, return that ignore's refnum. 
   $ignorectl(ADD <ignore-pattern> [level-desc]) 
   - Add a new ignore, ala /IGNORE <ignore-pattern> <level-desc> and return 
     the refnum for the new ignore.  <ignore-pattern> is taken literally and 
     should not contain spaces or commas.
   $ignorectl(CHANGE <refnum> [level-desc])
   - Change the <refnum> ignore by adding or subtracting levels as indicated 
     by [level-desc].  If <refnum> is not a number or does not represent a 
     valid ignore, the empty string is returned.  Otherwise, <refnum> is 
     returned.
   $ignorectl(DELETE <refnum>) 
   - Remove the ignore numbered <refnum>

   $ignorectl(PATTERN <wildcard pattern>)
   - The effect of $igmask(<wildcard pattern>): treating each ignore pattern 
     as a literal string, return all refnums whose ignore masks are matched by 
     the <wildcard pattern>.
   $ignorectl(RPATTERN <nick!user@host>)
   - The effect of $rigmask(<nick!user@host>): treating the argument as a 
     nick!user@host string, return all refnums whose ignore masks match the 
     nick!user@host string, that is, each ignore which would "cover" the 
     nick!user@host.
   $ignorectl(WITH_TYPES [level-desc])
   - The effect of $rigtype([level-desc]): return the refnums of all ignores 
     which contain at least all of the levels indicated.  It is possible for 
     an ignore to have MORE levels set, but of those levels which are 
     requested, all of them must be present.

   $ignorectl(GET <refnum> NICK)
   - Return the ignore-pattern for the ignore refnum
   $ignorectl(GET <refnum> LEVELS)
   - Like $igtype(), but better: return a space separated list of all of the 
     ignore levels that are active for this ignore, each level prefixed with 
     exactly one character which indicates that level's disposition:
   	/<level>        Suppressive ignore
   	+<level>        Highlight ignore
   	^<level>        Exceptive ignore
   $ignorectl(GET <refnum> SUPPRESS)
   - Return an integer value that contains a bitwise representation of all of 
     the suppressed levels for this ignore.  The exact layout of this value is 
     epic-version-dependant and may change in the future.  If you use this 
     value in a script, make sure you are using a layout compatable with the 
     version of epic the user is using.
   $ignorectl(GET <refnum> EXCEPT)
   - Return an integer value that contains a bitwise representation of all of 
     the excepted levels for this ignore.  See above for warning about trying 
     to use this value.
   $ignorectl(GET <refnum> HIGHLIGHT)
   - Return an integer value that contains a bitwise representation of all of 
     the highlighted levels for this ignore.  See above for warning about 
     trying to use this value.
   $ignorectl(GET <refnum> EXPIRATION)
   - Return the time the ignore is to expire as two integers. The first integer
     is the seconds and the second number is the milliseconds.  This is the 
     same format that $utime() uses.  If the ignore does not expire, both 
     values are 0.
   $ignorectl(GET <refnum> REASON)
   - Return the reason the user set the ignore, if any.
   $ignorectl(GET <refnum> CREATION)
   - Return the $utime() when the ignore was created.
   $ignorectl(GET <refnum> LAST_USED)
   - Return the last $utime() the ignore was used (triggered).  
   $ignorectl(GET <refnum> COUNTER)
   - Return the number of times the ignore has been used (triggered).

   $ignorectl(SET <refnum> NICK <ignore-pattern>)
   - Set the ignore-pattern for the ignore refnum.
     *** WARNING *** The ignore list is usually sorted, and changing this 
     value may de-sort the ignore list.  The result of this is uncertain and 
     could destabilize epic.  It is probably not a good idea to change an 
     ignore's pattern.  The ignore's refnum is returned.
   $ignorectl(SET <refnum> LEVELS <level-desc>)
   - Unconditionally set the ignore levels to <level-desc>.  All levels 
     previously in use are cleared and replaced with the new levels.  You 
     should prefix each level with one character to indicate it's disposition:
   	/<level>        Suppressive ignore
   	+<level>        Highlight ignore
   	^<level>        Exceptive ignore
     The ignore's refnum is returned.
   $ignorectl(SET <refnum> SUPPRESS <integer>)
   - Unconditionally set the integer value corresopnding to the suppressive 
     ignores for this ignore item.  *** WARNING *** The exact layout of this 
     value is version dependant on epic and may change in the future, so 
     changing this value directly like this could corrupt the ignore if you 
     don't know what version of epic you are using.  You Have Been Warned.
     The ignore's refnum is returned.
   $ignorectl(SET <refnum> EXCEPT <integer>)
   - Unconditionally set the integer value corresopnding to the exceptive 
     ignores for this ignore item.  See above warning The ignore's refnum is 
     returned.
   $ignorectl(SET <refnum> HIGHLIGHT <integer>)
   - Unconditionally set the integer value corresopnding to the highlighted 
     ignores for this ignore item.  See above warning The ignore's refnum is 
     returned.
   $ignorectl(SET <refnum> EXPIRATION <seconds> <milliseconds>)
   - Set the $utime() the ignore shall expire.  This is not an interval, but
     rather an absolute $utime() value.  If you set both values to 0, the 
     ignore will not expire.  The ignore's refnum is returned.
   $ignorectl(SET <refnum> REASON [reason])
   - Set the reason the user set the ignore.  The return value is the reason.
     If no reason is given, the ignore's reason is removed.  The ignore's
     refnum is returned.
   $ignorectl(SET <refnum> CREATION <seconds> <milliseconds>)
   - Set the $utime() the ignore was created.  Why would you want to change 
     this?  Well, whatever.  The ignore's refnum is returned.
   $ignorectl(SET <refnum> LAST_USED <seconds> <milliseconds>)
   - Set the $utime() the ignore was last used (triggered).  The ignore's
     refnum is returned.
   $ignorectl(SET <refnum> COUNTER <number>)
   - Set the number of times the ignore has been used (triggered).  This is 
     probably only useful if you want to reset it to 0 to see if an ignore 
     is still being triggered (or not).  The ignore's refnum is returned.

See Also:
   ignore(1)

History:
   The $ignore() function first appeared in EPIC4-1.1.13.
