def as_Col(col, table=None):

    if col == None or isinstance(col, Code): return col

    else: return Col(col, table)

# Tells as_ValueCond() to assume a non-ValueCond is a literal value

assume_literal = object()

def as_ValueCond(value, default_table=assume_literal):

    if not isinstance(value, ValueCond):

        if default_table is not assume_literal:

            value = as_Col(value, default_table)

        return CompareCond(value)

join_using = object() # tells Join to join the column with USING

filter_out = object() # tells Join to filter out rows that match the join

class Join(Code):

    def __init__(self, table, mapping, type_=None):

        '''

        @param mapping dict(right_table_col=left_table_col, ...)

            * if left_table_col is join_using: left_table_col = right_table_col

        @param type_ None (for plain join)|str (e.g. 'LEFT')|filter_out

            * filter_out: equivalent to 'LEFT' with the query filtered by

              `table_pkey IS NULL` (indicating no match)

        '''

        if util.is_str(table): table = Table(table)

        assert type_ == None or util.is_str(type_) or type_ is filter_out

        self.table = table

        self.mapping = mapping

        self.type_ = type_

    def to_str(self, db, left_table):

        def join(entry):

            '''Parses non-USING joins'''

            right_table_col, left_table_col = entry

            # Parse special values

            if left_table_col is join_using: left_table_col = right_table_col

            cond = as_ValueCond(right_table_col, self.table)

            return cond.to_str(db, as_Col(left_table_col, left_table))

        # Create join condition and determine join type

        if reduce(operator.and_, (v is join_using for v in joins.itervalues())):

            # all cols w/ USING, so can use simpler USING syntax

            join_cond = 'USING ('+(', '.join(joins.iterkeys()))+')'

        else: join_cond = 'ON '+(' AND '.join(map(join, joins.iteritems())))

        # Create join

        type_ = self.type_

        if type_ is filter_out: type_ = 'LEFT'

        return type_+' JOIN '+table+' '+join_cond