You can use them as thousands separators.
This change differs from PEP 515 in that not only does it allow commas in addition to underscores, but it's much more liberal about placement. Any number of underscores or commas can be placed anywhere, even at the start.
Unlike Python, Hy allows the programmer to intermingle positional and keyword arguments. This change removes an exception to that rule for method calls, in which the method callee always had to be the first thing after the method. Thus, `(.split :sep "o" "foo")` now compiles to `"foo".split(sep="o")` instead of `HyKeyword("sep").split("o", "foo")`.
I don't see why you'd put this in the standard library. I guess it could be useful for when you're maintaining a library and you want to change the name of a function or macro but keep the old name around for a while so people's code doesn't break immediately. But that's a pretty limited purpose.
* Add comp, constantly and complement
relates #1176
* Fix composition order in comp
* comp without parameters returns identity
* Doc edits for comp, complement, constantly
* Test that `(comp)` returns `identity` exactly
* Simplify the `reduce` call in `comp`
* updated version of comp
I have some macros for using pandas and NumPy that expect : to be a keyword instead of an ordinary symbol. These tests will ensure that we don't break this unless we want to.
* added defmacro!
* revert #924#924 had an error and should never have been merged in the first place. (see #903)
* put back import getargspec
Without the `formatargspec` this time.
* Give better error message on failed macro expansion
Better error messages work most of the time. In cases where there are
parameters that aren't valid in Python, error message shown is rather
ugly. But this is better than no error messages at all and such
macros with strange parameter names are rather rare.
* fix flake8 errors
* Minor English improvements
Per the straw poll in #908, as an alternative to #1147.
Now you must use `True`, `False`, and `None`, as in Python. Or just assign `true` to `True`, etc.; the old synonyms aren't reserved words anymore.
In Python 2.x (range 10) is mapped to xrange(10) in Python
terms. However, xrange doesn't support slicing, which caused tests to
fail. By forxing xrange into list, we have slicing available.
Give `require` the same features as `import`
You can now do (require foo), (require [foo [a b c]]), (require [foo [*]]), and (require [foo :as bar]). The first and last forms get you macros named foo.a, foo.b, etc. or bar.a, bar.b, etc., respectively. The second form only gets the macros in the list.
Implements #1118 and perhaps partly addresses #277.
N.B. The new meaning of (require foo) will cause all existing code that uses macros to break. Simply replace these forms with (require [foo [*]]) to get your code working again.
There's a bit of a hack involved in the forms (require foo) or (require [foo :as bar]). When you call (foo.a ...) or (bar.a ...), Hy doesn't actually look inside modules. Instead, these (require ...) forms give the macros names that have periods in them, which happens to work fine with the way Hy finds and interprets macro calls.
* Make `require` syntax stricter and add tests
* Update documentation for `require`
* Documentation wording improvements
* Allow :as in `require` name lists
This allows them to be used with numeric types that aren't built in, such as NumPy arrays. Because Python uses duck typing, there's generally no way to know in advance whether a given value will accept a given operator. Of course, things like `(inc "hello")` will still raise a `TypeError`, because so does `(+ "hello" 1)`.
This allows macros to take a keyword dict containing useful things by
defining a keyword argument. This allows us to pass in new objects
which might be handy to have in macros.
This changeset refactors module_name to become `compiler`, so that we
can pass the compiler itself into the macros as `opts['compiler']`.
This allows the macro to both get the macro name
(`compiler.module_name`), as well as use the compiler to build AST.
In the future, this will enable us to create "super-macros" which return
AST, not HyAST, in order to manually create insane things from userland.
For userland macros (not `defmacro`) the core.language `macroexpand`
will go ahead and make a new compiler for you.
This makes it possible to use strings as the macro name argument to
defreader, which in turn makes it possible to define reader macros with
names that would otherwise result in parse errors.
Such as `#.`.
This fixes#918.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
The `if` form now supports elif clauses.
It works like `cond` but without the implicit `do`.
The old `if` is now `if*`
variadic lif now supports "ellif" clauses.
Update if-no-waste compiler to use `if*` properly.
(Sometimes one character is all it takes.)
document if
reword truthiness
Comparison operators such as =, !=, <, >, <=, >= should support a
one-arity version too, and return true in those cases (except for !=,
which returns false).
This closes#949.
Reported-by: Matthew Egan Odendahl
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This changes with syntax from (with [[x (expr)] (expr)] ...) to (with
[x (expr) (expr)] ...). Should have no ill side effects apart from the
syntax change.
Closes#852.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This changes let to use a flat list of symbol-value pairs instead of a
vector of vectors. One side effect is that (let [[a 1] z]) is not
expressible now, and one will explicitly need to set a nil value for z,
such as: (let [a 1 z nil]).
Closes#713.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
apply now mangles strings and keywords according to the Hy mangling
rules (by using the same function, now imported from
hy.lex.parser). With this change, if the dict passed to apply has
keywords, strings or quoted symbols, they'll get mangled, to turn them
into proper keys.
This only works for the cases where the keys are directly in the apply
params. A previously deffed dict, or key through a variable will not be
mangled.
This closes#219.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
To make it easier to write --init-- functions, defclass will now check
any (setv) expressions (and its property list), to find any --init--
declarations, and append a nil to the end.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
For easier macro writing purposes, allow an empty (cond), that simply
returns nil. Closes#904.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
To mirror the behaviour of (setv), allow an empty (del) too: one that
shall return nil. Closes#905.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
To allow classes to have methods that match built-in names, yet, still
disallow them outside of defclass, keep an internal state whether
builtins are allowed in the current context.
By default, this is false. But defclass will set it to True when it
compiles its body, and set it back to the previous value when it's done
with that. We need to set back to the previous value to allow nested
defclasses to work properly.
This closes#783.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Strip the \ufdd0 prefix from the keyword argument before turning it into
a string: the same representation the user entered looks better, and is
printable too, thus Python2 doesn't choke on it.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Some valid-looking list comprehensions, such as (genexpr x []) can crash
Python 2.7. The AST we generate from these cannot be expressed in
Python, but were valid in Hy.
Added two guards to guard against this, so we raise an error instead of
crashing Python.
Closes#572, #591 and #634.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Postfixing functions with a bang, like set!, get!, etc are relatively
common. However, those names are not valid in python, so in the name of
python interoperability, lets mangle them to set_bang and get_bang,
respectively.
Closes#536.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
When trying to setv a callable, raise an error instead of showing the
user an incredibly ugly backtrace. Closes#532.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
In case for doesn't get a body, raise the appropriate, descriptive error
instead of an IndexOutOfBounds one. Also updated the failing test case.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
defclass now has a new syntax:
(defclass Name [BaseList]
[property value
property value] ;; optional
(defn method [self]
self.property))
Anything after the optional property list (which will be translated to a
setv within the class context) will be added to the class body. This
allows one to have side effects and complex expressions within the class
definition.
As a side effect, defining methods is much more friendly now!
Closes#850.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
xor with more than two input parameters is not well defined and people
have different expectations on how it should behave. Avoid confusion by
sticking with two parameters only.
Added xor to complement and, or, not operators. Standard python
falsey/truthy semantics are followed. This implementation works for
two or more parameters.
The `with-decorator` special form is not the most ergonomic—this commit
introduces a new builtin `#@` reader macro that expands to an invocation
of `with-decorator`. To support this, `reader_macroexpand` is made to
also look in the default `None` namespace, in imitation of how
regular (non-reader) macros defined in hy.core are looked up. The
docstring of `hy.macros.reader` is also edited slightly for accuracy.
This in the matter of issue #856.
Much like how `can_compile` returns the compilation result, which some
tests make use of, it may be useful for for `cant_compile` to return the
exception object that it caught, for more specific assertions.
Python 3 supports keyword-only arguments as described in the immortal
PEP 3102. This commit implements keyword-only argument support for Hy
using a `&kwonly` lambda-list-keyword with semantics analogous how
`&optional` arguments are handled: `&kwonly` arguments are either a
symbol, in which case the keyword argument so named is mandatory, or a
two-element list, the first of which is the symbolic name of the keyword
argument and the second of which is its default value if not
supplied. If Hy is running under Python 2, attempting to use `&kwonly`
args will raise a HyTypeError.
This effort is with the aim of resolving #453.
Expressions can sometimes contain itertools.islice objects, which we can
only walk if we force them into a list. To do this, the walk function
has to be taught that collections that are not instances of list should
be forced into a list.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Python 3.5's PEP 448 ("Additional Unpacking Generalizations") allows the
iterable- and dictionary- unpacking operators to be used more than once;
the implementation (see https://hg.python.org/cpython/rev/a65f685ba8c0)
gets rid of the optional `starargs` and `kwargs` arguments to `ast.Call`
and `ast.ClassDef`, instead using `ast.Starred` and `ast.keyword`
objects inside of the normal `args` and `keywords` lists,
respectively. This commit allows Hy's `apply` to work correctly with
this revised AST when running under Python 3.5.
As reported in issue #748, there was a bug in which passing a lambda
as the value of a :keyword argument would fail—
$ hy --spy
hy 0.10.1 using CPython(default) 3.4.0 on Linux
=> (sorted (range 10) :key (fn [x] (- x)))
from hy.core.language import range
sorted(range(10), key=_hy_anon_fn_1)
Traceback (most recent call last):
File "<input>", line 1, in <module>
NameError: name '_hy_anon_fn_1' is not defined
The function call would appear in the generated AST without being
preceded by the appropriate function definition corresponding to the
anonymous function argument value in the Hy source, causing either a
NameError (as in the example above), or erroneous reuse of whatever
function was already pointed to by the `_hy_anon_fn_` name referenced
in the list of keywords passed to `ast.Call`.
This commit aims to fix the problem by handling it in same way that
the expression/statement gap is bridged many other places in the
compiler, by adding the compiled value of the keyword argument to the
Result object being built during `_compile_collect`, with the
understanding that any Python statements implied by the argument value
will be appropriately preserved therein.
Python 3.5 will have a new commercial-at infix operator with the magic
methods __matmul__, __rmatmul__, and __imatmul__, unused as yet in the
standard library, but intended to represent matrix multiplication in
numerical code; see PEP 465 (https://www.python.org/dev/peps/pep-0465/)
for details. This commit (developed against Python 3.5 alpha 3) brings
support for this operator to Hy when running under Python 3.5 (or,
hypothetically as yet, greater). For Hy under Python <= 3.4, attempting
to use `@` in function-call position currently results in a NameError;
this commit does not change that behavior.
This is intended to resolve#668.
jcrocholl/pep8 (used by flake8, used in Hy's continuous integration
builds) introduced an imports-at-top-of-file check in 1.6.0 and a
line-breaks-around-binary-operators check in 1.6.2. This commit makes
nonfunctional changes to bring the Hy codebase in compliance with this
tool, fixing #764.
This code is heavily, *heavily* based off of Guillermo Vaya
(willyfrog)'s work... instead of defining its own keyword arg though, it
uses the "standard" :kwarg type, which is the main difference from
willyfrog's original branch.
Included tests and some documentation in the tutorial.
Also documented "apply" separately as an example of reproducing
*args and **kwargs.
When (fn) or (defn) does not get an arglist as first/second parameter,
emit a more descriptive error message, rather than an ugly traceback.
Fixes#716.
Reported-by: Joakim Tall
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Our MetaImporter was being inserted at the end of sys.meta_path.
For Python prior to 3.3, this was fine since sys.meta_path
was empty by default. As of the completion of PEP 302 in Py3.3 and
later, there are several importers registered by default. One of
these was trying (and failing) to import simple Hy modules,
resulting in a failure to import anything inside __init__.hy.
This change simply inserts the Hy-specific importer at the front
of the list.
This was noted in issue #620 (great catch @algernon)
A tribute to Portal 2, this function will return an infinite list of the
contents of the AUTHORS file on GitHub master (assuming requests is
installed). Except, the macro does this, the function never gets called,
it is purely there for tribute reasons.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Python has the keyword.iskeyword method we can leverage for Python
keywords, but we also need to address Hy builtins like 'get' or
'slice'.
And to make behavior compatible with Python 2 or 3, we also make
a special case to prevent assignment to False, True or None as
well as the Hy versions: false, true, null, and nil.
For non-Hy modules, we also check to make sure the symbol is not
part of the compiler. This allows shadow.hy to override "+" but
prevents general use from re-defn-ing 'get' or 'do'.
As noted in #600, Python 3 allows a return inside a generator
method, that raises a StopIteration and passes the return value
inside the 'value' attr of the exception.
To allow this behaviour we simple set 'contains_yield' while compiling
'yield', thus allowing a return statement, but only for Python 3. Then
when compiling the try-except, we check for contains_yield to decide
whether there will be a return.
This allows code like:
(defn gen []
(yield 3)
"goodbye")
to compile in both Py2 and Py3. The return value is simply ignored in
Python 2.
hy2py in Python 2 gives:
def g():
yield 3L
u'goodbye'
while hy2py in Python 3 gives:
def g():
yield 3
return 'goodbye'
Turns out return in yield started in Python 3.3
This new core module allows us to shadow the builtin Python operators so
they may be passed to sequence functions that expect functions:
=> (map / [1 2 3 4 5])
[1.0, 0.5, 0.3333333333333333, 0.25]
Currently, defmacro/g! doesn't respond well when it comes across a
HyObject that doesn't respond to the instance method startswith (e.g.
HyInteger, HyFloat, etc.). This updates defmacro/g! to be a little
safer when searching for the gensyms it needs to create.
This also breaks out the PY3 only tests into their own file. We need to do this because raise from is a syntax error in PY2, so we can't rely on the previous hack of catching a HyCompileError - it would compile fine through Hy and then be a syntax error in Python.
As a result:
* functions such as `nth` should work correctly on iterators;
* `nth` will raise `IndexError` (in a fashion consistent with `get`)
when the index is out of bounds;
* `take`, etc. will raise `ValueError` instead of returning
an ambiguous value if the index is negative;
* `map`, `zip`, `range`, `input`, `filter` work the same way (Py3k one)
on both Python 2 and 3 (see #523 and #331).
Also small DRYing in try handling.
Previously, writing a bare (try (foo)) would invoke Pokemon
exception catching (gotta catch 'em all) instead of the correct
behavior, which is to raise the exception if no handler is provided.
Note that this is a cute feature of Hy, as a `try` with no `except`
is a syntax error. We avoid the syntax error here because we don't
use Python's compiler, which is the only thing that can throw
Syntax Errors. :D
Fixes#555.
The yield-from that existed previously wasn't actually implementing the
full complexity of "yield from":
http://legacy.python.org/dev/peps/pep-0380/#formal-semantics
... this includes passing along errors, and many other things.
Also removes the yield-from backport macro, since it does not seem
possible at present to conditionally build macros.
Thus, there is no longer yield-from on pre-python-3.3 systems.
Includes updated docs and tests to reflect all this.
Example:
(defmain [&rest args]
(print "now we're having a fun time!")
(print args))
Which outputs:
$ hy test.hy
now we're having a fun time!
(['test.hy'],)
Includes documentation and tests.
One would expect the form:
> (defmacro a (&rest b) b)
> (a 1 2)
To return a tuple object but we have no Hy model so it returns a HyList.
Not sure if this is the right thing to do.
When (import) encounters anything but a HySymbol or HyList, raise an
exception, as that is not valid in Hy. Previously, anything other than a
HySymbol or HyList was simply ignored, turning that particular import
into a no-op, which was both wrong and confusing.
Reported-by: Richard Parsons <richard.lee.parsons@gmail.com>
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This function will recursively perform all possible macroexpansions in
the supplied form. Unfortunately, it also traverses into quasiquoted
parts, where it shouldn't, but it is a useful estimation of macro
expansion anyway.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
The hy.contrib.walk module provides a few functions to walk the Hy AST,
and potentially transform it along the way. The main entry point
is (walk), which takes two functions and a form as arguments, and
applies the first (inner) function to each element of the form, building
up a data structure of the same type as the original. Then applies outer
(the second function) to the result.
Two convenience functions are provided: (postwalk) and (prewalk), which
do a depth-first, post/pre-order traversal of the form.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* hy/core/language.hy: Adding a simple `identity` function that returns
the argument supplied to it
* docs/language/core.rst: Updated docs with identity function
Sometimes it is better to start with the false condition, sometimes that
makes the code clearer. For that, the (if-not) macro, which simply
reverses the order of the condition blocks, can be of great use.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
In the same vein as defmacro-alias, this implements defn-alias /
defun-alias, which does essentially the same thing as defmacro-alias,
but for functions.
Signed-off-by: Gergely Nagy <algernon@balabit.hu>
With this patch, every identifier is split up along dots, each part gets
separately mangled, and then it is all joined back together. This allows
for fun stuff like (.foo? (Foo)), and even more contrived examples.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
The hy2py tool has been very useful for me, but most of the time, it's
only a part of its output that one is interested in. The whole output,
with source code, AST and python code together is one big monstrosity.
So instead of printing all that, lets have a few handy command-line
options to control which part gets printed.
By default, only the generated python source is, as that's what the name
of the tool implies.
Also, don't run it. That's what hy is for.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
There's no reason why one would need to choose between --spy and -i, so
pass down options.spy to run_icommand, and then to HyREPL, so we can
have both.
Signed-off-by: Gergely Nagy <algernon@balabit.hu>
* hy/core/language.hy:
-Added a simple coll? function that checks whether the given argument
is an iterable and not a string,
- Also replaced the check in `flatten` by coll?
* tests/native_tests/core.hy: Tests updated for checking coll?
This cleans up a number of doc warnings, including a bad
underline for zero?
While there, added a nil? function to match up with the
new nil is None.
Also un-hid myself from coreteam.
This version is much simpler.
At the point that the exception is raised, we don't have access to
the actual source, just the current expression. but as the
exception percolates up, we can intercept it, add the source and
the re-raise it.
Then at the final point, in the cmdline handler, we can choose to
let the entire traceback print, or just the simpler, direct error
message.
And even with the full traceback, the last bit is nicely formatted
just like the shorter, simpler message.
The error message is colored if clint is installed, but to avoid
yet another dependency, you get monochrome without clint.
I'm sure there is a better way to do the markup, the current method
is kludgy but works.
I wish there was more shared code between HyTypeError and LexException
but they are kind of different in some fundamental ways.
This doesn't work (yet) with runtime errors generated from Python,
like NameError, but I have a method that can catch NameError and turn it
into a more pleasing output.
Finally, there is no obvious way to raise HyTypeError from pure Hy code,
so methods in core/language.hy throw ugly TypeError/ValueError.
When calling get with more than two arguments, treat the rest as indexes
into the expression from the former. That is, (get foo "bar" "baz")
would translate to foo["bar"]["baz"], and so on.
This fixes#362.
Requested-by: Sean B. Palmer <sean@miscoranda.com>
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* hy/contrib/anaphoric.hy: The following anaphoric macros have been
added
`ap-reject` : Opposite of ap-filter, yields the elements when a `pred`
evaluates to false
`ap-dotimes` : Execute body forms (possibly for side-effects) n times
with `it` bound from 0 to n-1
`ap-first` : return the first element that passes predicate
`ap-last` : return the last element that passes predicate
`ap-reduce`: anaphoric form of reduce that allows `acc` and `it` to
create a function that is applied over the list
* docs/contrib/anaphoric.rst: updated docs to reflect these changes
* tests/__init__.py: updated to explicitly include tests for anaphoric
macros
Apply didn't work on method calls (i.e. `(apply .foo [bar]) broke).
This slipped through because there were no tests of this behavior. I noticed
it while trying to merge the `meth` fixes.
Added first iteration of reader macros
Refactored defmacro and defreader
Added test inn hy/tests/lex/test_lex.py
Added new test in hy/tests/native/tests
Added new test in hy/tests/macros.
changed the error given in the dispatch macro and added some handling for missing symbol and invalid characters
Adding to the manual gensym for macros are 2 new
macros, but very literal from the CL in
letoverlambda.
The first is the (with-gensyms ...) macro that
can generate a small set of syms for a macro. Works
something like:
(defmacro adder2 [A B]
(with-gensyms [a b]
`(let [[~a ~A] [~b ~B]]
(+ ~a ~b))))
and ~a and ~b will be replaced with (gensym "a") and
(gensym "b") respectively.
Then the final macro is a new defmacro that will automatically
replace symbols prefaced with "g!" with a new gensym based on the
rest of the symbol. So in this final version of 'nif':
(defmacro/g! nif4 (expr pos zero neg)
`(let [[~g!result ~expr]]
(cond [(pos? ~g!result) ~pos]
[(zero? ~g!result) ~zero]
[(neg? ~g!result) ~neg])))
all uses of ~g!result will be replaced with (gensym "result").
Simple implementation of gensym in Hy.
Returns a new HySymbol.
Usable in macros like:
(defmacro nif [expr pos zero neg]
(let [[g (gensym)]]
`(let [[~g ~expr]]
(cond [(pos? ~g) ~pos]
[(zero? ~g) ~zero]
[(neg? ~g) ~neg]))))
This addresses all the general comments about (gensym), and doesn't
try to implement "auto-gensym" yet. But clearly the macro approach
instead of the pre-processor approach (as described in the
letoverlambda (http://letoverlambda.com/index.cl/guest/chap3.html#sec_5)
is the way to go
Like other lisps, operators `+` and `*` return their identity values
when called with no arguments. Also with a single operand they return
the operand.
This fixes#372
`hy --spy` fails on hy 0.9.11.
$ hy --spy
hy 0.9.11
=> (type "hy")
Traceback (most recent call last):
File "/usr/local/lib/python2.7/dist-packages/hy/cmdline.py", line 68, in print_python_code
import astor.codegen
ImportError: No module named astor.codegen
The fancypants Hy award goes to Nick for coming up with the quoted
symbol hack for exports. This broke with foo?, since the export string
needs to be is_foo, but using a quoted string will pick up the change
due to it being a Symbol.
Mad clown love for that, @olasd.
A couple of more macros:
hy> (--each-while [1 2 3 4 5] (< it 3) (print it))
1
2
3
hy>
```--each-while``` continues to evaluate the body form while the
predicate form is true for each element in the list.
```--map-when``` uses a predicate form to determine when to apply the
map form upon the element in the list:
hy> (list (--map-when (even? it) (* it 3) [1 2 3 4]))
[1, 6, 3, 12]
Anaphoric macros reduce the need to specify a lambda by binding a
special name in a form passed as a parameter to the macro. This allows
you to write more concise code:
(= (list (--filter (even? it) [1 2 3 4])) [2 4])
This patch just adds a few basic ones. Other forms that can be
converted to anaphoric versions include reduce, remove, enumerate,
etc.
This gets rid of the dichotomy between bootstrap.py and macros.hy,
by making both files hy modules.
I added some error checking to make the macros more resilient. The
biggest (user-visible) change is the change in cond, which now only
accepts lists as arguments. Tests updated accordingly.
Closes: #176 (whoops, no more bootstrap)
This rounds out the first pass at a set of core functions, adding
some that were not in the first PR.
From here I'm working on a contrib.seq and contrib.io module to
hold less obvious but maybe interesting native functions that can
move to core if desired.
This should also close out issure #150 asking for some core
functions like these.
