Commits

Kirill Simonov committed bcb7074

Refactoring signatures; documenting functions.

Comments (0)

Files changed (2)

src/htsql/tr/fn/bind.py

 from ..error import BindError
 from ..coerce import coerce
 from ..lookup import lookup
-from .signature import (Signature, UnarySig, BinarySig, ThisSig, RootSig,
+from .signature import (Signature, NullarySig, UnarySig, BinarySig,
                         FiberSig, AsSig, SortDirectionSig, LimitSig,
-                        SortSig, NullSig, TrueSig, FalseSig, CastSig,
-                        MakeDateSig, ExtractYearSig, ExtractMonthSig,
-                        ExtractDaySig,
+                        SortSig, CastSig, MakeDateSig, ExtractYearSig,
+                        ExtractMonthSig, ExtractDaySig,
                         IsEqualSig, IsInSig, IsTotallyEqualSig, AndSig, OrSig,
                         NotSig, CompareSig, AddSig, ConcatenateSig,
                         HeadSig, TailSig, SliceSig, AtSig, ReplaceSig,
         return correlate()
 
 
+class BindNull(BindMacro):
 
+    named('null')
+    signature = NullarySig
+    hint = """null() -> NULL"""
 
+    def expand(self):
+        yield LiteralBinding(None, UntypedDomain(), self.syntax)
 
 
+class BindTrue(BindMacro):
 
+    named('true')
+    signature = NullarySig
+    hint = """true() -> TRUE"""
 
+    def expand(self):
+        yield LiteralBinding(True, coerce(BooleanDomain()), self.syntax)
+
+
+class BindFalse(BindMacro):
+
+    named('false')
+    signature = NullarySig
+    hint = """false() -> FALSE"""
+
+    def expand(self):
+        yield LiteralBinding(False, coerce(BooleanDomain()), self.syntax)
 
 
 class BindRoot(BindMacro):
 
     named('root')
-    signature = RootSig
+    signature = NullarySig
+    hint = """base.root() -> the root space"""
 
     def expand(self):
         yield WrapperBinding(self.state.root, self.syntax)
 class BindThis(BindMacro):
 
     named('this')
-    signature = ThisSig
+    signature = NullarySig
+    hint = """base.this() -> the current base space"""
 
     def expand(self):
         yield WrapperBinding(self.state.base, self.syntax)
 
     named('fiber')
     signature = FiberSig
+    hint = """base.fiber(T[, img][, cimg]) -> fiber product of base and T"""
 
     def expand(self, table, image=None, counterimage=None):
         if not isinstance(table, IdentifierSyntax):
 
     named('as')
     signature = AsSig
+    hint = """as(expr, title) -> expression with a title"""
+    help = """
+    Decorates an expression with a title.
+
+    `expr`: an arbitrary expression.
+    `title`: an identifier or a string literal.
+    """
 
     def expand(self, base, title):
         if not isinstance(title, (StringSyntax, IdentifierSyntax)):
 
     named('_+')
     direction = +1
+    hint = """(expr +) -> sort in ascending order"""
+    help = """
+    Decorates an expression with a sort order indicator.
+    """
 
 
 class BindDescDir(BindDirectionBase):
 
     named('_-')
     direction = -1
+    hint = """(expr -) -> sort in descending order"""
 
 
 class BindLimit(BindMacro):
 
     named('limit')
     signature = LimitSig
+    hint = """base.limit(N[, skip]) -> slice of the base space"""
 
     def parse(self, argument):
         try:
 
     named('sort')
     signature = SortSig
+    hint = """base.sort(expr[, ...]) -> sorted space"""
 
     def expand(self, order):
         bindings = []
         yield SortBinding(self.state.base, bindings, None, None, self.syntax)
 
 
-class BindNull(BindMacro):
-
-    named('null')
-    signature = NullSig
-
-    def expand(self):
-        yield LiteralBinding(None, UntypedDomain(), self.syntax)
-
-
-class BindTrue(BindMacro):
-
-    named('true')
-    signature = TrueSig
-
-    def expand(self):
-        yield LiteralBinding(True, coerce(BooleanDomain()), self.syntax)
-
-
-class BindFalse(BindMacro):
-
-    named('false')
-    signature = FalseSig
-
-    def expand(self):
-        yield LiteralBinding(False, coerce(BooleanDomain()), self.syntax)
-
-
 class BindCast(BindFunction):
 
     signature = CastSig
 
 class BindBooleanCast(BindCast):
 
-    named('boolean')
+    named('boolean', 'bool')
     codomain = BooleanDomain()
+    hint = """boolean(expr) -> expression converted to Boolean"""
 
 
 class BindStringCast(BindCast):
 
-    named('string')
+    named('string', 'str')
     codomain = StringDomain()
+    hint = """string(expr) -> expression converted to a string"""
 
 
 class BindIntegerCast(BindCast):
 
-    named('integer')
+    named('integer', 'int')
     codomain = IntegerDomain()
+    hint = """integer(expr) -> expression converted to integer"""
 
 
 class BindDecimalCast(BindCast):
 
-    named('decimal')
+    named('decimal', 'dec')
     codomain = DecimalDomain()
+    hint = """decimal(expr) -> expression converted to decimal"""
 
 
 class BindFloatCast(BindCast):
 
     named('float')
     codomain = FloatDomain()
+    hint = """float(expr) -> expression converted to float"""
 
 
 class BindDateCast(BindCast):
 
     named('date')
     codomain = DateDomain()
+    hint = """date(expr) -> expression converted to date"""
 
 
 class BindMakeDate(BindMonoFunction):
     signature = MakeDateSig
     domains = [IntegerDomain(), IntegerDomain(), IntegerDomain()]
     codomain = DateDomain()
+    hint = """date(year, month, day) -> date value"""
 
 
 class BindAmongBase(BindFunction):
 
     named('=')
     polarity = +1
+    hint = """(x = y) -> TRUE if x is equal to y"""
 
 
 class BindNotAmong(BindAmongBase):
 
     named('!=')
     polarity = -1
+    hint = """(x != y) -> TRUE if x is not equal to y"""
 
 
 class BindTotallyEqualBase(BindFunction):
 
     named('==')
     polarity = +1
+    hint = """(x == y) -> TRUE if x is equal to y"""
 
 
 class BindTotallyNotEqual(BindTotallyEqualBase):
 
     named('!==')
     polarity = -1
+    hint = """(x !== y) -> TRUE if x is not equal to y"""
 
 
 class BindAnd(BindFunction):
 
     named('&')
     signature = BinarySig
+    hint = """(p & q) -> TRUE if both p and q are TRUE"""
 
     def correlate(self, lop, rop):
         domain = coerce(BooleanDomain())
 
     named('|')
     signature = BinarySig
+    hint = """(p | q) -> TRUE if either p or q is TRUE"""
 
     def correlate(self, lop, rop):
         domain = coerce(BooleanDomain())
 
     named('!_')
     signature = NotSig
+    hint = """(! p) -> TRUE if p is FALSE"""
 
     def correlate(self, op):
         domain = coerce(BooleanDomain())
 
     named('<')
     relation = '<'
+    hint = """(x < y) -> TRUE if x is less than y"""
 
 
 class BindLessThanOrEqual(BindCompare):
 
     named('<=')
     relation = '<='
+    hint = """(x < y) -> TRUE if x is less than or equal to y"""
 
 
 class BindGreaterThan(BindCompare):
 
     named('>')
     relation = '>'
+    hint = """(x > y) -> TRUE if x is greater than y"""
 
 
 class BindGreaterThanOrEqual(BindCompare):
 
     named('>=')
     relation = '>='
+    hint = """(x >= y) -> TRUE if x is greater than or equal to y"""
 
 
 class Comparable(Adapter):
 
     named('+')
     signature = AddSig
+    hint = """(x + y) -> sum of x and y"""
 
 
 class CorrelateIntegerAdd(CorrelateFunction):
 
     named('-')
     signature = SubtractSig
+    hint = """(x - y) -> difference between x and y"""
 
 
 class CorrelateIntegerSubtract(CorrelateFunction):
 
     named('*')
     signature = MultiplySig
+    hint = """(x * y) -> product of x and y"""
 
 
 class CorrelateIntegerMultiply(CorrelateFunction):
 
     named('/')
     signature = DivideSig
+    hint = """(x / y) -> quotient of x divided by y"""
 
 
 class CorrelateDecimalDivide(CorrelateFunction):
 
     named('+_')
     signature = KeepPolaritySig
+    hint = """(+ x) -> x"""
 
 
 class CorrelateIntegerKeepPolarity(CorrelateFunction):
 
     named('-_')
     signature = ReversePolaritySig
+    hint = """(- x) -> negation of x"""
 
 
 class CorrelateIntegerReversePolarity(CorrelateFunction):
 
     named('round')
     signature = RoundSig
+    hint = """round(x) -> x rounded to zero"""
 
 
 class CorrelateDecimalRound(CorrelateFunction):
 
     named(('round', 2))
     signature = RoundToSig
+    hint = """round(x, n) -> x rounded to a given precision"""
 
 
 class CorrelateDecimalRoundTo(CorrelateFunction):
 
     named('length')
     signature = LengthSig
+    hint = """length(s) -> length of s"""
 
 
 class CorrelateStringLength(CorrelateFunction):
 
     named('~')
     polarity = +1
+    hint = """(s ~ sub) -> TRUE if s contains sub"""
 
 
 class BindNotContains(BindContainsBase):
 
     named('!~')
     polarity = -1
+    hint = """(s !~ sub) -> TRUE if s does not contain sub"""
 
 
 class CorrelateStringContains(CorrelateFunction):
 
     named('head')
     signature = HeadSig
+    hint = """head(s[, N=1]) -> the first N elements of s"""
 
 
 class BindTail(BindPolyFunction):
 
     named('tail')
     signature = TailSig
+    hint = """tail(s[, N=1]) -> the last N elements of s"""
 
 
 class CorrelateHead(CorrelateFunction):
 
     named('slice')
     signature = SliceSig
+    hint = """slice(s, i, j) -> slice of s from i-th to j-th elements"""
 
     def correlate(self, op, left, right):
         if left is not None:
 
     named('at')
     signature = AtSig
+    hint = """at(s, i[, len=1]) -> i-th to (i+len)-th elements of s"""
 
     def correlate(self, op, index, length):
         index = CastBinding(index, coerce(IntegerDomain()), index.syntax)
 
     named('replace')
     signature = ReplaceSig
+    hint = """replace(s, o, n) -> s with occurences of o replaced by n"""
 
 
 class CorrelateReplace(CorrelateFunction):
 
     named('upper')
     signature = UpperSig
+    hint = """upper(s) -> s converted to uppercase"""
 
 
 class CorrelateUpper(CorrelateFunction):
 
     named('lower')
     signature = LowerSig
+    hint = """lower(s) -> s converted to lowercase"""
 
 
 class CorrelateLower(CorrelateFunction):
     named('trim')
     is_left = True
     is_right = True
+    hint = """trim(s) -> s with leading and trailing whitespaces removed"""
 
 
 class BindLTrim(BindTrimBase):
 
     named('ltrim')
     is_left = True
+    hint = """ltrim(s) -> s with leading whitespaces removed"""
 
 
 class BindRTrim(BindTrimBase):
 
     named('rtrim')
     is_right = True
+    hint = """rtrim(s) -> s with trailing whitespaces removed"""
 
 
 class BindToday(BindMonoFunction):
     named('today')
     signature = TodaySig
     codomain = DateDomain()
+    hint = """today() -> the current date"""
 
 
 class BindExtractYear(BindPolyFunction):
 
     named('year')
     signature = ExtractYearSig
+    hint = """year(date) -> the year of a given date"""
 
 
 class BindExtractMonth(BindPolyFunction):
 
     named('month')
     signature = ExtractMonthSig
+    hint = """month(date) -> the month of a given date"""
 
 
 class BindExtractDay(BindPolyFunction):
 
     named('day')
     signature = ExtractDaySig
+    hint = """day(date) -> the day of a given date"""
 
 
 class CorrelateExtractYear(CorrelateFunction):
     named('is_null')
     signature = IsNullSig(+1)
     codomain = BooleanDomain()
+    hint = """is_null(x) -> TRUE if x is NULL"""
 
 
 class BindNullIf(BindHomoFunction):
 
     named('null_if')
     signature = NullIfSig()
+    hint = """null_if(x, y) -> NULL if x is equal to y; x otherwise"""
 
 
 class BindIfNull(BindHomoFunction):
 
     named('if_null')
     signature = IfNullSig()
+    hint = """if_null(x, y) -> y if x is NULL; x otherwise"""
 
 
 class BindIf(BindFunction):
 
     named('if')
     signature = IfSig
+    hint = """if(p, c[, ...][, a=NULL]) -> c if p; a otherwise"""
 
     def match(self):
         operands = list(reversed(self.syntax.arguments))
 
     named('switch')
     signature = SwitchSig
+    hint = """switch(x, v, c, [...][, a=NULL]) -> c if x = v; a otherwise"""
 
     def match(self):
         operands = list(reversed(self.syntax.arguments))
 
     named('exists')
     polarity = +1
+    hint = """base.exists(p) -> TRUE if there exists p such that p = TRUE"""
 
 
 class BindEvery(BindExistsBase):
 
     named('every')
     polarity = -1
+    hint = """base.every(p) -> TRUE if p = TRUE for every p"""
 
 
 class BindCount(BindFunction):
 
     named('count')
     signature = CountSig
+    hint = """base.count(p) -> the number of p such that p = TRUE"""
 
     def correlate(self, op):
         op = CastBinding(op, coerce(BooleanDomain()), op.syntax)
     named('min')
     signature = MinMaxSig
     polarity = +1
+    hint = """base.min(x) -> the minimal value in the set of x"""
 
 
 class BindMinMaxBase(BindMinMaxBase):
     named('max')
     signature = MinMaxSig
     polarity = -1
+    hint = """base.avg(x) -> the maximal value in the set of x"""
 
 
 class CorrelateIntegerMinMax(CorrelateAggregate):
 
     named('sum')
     signature = SumSig
+    hint = """base.sum(x) -> the sum of x"""
 
 
 class CorrelateIntegerSum(CorrelateAggregate):
 
     named('avg')
     signature = AvgSig
+    hint = """base.avg(x) -> the average value of x"""
 
 
 class CorrelateDecimalAvg(CorrelateAggregate):

src/htsql/tr/fn/signature.py

                          IfNullSig, NullIfSig, AndSig, OrSig, NotSig)
 
 
-class ThisSig(Signature):
-    pass
-
-
-class RootSig(Signature):
-    pass
-
-
 class FiberSig(Signature):
 
     slots = [
     ]
 
 
-class NullSig(Signature):
-    pass
-
-
-class TrueSig(Signature):
-    pass
-
-
-class FalseSig(Signature):
-    pass
-
-
 class CastSig(Signature):
 
     slots = [