mwxlib 1.0.0__py3-none-any.whl → 1.8.0__py3-none-any.whl

mwx/utilus.py

@@ -16,8 +16,7 @@ import fnmatch
 import pkgutil
 import pydoc
 import inspect
-from inspect import (isclass, ismodule, ismethod, isbuiltin,
-                     isfunction, isgenerator, isframe, iscode, istraceback)
+from inspect import isclass, ismodule, ismethod, isbuiltin, isfunction
 from pprint import pprint
 
 
@@ -37,20 +36,26 @@ def ignore(*category):
         yield
 
 
-def warn(message, category=None):
-    frame = inspect.currentframe().f_back # previous call stack frame
-    skip = [frame.f_code.co_filename]
-    stacklevel = 1
-    while frame.f_code.co_filename in skip:
-        frame = frame.f_back
-        if not frame:
-            break
-        stacklevel += 1
+def warn(message, category=None, stacklevel=None):
+    if stacklevel is None:
+        frame = inspect.currentframe().f_back  # previous call stack frame
+        skip = [frame.f_code.co_filename]
+        stacklevel = 1
+        while frame.f_code.co_filename in skip:
+            frame = frame.f_back
+            if not frame:
+                break
+            stacklevel += 1
     return warnings.warn(message, category, stacklevel+1)
 
 
 def atom(v):
-    return not hasattr(v, '__name__')
+    ## Not a class, method, function, module, or any type (class, int, str, etc.).
+    if (isclass(v) or ismethod(v) or isfunction(v) or isbuiltin(v)
+            or ismodule(v) or isinstance(v, type)):
+        return False
+    ## Include the case where __name__ is manually defined for a class instance.
+    return not hasattr(v, '__name__') or hasattr(v, '__class__')
 
 
 def isobject(v):
@@ -62,7 +67,7 @@ def instance(*types):
     ## return lambda v: isinstance(v, types)
     def _pred(v):
         return isinstance(v, types)
-    _pred.__name__ = str("instance<{}>".format(','.join(p.__name__ for p in types)))
+    _pred.__name__ = "instance<{}>".format(','.join(p.__name__ for p in types))
     return _pred
 
 
@@ -70,45 +75,45 @@ def subclass(*types):
     ## return lambda v: issubclass(v, types)
     def _pred(v):
         return issubclass(v, types)
-    _pred.__name__ = str("subclass<{}>".format(','.join(p.__name__ for p in types)))
+    _pred.__name__ = "subclass<{}>".format(','.join(p.__name__ for p in types))
     return _pred
 
 
 def _Not(p):
     ## return lambda v: not p(v)
-    if isinstance(p, type):
-        p = instance(p)
     def _pred(v):
         return not p(v)
-    _pred.__name__ = str("not {}".format(p.__name__))
+    if isinstance(p, type):
+        p = instance(p)
+    _pred.__name__ = "not {}".format(p.__name__)
     return _pred
 
 
 def _And(p, q):
     ## return lambda v: p(v) and q(v)
+    def _pred(v):
+        return p(v) and q(v)
     if isinstance(p, type):
         p = instance(p)
     if isinstance(q, type):
         q = instance(q)
-    def _pred(v):
-        return p(v) and q(v)
-    _pred.__name__ = str("{} and {}".format(p.__name__, q.__name__))
+    _pred.__name__ = "{} and {}".format(p.__name__, q.__name__)
     return _pred
 
 
 def _Or(p, q):
     ## return lambda v: p(v) or q(v)
+    def _pred(v):
+        return p(v) or q(v)
     if isinstance(p, type):
         p = instance(p)
     if isinstance(q, type):
         q = instance(q)
-    def _pred(v):
-        return p(v) or q(v)
-    _pred.__name__ = str("{} or {}".format(p.__name__, q.__name__))
+    _pred.__name__ = "{} or {}".format(p.__name__, q.__name__)
     return _pred
 
 
-def predicate(text, locals):
+def _Predicate(text, locals):
     tokens = [x for x in split_words(text.strip()) if not x.isspace()]
     j = 0
     while j < len(tokens):
@@ -138,11 +143,8 @@ def apropos(obj, rexpr='', ignorecase=True, alias=None, pred=None, locals=None):
     """
     name = alias or typename(obj)
     
-    rexpr = (rexpr.replace('\\a','[a-z0-9]')  #\a: identifier chars (custom rule)
-                  .replace('\\A','[A-Z0-9]')) #\A: 
-    
     if isinstance(pred, str):
-        pred = predicate(pred, locals)
+        pred = _Predicate(pred, locals)
     
     if isinstance(pred, type):
         pred = instance(pred)
@@ -161,9 +163,9 @@ def apropos(obj, rexpr='', ignorecase=True, alias=None, pred=None, locals=None):
         try:
             p = re.compile(rexpr, re.I if ignorecase else 0)
         except re.error as e:
-            print("- re:miss compilation:", e)
+            print("- re:miss compilation;", e)
         else:
-            keys = sorted(filter(p.search, dir(obj)), key=lambda s:s.upper())
+            keys = sorted(filter(p.search, dir(obj)), key=lambda s: s.upper())
             n = 0
             for key in keys:
                 try:
@@ -176,7 +178,7 @@ def apropos(obj, rexpr='', ignorecase=True, alias=None, pred=None, locals=None):
                 except Exception as e:
                     word = f"#<{e!r}>"
                 if len(word) > 80:
-                    word = word[:80] + '...' # truncate words +3 ellipsis
+                    word = word[:80] + '...'  # truncate words +3 ellipsis
                 print("    {}.{:<36s} {}".format(name, key, word))
             if pred:
                 print("found {} of {} words with :{}".format(n, len(keys), pred.__name__))
@@ -187,22 +189,26 @@ def apropos(obj, rexpr='', ignorecase=True, alias=None, pred=None, locals=None):
 def typename(obj, docp=False, qualp=True):
     """Formatted object type name.
     """
-    if hasattr(obj, '__name__'): # module, class, method, function, etc.
+    if not atom(obj):  # module, class, method, function, etc.
         if qualp:
             name = getattr(obj, '__qualname__', obj.__name__)
         else:
             name = obj.__name__
-    elif hasattr(obj, '__module__'): # atom -> module.class
+    elif hasattr(obj, '__class__'):  # class instance -> module.class
         name = obj.__class__.__name__
     else:
-        return pydoc.describe(obj) # atom -> short description
+        return pydoc.describe(obj)  # atom -> short description
     
     modname = getattr(obj, '__module__', None)
-    if modname and modname != "__main__" and not modname.startswith('mwx'):
-        name = modname + ('.' if qualp else '..') + name
+    if modname:
+        if qualp:
+            name = modname + '.' + name
+        else:
+            if not modname.startswith(("__main__", "mwx")):
+                name = modname + '..' + name
     
     if docp and callable(obj) and obj.__doc__:
-        name += "<{!r}>".format(obj.__doc__.splitlines()[0]) # concat the first doc line
+        name += "<{!r}>".format(obj.__doc__.splitlines()[0])  # concat the first doc line
     return name
 
 
@@ -227,8 +233,8 @@ def where(obj):
         name = obj.tb_frame.f_code.co_name
         return "{}:{}:{}".format(filename, lineno, name)
     
-    ## if inspect.isbuiltin(obj):
-    ##     return None
+    # if inspect.isbuiltin(obj):
+    #     return None
     
     def _where(obj):
         obj = inspect.unwrap(obj)
@@ -241,18 +247,18 @@ def where(obj):
     
     try:
         try:
-            return _where(obj) # module, class, method, function, frame, or code
+            return _where(obj)  # module, class, method, function, frame, or code
         except TypeError:
-            return _where(obj.__class__) # otherwise, class of the object
+            return _where(obj.__class__)  # otherwise, class of the object
     except Exception:
         pass
     ## The source code cannot be retrieved.
     ## Try to get filename where the object is defined.
     try:
         try:
-            return inspect.getfile(obj) # compiled file?
+            return inspect.getfile(obj)  # compiled file?
         except TypeError:
-            return inspect.getfile(obj.__class__) # or a special class?
+            return inspect.getfile(obj.__class__)  # or a special class?
     except Exception:
         pass
     
@@ -275,34 +281,50 @@ def mro(obj):
 def pp(obj):
     pprint(obj, **pp.__dict__)
 
-if pp:
-    pp.indent = 1
-    pp.width = 80 # default 80
-    pp.depth = None
-    if sys.version_info >= (3,6):
-        pp.compact = False
-    if sys.version_info >= (3,8):
-        pp.sort_dicts = True
+
+pp.indent = 1
+pp.width = 80  # default 80
+pp.depth = None
+pp.compact = False
+pp.sort_dicts = False
+
+
+## --------------------------------
+## Shell internal helper functions.
+## --------------------------------
+
+def fix_fnchars(filename, substr='_'):
+    """Replace invalid filename characters with substr."""
+    if os.name == 'nt':
+        ## Replace Windows-invalid chars [:*?"<>|] with substr.
+        ## Do not replace \\ or / to preserve folder structure.
+        return re.sub(r'[:*?"<>|]', substr, filename)
+    else:
+        return filename
 
 
-def split_paren(text, reverse=False):
-    """Split text into a head parenthesis and the rest, including the tail.
-    If reverse is True, search from tail to head.
+def split_words(text, reverse=False):
+    """Generates words (python phrase) extracted from text.
+    If reverse is True, process from tail to head.
     """
     tokens = list(split_tokens(text))
     if reverse:
         tokens = tokens[::-1]
-    words = _extract_paren_from_tokens(tokens, reverse)
-    paren = ''.join(reversed(words) if reverse else words)
-    rest = ''.join(reversed(tokens) if reverse else tokens)
-    if reverse:
-        return rest, paren
-    else:
-        return paren, rest
+    while tokens:
+        words = []
+        while 1:
+            word = _extract_words_from_tokens(tokens, reverse)
+            if not word:
+                break
+            words += word
+        if words:
+            yield ''.join(reversed(words) if reverse else words)
+        if tokens:
+            yield tokens.pop(0)  # sep-token
 
 
-def split_words(text, reverse=False):
-    """Generates words extracted from text.
+def split_parts(text, reverse=False):
+    """Generates portions (words and parens) extracted from text.
     If reverse is True, process from tail to head.
     """
     tokens = list(split_tokens(text))
@@ -313,7 +335,7 @@ def split_words(text, reverse=False):
         if words:
             yield ''.join(reversed(words) if reverse else words)
         else:
-            yield tokens.pop(0) # sep-token
+            yield tokens.pop(0)  # sep-token
 
 
 def split_tokens(text, comment=True):
@@ -326,17 +348,18 @@ def split_tokens(text, comment=True):
         j, k = 1, 0
         for type, string, start, end, line in tokens:
             l, m = start
-            if type in (0,5,6) or not string:
+            if type in (tokenize.INDENT, tokenize.DEDENT) or not string:
+                ## Empty strings such as NEWLINE and ENDMARKER are also skipped.
                 continue
-            if type == 61 and not comment:
-                token = next(tokens)  # eats a trailing token
-                string = token.string # cr/lf or ''
+            if type == tokenize.COMMENT and not comment:
+                token = next(tokens)   # eats a trailing token
+                string = token.string  # cr/lf or ''
                 if m == 0:
                     continue  # line starting with a comment
             if l > j and m > 0:
                 yield ' ' * m  # indent spaces
             elif m > k:
-                yield ' ' * (m-k) # white spaces
+                yield ' ' * (m-k)  # white spaces
             j, k = end
             yield string
     except tokenize.TokenError:
@@ -346,10 +369,6 @@ def split_tokens(text, comment=True):
 def _extract_words_from_tokens(tokens, reverse=False):
     """Extracts pythonic expressions from tokens.
     
-    Extraction continues until the parenthesis is closed
-    and the following token starts with a char in sep, where
-    the sep includes `@, ops, delims, and whitespaces, etc.
-    
     Returns:
         A token list extracted including the parenthesis.
         If reverse is True, the order of the tokens will be reversed.
@@ -361,53 +380,28 @@ def _extract_words_from_tokens(tokens, reverse=False):
     stack = []
     words = []
     for j, c in enumerate(tokens):
+        if not c:
+            continue
         if c in p:
             stack.append(c)
         elif c in q:
-            if not stack: # error("open-paren")
+            if not stack:  # error("open-paren")
                 break
-            if c != q[p.index(stack.pop())]: # error("mismatch-paren")
+            if c != q[p.index(stack.pop())]:  # error("mismatch-paren")
                 break
-        elif not stack and c[0] in sep: # ok; starts with a char in sep
+        elif not stack and c[0] in sep:  # ok; starts with a char in sep
             break
         words.append(c)
-    else: # if stack: error("unclosed-paren")
+        if not stack:  # ok
+            j += 1  # to remove current token
+            break
+    else:
+        # if stack: error("unclosed-paren")
         j = None
-    del tokens[:j] # remove extracted tokens (except the last one)
+    del tokens[:j]  # remove extracted tokens (except the last one)
     return words
 
 
-def _extract_paren_from_tokens(tokens, reverse=False):
-    """Extracts parenthesis from tokens.
-    
-    The first token must be a parenthesis.
-    Returns:
-        A token list extracted including the parenthesis,
-        or an empty list if the parenthesis is not closed.
-        If reverse is True, the order of the tokens will be reversed.
-    """
-    p, q = "({[", ")}]"
-    if reverse:
-        p, q = q, p
-    stack = []
-    words = []
-    for j, c in enumerate(tokens):
-        if c in p:
-            stack.append(c)
-        elif c in q:
-            if not stack: # error("open-paren")
-                break
-            if c != q[p.index(stack.pop())]: # error("mismatch-paren")
-                break
-        elif j == 0:
-            break # first char is not paren
-        words.append(c)
-        if not stack: # ok
-            del tokens[:j+1] # remove extracted tokens
-            return words
-    return [] # error("unclosed-paren")
-
-
 def walk_packages_no_import(path=None, prefix=''):
     """Yields module info recursively for all submodules on path.
     If path is None, yields all top-level modules on sys.path.
@@ -443,9 +437,9 @@ def find_modules(force=False, verbose=True):
     
     if not force and os.path.exists(fn):
         with open(fn, 'r') as o:
-            lm = eval(o.read()) # read and evaluate module list
+            lm = eval(o.read())  # read and evaluate module list
         
-        ## Check additional packages and modules
+        ## Check additional packages and modules.
         verbose = False
         for info in walk_packages_no_import(['.']):
             _callback('.', info.name)
@@ -464,7 +458,7 @@ def find_modules(force=False, verbose=True):
         
         lm.sort(key=str.upper)
         with open(fn, 'w') as o:
-            pprint(lm, stream=o) # write module list
+            pprint(lm, stream=o)  # write module list
         print("The results were written in {!r}.".format(fn))
     return lm
 
@@ -480,19 +474,19 @@ def get_rootpath(fn):
 
 
 ## --------------------------------
-## Finite State Machine
+## Finite State Machine.
 ## --------------------------------
 
 class SSM(dict):
-    """Single State Machine/Context of FSM
+    """Single State Machine/Context of FSM.
     """
     def __call__(self, event, *args, **kwargs):
         for act in self[event]:
             act(*args, **kwargs)
-    
+
     def __repr__(self):
         return "<{} object at 0x{:X}>".format(self.__class__.__name__, id(self))
-    
+
     def __str__(self):
         def _lstr(v):
             def _name(a):
@@ -501,7 +495,7 @@ class SSM(dict):
                 return repr(a)
             return ', '.join(_name(a) for a in v)
         return '\n'.join("{:>32} : {}".format(str(k), _lstr(v)) for k, v in self.items())
-    
+
     def bind(self, event, action=None):
         """Append a transaction to the context."""
         assert callable(action) or action is None
@@ -513,7 +507,7 @@ class SSM(dict):
         if action not in transaction:
             transaction.append(action)
         return action
-    
+
     def unbind(self, event, action=None):
         """Remove a transaction from the context."""
         assert callable(action) or action is None
@@ -530,7 +524,7 @@ class SSM(dict):
 
 
 class FSM(dict):
-    """Finite State Machine
+    """Finite State Machine.
     
     Args:
         contexts: map of context <DNA>
@@ -554,27 +548,28 @@ class FSM(dict):
         [8] +++ (max verbose level) to put all args and kwargs.
     
     Note:
-        A default=None is given as an argument of the init.
-        If there is only one state, that state will be the default.
+        default=None is given as an argument to ``__init__``.
+        If there is only one state, that state is used as the default.
     
     Note:
         There is no enter/exit event handler.
     """
     debug = 0
-    
-    default_state = None
+
+    default_state = None  # Used for define/undefine methods.
+
     current_state = property(lambda self: self.__state)
     previous_state = property(lambda self: self.__prev_state)
-    
+
     current_event = property(lambda self: self.__event)
     previous_event = property(lambda self: self.__prev_event)
-    
+
     @current_state.setter
     def current_state(self, state):
         self.__state = state
         self.__event = '*forced*'
         self.__debcall__(self.__event)
-    
+
     def clear(self, state):
         """Reset current and previous states."""
         self.__state = state
@@ -582,28 +577,28 @@ class FSM(dict):
         self.__event = None
         self.__prev_event = None
         self.__matched_pattern = None
-    
+
     def __init__(self, contexts=None, default=None):
-        dict.__init__(self) # update dict, however, it does not clear
-        dict.clear(self)    # if and when __init__ is called, all contents are cleared
+        dict.__init__(self)  # update dict, however, it does not clear
+        dict.clear(self)     # if and when __init__ is called, all contents are cleared
         if contexts is None:
             contexts = {}
-        if default is None: # if no default given, reset the first state as the default
+        if default is None:  # if no default given, reset the first state as the default
             if self.default_state is None:
                 default = next((k for k in contexts if k is not None), None)
         self.default_state = default
-        self.clear(default) # the first clear creates object localvars
+        self.clear(default)  # the first clear creates object localvars
         self.update(contexts)
-    
+
     def __missing__(self, key):
         raise Exception("FSM logic-error: undefined state {!r}".format(key))
-    
+
     def __repr__(self):
         return "<{} object at 0x{:X}>".format(self.__class__.__name__, id(self))
-    
+
     def __str__(self):
         return '\n'.join("[ {!r} ]\n{!s}".format(k, v) for k, v in self.items())
-    
+
     def __call__(self, event, *args, **kwargs):
         """Handle the event.
         
@@ -617,8 +612,8 @@ class FSM(dict):
             - process the event (no actions) -> []
             - no event:transaction -> None
         """
-        recept = False # Is transaction performed?
-        retvals = [] # retvals of actions
+        recept = False  # Is transaction performed?
+        retvals = []  # retvals of actions
         self.__event = event
         if None in self:
             org = self.__state
@@ -626,17 +621,17 @@ class FSM(dict):
             try:
                 self.__state = None
                 self.__prev_state = None
-                ret = self.call(event, *args, **kwargs) # None process
+                ret = self.call(event, *args, **kwargs)  # None process
                 if ret is not None:
                     recept = True
                     retvals += ret
             finally:
-                if self.__state is None: # restore original
+                if self.__state is None:  # restore original
                     self.__state = org
                     self.__prev_state = prev
         
         if self.__state is not None:
-            ret = self.call(event, *args, **kwargs) # normal process
+            ret = self.call(event, *args, **kwargs)  # normal process
             if ret is not None:
                 recept = True
                 retvals += ret
@@ -646,7 +641,7 @@ class FSM(dict):
         self.__prev_state = self.__state
         if recept:
             return retvals
-    
+
     def fork(self, event, *args, **kwargs):
         """Invoke the event handlers (internal use only).
         
@@ -657,7 +652,7 @@ class FSM(dict):
         ret = self.call(event, *args, **kwargs)
         self.__prev_event = self.__event
         return ret
-    
+
     def call(self, event, *args, **kwargs):
         """Invoke the event handlers (internal use only).
         
@@ -674,16 +669,16 @@ class FSM(dict):
         context = self[self.__state]
         if event in context:
             transaction = context[event]
-            self.__prev_state = self.__state # save previous state
-            self.__state = transaction[0]    # the state transits here
-            self.__debcall__(event, *args, **kwargs) # check after transition
+            self.__prev_state = self.__state  # save previous state
+            self.__state = transaction[0]     # the state transits here
+            self.__debcall__(event, *args, **kwargs)  # check after transition
             retvals = []
             for act in transaction[1:]:
                 ## Save the event before each action (for nested call).
                 if self.__matched_pattern is None:
                     self.__event = event
                 try:
-                    ret = act(*args, **kwargs) # call actions after transition
+                    ret = act(*args, **kwargs)  # call actions after transition
                     retvals.append(ret)
                 except BdbQuit:
                     pass
@@ -699,15 +694,15 @@ class FSM(dict):
             self.__matched_pattern = None
             return retvals
         
-        if isinstance(event, str): # matching test using fnmatch
+        if isinstance(event, str):  # matching test using fnmatch
             for pat in context:
                 if fnmatch.fnmatchcase(event, pat):
                     self.__matched_pattern = pat
-                    return self.call(pat, *args, **kwargs) # recursive call
+                    return self.call(pat, *args, **kwargs)  # recursive call
         
-        self.__debcall__(event, *args, **kwargs) # check when no transition
-        return None # no event, no action
-    
+        self.__debcall__(event, *args, **kwargs)  # check when no transition
+        return None  # no event, no action
+
     def __debcall__(self, pattern, *args, **kwargs):
         v = self.debug
         if v and self.__state is not None:
@@ -722,7 +717,7 @@ class FSM(dict):
                     a = '' if not actions else ('=> ' + actions),
                     c = '*' if self.__prev_state != self.__state else ' '))
         
-        elif v > 3: # state is None
+        elif v > 3:  # state is None
             transaction = self[None].get(pattern) or []
             actions = ', '.join(typename(a, qualp=0) for a in transaction[1:])
             if actions or v > 4:
@@ -730,13 +725,13 @@ class FSM(dict):
                     self.__event,
                     a = '' if not actions else ('=> ' + actions)))
         
-        if v > 7: # max verbose level puts all args
+        if v > 7:  # max verbose level puts all args
             self.log("\t:", args, kwargs)
-    
+
     @staticmethod
     def log(*args):
         print(*args, file=sys.__stdout__)
-    
+
     @staticmethod
     def dump(*args):
         fn = get_rootpath("deb-dump.log")
@@ -744,7 +739,7 @@ class FSM(dict):
             print(time.strftime('!!! %Y/%m/%d %H:%M:%S'), file=o)
             print(*args, traceback.format_exc(), sep='\n', file=o)
         print(*args, traceback.format_exc(), sep='\n', file=sys.__stderr__)
-    
+
     @staticmethod
     def duplicate(context):
         """Duplicate the transaction:list in the context.
@@ -752,63 +747,63 @@ class FSM(dict):
         This method is used for the contexts given to :append and :update
         so that the original transaction (if they are lists) is not removed.
         """
-        return {event:transaction[:] for event, transaction in context.items()}
-    
+        return {event: transaction[:] for event, transaction in context.items()}
+
     def validate(self, state):
         """Sort and move to end items with key which includes ``*?[]``."""
         context = self[state]
         ast = []
         bra = []
-        for event in list(context): # context mutates during iteration
+        for event in list(context):  # context mutates during iteration
             if re.search(r"\[.+\]", event):
-                bra.append((event, context.pop(event))) # event key has '[]'
+                bra.append((event, context.pop(event)))  # event key has '[]'
             elif '*' in event or '?' in event:
-                ast.append((event, context.pop(event))) # event key has '*?'
+                ast.append((event, context.pop(event)))  # event key has '*?'
         
-        temp = sorted(context.items()) # normal event key
+        temp = sorted(context.items())  # normal event key
         context.clear()
         context.update(temp)
         context.update(sorted(bra, reverse=1))
-        context.update(sorted(ast, reverse=1, key=lambda v:len(v[0])))
-    
+        context.update(sorted(ast, reverse=1, key=lambda v: len(v[0])))
+
     def update(self, contexts):
         """Update each context or Add new contexts."""
         for k, v in contexts.items():
             if k in self:
                 self[k].update(self.duplicate(v))
             else:
-                self[k] = SSM(self.duplicate(v)) # new context
+                self[k] = SSM(self.duplicate(v))  # new context
             self.validate(k)
-    
+
     def append(self, contexts):
         """Append new contexts."""
         for k, v in contexts.items():
             if k in self:
                 for event, transaction in v.items():
                     if event not in self[k]:
-                        self[k][event] = transaction[:] # copy the event:transaction
+                        self[k][event] = transaction[:]  # copy the event:transaction
                         continue
                     for act in transaction[1:]:
                         self.bind(event, act, k, transaction[0])
             else:
-                self[k] = SSM(self.duplicate(v)) # new context
+                self[k] = SSM(self.duplicate(v))  # new context
             self.validate(k)
-    
+
     def remove(self, contexts):
         """Remove old contexts."""
         for k, v in contexts.items():
             if k in self:
                 for event, transaction in v.items():
                     if self[k].get(event) == transaction:
-                        self[k].pop(event) # remove the event:transaction
+                        self[k].pop(event)  # remove the event:transaction
                         continue
                     for act in transaction[1:]:
                         self.unbind(event, act, k)
-        ## cleanup
-        for k, v in list(self.items()): # self mutates during iteration
+        ## Cleanup.
+        for k, v in list(self.items()):  # self mutates during iteration
             if not v:
                 del self[k]
-    
+
     def bind(self, event, action=None, state=None, state2=None):
         """Append a transaction to the context.
         
@@ -822,37 +817,39 @@ class FSM(dict):
         
         if state not in self:
             warn(f"- FSM [{state!r}] context newly created.")
-            self[state] = SSM() # new context
+            self[state] = SSM()  # new context
         
-        context = self[state]
         if state2 is None:
             state2 = state
         
+        context = self[state]
         if event in context:
             if state2 != context[event][0]:
                 warn(f"- FSM transaction may conflict ({event!r} : {state!r} --> {state2!r}).\n"
                      f"  The state {state2!r} is different from the original state.")
                 pass
-                context[event][0] = state2 # update transition
+                context[event][0] = state2  # update transition
         else:
             if state2 not in self:
                 warn(f"- FSM transaction may contradict ({event!r} : {state!r} --> {state2!r}).\n"
                      f"  The state {state2!r} is not found in the contexts.")
                 pass
-            context[event] = [state2] # new event:transaction
+            context[event] = [state2]  # new event:transaction
         
         transaction = context[event]
         if action is None:
             return lambda f: self.bind(event, f, state, state2)
         
-        if action not in transaction:
+        if action in transaction:
+            warn(f"- FSM duplicate transaction ({state!r} : {event!r}).")
+        else:
             try:
                 transaction.append(action)
             except AttributeError:
                 warn(f"- FSM cannot append new transaction ({state!r} : {event!r}).\n"
                      f"  The transaction must be a list, not a tuple.")
         return action
-    
+
     def unbind(self, event, action=None, state=None):
         """Remove a transaction from the context.
         
@@ -887,6 +884,41 @@ class FSM(dict):
                      f"  The transaction must be a list, not a tuple")
         return False
 
+    def binds(self, event, action=None, state=None, state2=None):
+        """Append a one-time transaction to the context.
+        
+        Like `bind`, but unbinds itself after being called once.
+        """
+        if action is None:
+            return lambda f: self.binds(event, f, state, state2)
+        
+        @wraps(action)
+        def _act(*v, **kw):
+            try:
+                return action(*v, **kw)
+            finally:
+                self.unbind(event, _act, state)
+        return self.bind(event, _act, state, state2)
+
+    def define(self, event, action=None, /, *args, **kwargs):
+        """Define event action.
+        
+        Note:
+            The funcall kwargs `doc` and `alias` are reserved as kw-only-args.
+        """
+        state = self.default_state
+        if action is None:
+            self[state].pop(event, None)  # cf. undefine
+            return lambda f: self.define(event, f, *args, **kwargs)
+        
+        f = funcall(action, *args, **kwargs)
+        self.update({state: {event: [state, f]}})
+        return action
+
+    def undefine(self, event):
+        """Delete event context."""
+        self.define(event, None)
+
 
 class TreeList:
     """Interface class for tree list control.
@@ -902,41 +934,41 @@ class TreeList:
     """
     def __init__(self, ls=None):
         self.__items = ls or []
-    
+
     def __call__(self, k):
         return TreeList(self[k])
-    
+
     def __len__(self):
         return len(self.__items)
-    
+
     def __contains__(self, k):
         return self._getf(self.__items, k)
-    
+
     def __iter__(self):
         return self.__items.__iter__()
-    
+
     def __getitem__(self, k):
         if isinstance(k, str):
             return self._getf(self.__items, k)
         return self.__items.__getitem__(k)
-    
+
     def __setitem__(self, k, v):
         if isinstance(k, str):
             return self._setf(self.__items, k, v)
         return self.__items.__setitem__(k, v)
-    
+
     def __delitem__(self, k):
         if isinstance(k, str):
             return self._delf(self.__items, k)
         return self.__items.__delitem__(k)
-    
+
     def _find_item(self, ls, key):
         for x in ls:
             if isinstance(x, (tuple, list)) and x and x[0] == key:
                 if len(x) < 2:
                     raise ValueError(f"No value for {key=!r}")
                 return x
-    
+
     def _getf(self, ls, key):
         if '/' in key:
             a, b = key.split('/', 1)
@@ -947,7 +979,7 @@ class TreeList:
         li = self._find_item(ls, key)
         if li is not None:
             return li[-1]
-    
+
     def _setf(self, ls, key, value):
         if '/' in key:
             a, b = key.split('/', 1)
@@ -955,19 +987,19 @@ class TreeList:
             if la is not None:
                 return self._setf(la, b, value)
             p, key = key.rsplit('/', 1)
-            return self._setf(ls, p, [[key, value]]) # ls[p].append([key, value])
+            return self._setf(ls, p, [[key, value]])  # ls[p].append([key, value])
         try:
             li = self._find_item(ls, key)
             if li is not None:
                 try:
-                    li[-1] = value # assign value to item (ls must be a list)
+                    li[-1] = value  # assign value to item (ls must be a list)
                 except TypeError:
-                    li[-1][:] = value # assign value to items:list
+                    li[-1][:] = value  # assign value to items:list
             else:
-                ls.append([key, value]) # append to items:list
+                ls.append([key, value])  # append to items:list
         except (ValueError, TypeError, AttributeError) as e:
             warn(f"- TreeList {e!r}: {key=!r}")
-    
+
     def _delf(self, ls, key):
         if '/' in key:
             p, key = key.rsplit('/', 1)
@@ -976,26 +1008,44 @@ class TreeList:
 
 
 def get_fullargspec(f):
-    argv = []
-    defaults = {}
-    varargs = None
-    varkwargs = None
-    kwonlyargs = []
+    """Get the names and default values of a callable object's parameters.
+    If the object is a built-in function, it tries to get argument
+    information from the docstring. If it fails, it returns None.
+    
+    Returns:
+        args:           a list of the parameter names.
+        varargs:        the name of the  * parameter or None.
+        varkwargs:      the name of the ** parameter or None.
+        defaults:       a dict mapping names from args to defaults.
+        kwonlyargs:     a list of keyword-only parameter names.
+        kwonlydefaults: a dict mapping names from kwonlyargs to defaults.
+    
+    Note:
+        `self` parameter is not reported for bound methods.
+    
+    cf. inspect.getfullargspec
+    """
+    argv = []           # <before /> 0:POSITIONAL_ONLY
+                        # <before *> 1:POSITIONAL_OR_KEYWORD
+    varargs = None      # <*args>    2:VAR_POSITIONAL
+    varkwargs = None    # <**kwargs> 4:VAR_KEYWORD
+    defaults = {}       # 
+    kwonlyargs = []     # <after *>  3:KEYWORD_ONLY
     kwonlydefaults = {}
     try:
         sig = inspect.signature(f)
         for k, v in sig.parameters.items():
-            if v.kind <= 1: # POSITIONAL_ONLY / POSITIONAL_OR_KEYWORD
+            if v.kind in (v.POSITIONAL_ONLY, v.POSITIONAL_OR_KEYWORD):
                 argv.append(k)
                 if v.default != v.empty:
                     defaults[k] = v.default
-            elif v.kind == 2: # VAR_POSITIONAL (*args)
+            elif v.kind == v.VAR_POSITIONAL:
                 varargs = k
-            elif v.kind == 3: # KEYWORD_ONLY
+            elif v.kind == v.KEYWORD_ONLY:
                 kwonlyargs.append(k)
                 if v.default != v.empty:
                     kwonlydefaults[k] = v.default
-            elif v.kind == 4: # VAR_KEYWORD (**kwargs)
+            elif v.kind == v.VAR_KEYWORD:
                 varkwargs = k
     except ValueError:
         ## Builtin functions don't have an argspec that we can get.
@@ -1006,25 +1056,39 @@ def get_fullargspec(f):
         ## 
         ## ...(details)...
         ## ```
-        docs = [ln for ln in inspect.getdoc(f).splitlines() if ln]
-        m = re.search(r"(\w+)\((.*)\)", docs[0])
-        if m:
-            ## Note: Cannot process args containing commas.
-            ## e.g., v='Hello, world"
-            name, argspec = m.groups()
-            for v in argspec.strip().split(','):
-                m = re.search(r"(\w+)", v)
+        doc = inspect.getdoc(f)
+        for word in split_parts(doc or ''):  # Search pattern for `func(argspec)`.
+            if word.startswith('('):
+                argspec = word[1:-1]
+                break
+        else:
+            return None  # no argument spec information
+        if argspec:
+            argparts = ['']
+            for part in split_parts(argspec):  # Separate argument parts with commas.
+                if not part.strip():
+                    continue
+                if part != ',':
+                    argparts[-1] += part
+                else:
+                    argparts.append('')
+            for v in argparts:
+                m = re.match(r"(\w+):?", v)  # argv + kwonlyargs
                 if m:
                     argv.append(m.group(1))
-            defaults = dict(re.findall(r"(\w+)\s*=\s*([\w' ]+)", argspec))
-        else:
-            return None
+                    m = re.match(r"(\w+)(?::\w+)?=(.+)", v)  # defaults + kwonlydefaults
+                    if m:
+                        defaults.update([m.groups()])
+                elif v.startswith('**'):  # <**kwargs>
+                    varkwargs = v[2:]
+                elif v.startswith('*'):  # <*args>
+                    varargs = v[1:]
     return (argv, varargs, varkwargs,
             defaults, kwonlyargs, kwonlydefaults)
 
 
 def funcall(f, *args, doc=None, alias=None, **kwargs):
-    """Decorator of event handler
+    """Decorator of event handler.
     
     Check if the event argument can be omitted and if any other
     required arguments are specified in args and kwargs.
@@ -1035,10 +1099,10 @@ def funcall(f, *args, doc=None, alias=None, **kwargs):
         >>> Act1 = lambda *v,**kw: f(*(v+args), **(kwargs|kw))
         >>> Act2 = lambda *v,**kw: f(*args, **(kwargs|kw))
         
-        Returns Act1 (accepts event arguments) if event arguments
+        `Act1` is returned (accepts event arguments) if event arguments
         cannot be omitted or if there are any remaining arguments
         that must be explicitly specified.
-        Otherwise, returns Act2 (ignores event arguments).
+        Otherwise, `Act2` is returned (ignores event arguments).
     """
     assert callable(f)
     assert isinstance(doc, (str, type(None)))
@@ -1047,18 +1111,19 @@ def funcall(f, *args, doc=None, alias=None, **kwargs):
     @wraps(f)
     def _Act(*v, **kw):
         kwargs.update(kw)
-        return f(*v, *args, **kwargs) # function with event args
+        return f(*v, *args, **kwargs)  # function with event args
     
     @wraps(f)
     def _Act2(*v, **kw):
         kwargs.update(kw)
-        return f(*args, **kwargs) # function with no explicit args
+        return f(*args, **kwargs)  # function with no explicit args
     
     action = _Act
     try:
         (argv, varargs, varkwargs, defaults,
             kwonlyargs, kwonlydefaults) = get_fullargspec(f)
     except Exception:
+        warn(f"Failed to get the signature of {f}.")
         return f
     if not varargs:
         N = len(argv)