Metadata-Version: 1.1
Name: stackfull
Version: 1.0.0
Summary: Tools for stack-usage in Python expressions
Home-page: https://github.com/jsbueno/stackfull
Author: João S. O. Bueno
Author-email: gwidion@gmail.com
License: License :: OSI Approved :: Python Software Foundation License
Description: PYTHON STACKFULL
        ================
        
        This small utility package provides functions to be used
        inside Python expressions that provide functionality
        like that available in stack-based languages
        (such as forth and postscript).
        
        It registers a hidden variable in the current
        running frame, which is a plain Python list -
        calls to plain "push, pop, dup, retr", etc...
        will just push/recover elements from that list.
        
        The intent is that whenever in an expression
        a value is complicated to retrieve - (or 
        computationally extensive) - instead of
        having to retrieve it in a previous line
        and storing said value in a variable,
        one gets the ability to "push" the value
        in this implicit stack - and retrieve it
        in another part of the same expression::
             
             `result = pop().upper() if not push(get_my+expensive_value()).isdigit() else pop()`
        
        For convenience, most functions return the valued passed
        to them in the first place (like the push above).
        
        
        Compatibility
        ==============
        As of version 0.20, and introduction of the `window`
        function, stackfull is no longer Python 2.x compatible.
        
        
        Available functions:
        ====================
        
        clear
        _____
        
            Clears the stack
        
        
        cleartomark
        ___________
        
            Clears the stack up to the special sentinel value
            MARK - this allows for clean-up of the stack after
            a block of code, preserving the older values.
            If the stack is not empty, returns the last value on the
            stack non destructively, else, MARK itself is returned.
        
        
        discard_if_false
        ________________
        
            Removes the last value in the stack if the expression is false.
            Made to be used in comprehensions, in the if part:
        
            Ex.:
            [pop().name for image in values if pop_if_false(push(image) is not None)]
        
        
        
        dup
        ___
        
            Dplicates the last value on the stack
            It also returns the value duplicated in a non-destructive way
        
        
        pop
        ___
        
            Pops the last value from the stack
        
        
        popclear
        ________
        
            Pops the last value from the stack, and clears the stack.
            This allows stackfull to be used inside generator expressions
            and comprehensions, using a 'push' in the filtering expression,
            and 'popclear' on the result expression.
        
        
        push
        ____
        
            Pushes a value into the stack, and returns the value itself
            Along with 'pop' and 'popclear' this is the heart of
            stackfull - as it allows an expensive function to be used
            in a 'if' or 'while' test, and still have its value
            available to use inside the defined block - without
            the need of an explicit auxiliar variable
        
        
        push_if_true
        ____________
        
            Returns the value itself, and Pushes a value into the stack, if it
            is truthy. Otherwise does not touch the stack.
            Nice to use inside  comprehensions
            in the "if" part: if the expession is not True, it is never pushed, and
            extraneous values don't pile up on the stack.
        
            Ex.:
            [pop().name for image in values if push_if_true(image)]
        
        
        
        retr
        ____
        
            Peeks the last value on the stack without consuming it
        
        
        roll
        ____
        
            Rolls the last 'items' values on the stack by
            'amount' positions, changing their order.
            Returns the value on the top of the stack after
            the changes in a non destructive way.
        
        
        stack
        _____
        
            Retrieves the stack as an ordinary Python list
            (which it actually is), allowing one to perform
            extra desired operations, such as 'len' or 'insert'
        
        
        window
        ______
        
            Pre-populates a frame stack with the seed values,
            and then iterates over the iterable -
        
            This allows one to use the stack with initial values in a simple way
            in a generator-expression context - like
        
            `fib = [push(stack()[-2] + stack()[-1]) for i in window(range(2, 10), 1,1)]`
        
        
        
        João S. O. Bueno <gwidion@gmail.com>
        
        
        Help on module stackfull:
        
        NAME
            stackfull - Stack expression utilities
        
        DESCRIPTION
            These functions use a "hidden" variable in the calling
            code frame context to hold a stack (a Python list)
            with values - the simple functionality here allow one
            have much of the functionality of stack
            based languages, like Postscript and Forth conveninently
            available to be used in any Python expression.
            
            
            (MAYBE) TODO: create a decorator which trasnform the operations here
            in real operations in the Python VM stack,
            by modifying the bytecode of calls to these utility functions into
            actual Python VM stack operations.
        
        FUNCTIONS
            clear()
                Clears the stack
            
            cleartomark()
                Clears the stack up to the special sentinel value
                MARK - this allows for clean-up of the stack after
                a block of code, preserving the older values.
                If the stack is not empty, returns the last value on the
                stack non destructively, else, MARK itself is returned.
            
            dup()
                Dplicates the last value on the stack
                It also returns the value duplicated in a non-destructive way
            
            pop()
                Pops the last value from the stack
            
            popclear()
                Pops the last value from the stack, and clears the stack.
                This allows stackfull to be used inside generator expressions
                and comprehensions, using a 'push' in the filtering expression,
                and 'popclear' on the result expression.
            
            push(value)
                Pushes a value into the stack, and returns the value itself
                Along with 'pop' and 'popclear' this is the heart of
                stackfull - as it allows an expensive function to be used
                in a 'if' or 'while' test, and still have its value
                available to use inside the defined block - without
                the need of an explicit auxiliar variable
            
            retr()
                Peeks the last value on the stack without consuming it
            
            roll(items, amount)
                Rolls the last 'items' values on the stack by
                'amount' positions, changing their order.
                Returns the value on the top of the stack after
                the changes in a non destructive way.
            
            stack()
                Retrieves the stack as an ordinary Python list
                (which it actually is), allowing one to perform
                extra desired operations, such as 'len' or 'insert'
        
        DATA
            MARK = <object object>
            SN = '.stackfull'
        
        FILE
            /home/gwidion/projetos/stackfull/stackfull.py
        
        
        
Keywords: python expressions stack acelerator utils push pop
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
