Navigation
- index
- modules |
- next |
- previous |
- Sage Reference v4.5.1 »
- Miscellaneous »
AUTHORS:
This strips LaTeX commands from a string; it is used by the format function to process docstrings for display from the command line interface.
INPUT:
If embedded is False, then do the replacements in both math_substitutes and nonmath_substitutes. If True, then only do nonmath_substitutes.
OUTPUT: string
EXAMPLES:
sage: from sage.misc.sagedoc import detex
sage: detex(r'Some math: `n \geq k`. A website: \url{sagemath.org}.')
'Some math: n >= k. A website: sagemath.org.\n'
sage: detex(r'More math: `x \mapsto y`. {\bf Bold face}.')
'More math: x |--> y. { Bold face}.\n'
sage: detex(r'`a, b, c, \ldots, z`')
'a, b, c, ..., z\n'
sage: detex(r'`a, b, c, \ldots, z`', embedded=True)
'`a, b, c, \\ldots, z`'
Format Sage documentation s for viewing with IPython.
This calls detex on s to convert LaTeX commands to plain text, and if s contains a string of the form “<<<obj>>>”, then it replaces it with the docstring for “obj”.
INPUT:
OUTPUT: string
Set embedded equal to True if formatting for use in the notebook; this just gets passed as an argument to detex.
EXAMPLES:
sage: from sage.misc.sagedoc import format
sage: identity_matrix(2).rook_vector.__doc__[115:184]
'Let `A` be a general `m` by `n`\n (0,1)-matrix with `m \\le n`. '
sage: format(identity_matrix(2).rook_vector.__doc__[115:184])
'Let A be a general m by n\n (0,1)-matrix with m <= n.\n'
If the first line of the string is ‘nodetex’, remove ‘nodetex’ but don’t modify any TeX commands:
sage: format("nodetex\n`x \\geq y`")
'\n`x \\geq y`'
Testing a string enclosed in triple angle brackets:
sage: format('<<<identity_matrix')
'<<<identity_matrix\n'
sage: format('identity_matrixsage:')
'identity_matrixsage:\n'
sage: format('<<<identity_matrixsage:')[:28]
'Definition: identity_matrix('
Format the output from search_src, search_def, or search_doc as html, for use in the notebook.
INPUT:
This function parses r: it should have the form FILENAME: string where FILENAME is the file in which the string that matched the search was found. Everything following the first colon is ignored; we just use the filename. If FILENAME ends in ‘.html’, then this is part of the documentation; otherwise, it is in the source code. In either case, an appropriate link is created.
EXAMPLES:
sage: from sage.misc.sagedoc import format_search_as_html
sage: format_search_as_html('Source', 'algebras/steenrod_algebra_element.py: an antihomomorphism: if we call the antipode `c`, then', 'antipode antihomomorphism')
'<html><font color="black"><h2>Search Source: antipode antihomomorphism</h2></font><font color="darkpurple"><ol><li><a href="/src/algebras/steenrod_algebra_element.py"><tt>algebras/steenrod_algebra_element.py</tt></a>\n</ol></font></html>'
sage: format_search_as_html('Other', 'html/en/reference/sage/algebras/steenrod_algebra_element.html:an antihomomorphism: if we call the antipode <span class="math">c</span>, then', 'antipode antihomomorphism')
'<html><font color="black"><h2>Search Other: antipode antihomomorphism</h2></font><font color="darkpurple"><ol><li><a href="/doc/live/reference/sage/algebras/steenrod_algebra_element.html"><tt>reference/sage/algebras/steenrod_algebra_element.html</tt></a>\n</ol></font></html>'
Format Sage source code s for viewing with IPython.
If s contains a string of the form “<<<obj>>>”, then it replaces it with the source code for “obj”.
INPUT: s - string
OUTPUT: string
EXAMPLES:
sage: from sage.misc.sagedoc import format_src
sage: format_src('unladen swallow')
'unladen swallow'
sage: format_src('<<<Sqsage:')[5:15]
'Sq(*nums):'
If there is an argument module, print the Python help message for module. With no argument, print a help message about getting help in Sage.
EXAMPLES:
sage: help()
Welcome to Sage ...
Retrieve the documentation for obj.
INPUT: obj - a Sage object, function, etc.
OUTPUT: its documentation (string)
EXAMPLES:
sage: from sage.misc.sagedoc import my_getdoc
sage: s = my_getdoc(identity_matrix)
sage: type(s)
<type 'str'>
Retrieve the source code for obj.
INPUT:
OUTPUT: its documentation (string)
EXAMPLES:
sage: from sage.misc.sagedoc import my_getsource
sage: s = my_getsource(identity_matrix, True)
sage: s[:19]
'def identity_matrix'
Replace dollar signs with backticks.
More precisely, do a regular expression search. Replace a plain dollar sign ($) by a backtick (`). Replace an escaped dollar sign (\$) by a dollar sign ($). Don’t change a dollar sign preceded or followed by a backtick (`$ or $`), because of strings like “$HOME“. Don’t make any changes on lines starting with more spaces than the first nonempty line in s, because those are indented and hence part of a block of code or examples.
This also doesn’t replaces dollar signs enclosed in curly braces, to avoid nested math environments.
EXAMPLES:
sage: from sage.misc.sagedoc import process_dollars
sage: process_dollars('hello')
'hello'
sage: process_dollars('some math: $x=y$')
'some math: `x=y`'
Replace \$ with $, and don’t do anything when backticks are involved:
sage: process_dollars(r'a ``$REAL`` dollar sign: \$')
'a ``$REAL`` dollar sign: $'
Don’t make any changes on lines indented more than the first nonempty line:
sage: s = '\n first line\n indented $x=y$'
sage: s == process_dollars(s)
True
Don’t replace dollar signs enclosed in curly braces:
sage: process_dollars(r'f(n) = 0 \text{ if $n$ is prime}')
'f(n) = 0 \\text{ if $n$ is prime}'
This is not perfect:
sage: process_dollars(r'$f(n) = 0 \text{ if $n$ is prime}$')
'`f(n) = 0 \\text{ if $n$ is prime}$'
The regular expression search doesn’t find the last $. Fortunately, there don’t seem to be any instances of this kind of expression in the Sage library, as of this writing.
Replace \mathtt{BLAH} with either \verb|BLAH| (in the notebook) or BLAH (from the command line).
INPUT:
This function is called by format(), and if in the notebook, it sets embedded to be True, otherwise False.
EXAMPLES:
sage: from sage.misc.sagedoc import process_mathtt
sage: process_mathtt(r'e^\mathtt{self}')
'e^self'
sage: process_mathtt(r'e^\mathtt{self}', embedded=True)
'e^{\\verb|self|}'
Search Sage library source code for function definitions containing name. The search is case sensitive.
INPUT: same as for search_src().
OUTPUT: same as for search_src().
Note
The regular expression used by this function only finds function definitions that are preceded by spaces, so if you use tabs on a “def” line, this function will not find it. As tabs are not allowed in Sage library code, this should not be a problem.
EXAMPLES:
See the documentation for search_src() for more examples.
sage: print search_def("fetch", interact=False) # random # long time
matrix/matrix0.pyx: cdef fetch(self, key):
matrix/matrix0.pxd: cdef fetch(self, key)
sage: print search_def("fetch", path_re="pyx", interact=False) # random # long time
matrix/matrix0.pyx: cdef fetch(self, key):
Search Sage HTML documentation for lines containing string. The search is case-sensitive.
The file paths in the output are relative to $SAGE_ROOT/devel/sage/doc/output.
INPUT: same as for search_src().
OUTPUT: same as for search_src().
EXAMPLES:
See the documentation for search_src() for more examples.
sage: search_doc('creates a polynomial', path_re='tutorial', interact=False) # random
html/en/tutorial/tour_polynomial.html:<p>This creates a polynomial ring and tells Sage to use (the string)
If you search the documentation for ‘tree’, then you will get too many results, because many lines in the documentation contain the word ‘toctree’. If you use the whole_word option, though, you can search for ‘tree’ without returning all of the instances of ‘toctree’. In the following, since search_doc('tree', interact=False) returns a string with one line for each match, counting the length of search_doc('tree', interact=False).splitlines() gives the number of matches.
sage: len(search_doc('tree', interact=False).splitlines()) > 2000
True
sage: len(search_doc('tree', whole_word=True, interact=False).splitlines()) < 200
True
Search Sage library source code for lines containing string. The search is case-sensitive.
INPUT:
OUTPUT: If interact is False, then return a string with all of the matches, separated by newlines. On the other hand, if interact is True (the default), there is no output. Instead: at the command line, the search results are printed on the screen in the form filename:line_number:line of text, showing the filename in which each match occurs, the line number where it occurs, and the actual matching line. (If multiline is True, then only the filename is printed for each match.) The file paths in the output are relative to $SAGE_ROOT/devel/sage/. In the notebook, each match produces a link to the actual file in which it occurs.
The string and extraN arguments are treated as regular expressions, as is path_re, and errors will be raised if they are invalid. The matches will be case-sensitive unless ignore_case is True.
Note
The extraN parameters are present only because search_src(string, *extras, interact=False) is not parsed correctly by Python 2.6; see http://bugs.python.org/issue1909.
EXAMPLES:
First note that without using interact=False, this function produces no output, while with interact=False, the output is a string. These examples almost all use this option, so that they have something to which to compare their output.
You can search for “matrix” by typing search_src("matrix"). This particular search will produce many results:
sage: len(search_src("matrix", interact=False).splitlines()) # random # long time
9522
You can restrict to the Sage calculus code with search_src("matrix", module="sage.calculus"), and this produces many fewer results:
sage: len(search_src("matrix", module="sage.calculus", interact=False).splitlines()) # random
26
Note that you can do tab completion on the module string. Another way to accomplish a similar search:
sage: len(search_src("matrix", path_re="calc", interact=False).splitlines()) > 15
True
The following produces an error because the string ‘fetch(‘ is a malformed regular expression:
sage: print search_src(" fetch(", "def", interact=False)
...
error: unbalanced parenthesis
To fix this, escape the parenthesis with a backslash:
sage: print search_src(" fetch\(", "def", interact=False) # random # long time
matrix/matrix0.pyx: cdef fetch(self, key):
matrix/matrix0.pxd: cdef fetch(self, key)
sage: print search_src(" fetch\(", "def", "pyx", interact=False) # random # long time
matrix/matrix0.pyx: cdef fetch(self, key):
As noted above, the search is case-sensitive, but you can make it case-insensitive with the ‘ignore_case’ key word:
sage: s = search_src('Matrix', path_re='matrix', interact=False); s.find('x') > 0
True
sage: s = search_src('MatRiX', path_re='matrix', interact=False); s.find('x') > 0
False
sage: s = search_src('MatRiX', path_re='matrix', interact=False, ignore_case=True); s.find('x') > 0
True
Searches are by default restricted to single lines, but this can be changed by setting multiline to be True. In the following, since search_src(string, interact=False) returns a string with one line for each match, counting the length of search_src(string, interact=False).splitlines() gives the number of matches.
sage: len(search_src('log', 'derivative', interact=False).splitlines()) < 8
True
sage: len(search_src('log', 'derivative', interact=False, multiline=True).splitlines()) > 30
True
A little recursive narcissism: let’s do a doctest that searches for this function’s doctests. Note that you can’t put “sage:” in the doctest string because it will get replaced by the Python “>>>” prompt.
sage: print search_src('^ *sage[:] .*search_src\(', interact=False) # long time
misc/sagedoc.py:... len(search_src("matrix", interact=False).splitlines()) # random # long time
misc/sagedoc.py:... len(search_src("matrix", module="sage.calculus", interact=False).splitlines()) # random
misc/sagedoc.py:... len(search_src("matrix", path_re="calc", interact=False).splitlines()) > 15
misc/sagedoc.py:... print search_src(" fetch(", "def", interact=False)
misc/sagedoc.py:... print search_src(" fetch\(", "def", interact=False) # random # long time
misc/sagedoc.py:... print search_src(" fetch\(", "def", "pyx", interact=False) # random # long time
misc/sagedoc.py:... s = search_src('Matrix', path_re='matrix', interact=False); s.find('x') > 0
misc/sagedoc.py:... s = search_src('MatRiX', path_re='matrix', interact=False); s.find('x') > 0
misc/sagedoc.py:... s = search_src('MatRiX', path_re='matrix', interact=False, ignore_case=True); s.find('x') > 0
misc/sagedoc.py:... len(search_src('log', 'derivative', interact=False).splitlines()) < 8
misc/sagedoc.py:... len(search_src('log', 'derivative', interact=False, multiline=True).splitlines()) > 30
misc/sagedoc.py:... print search_src('^ *sage[:] .*search_src\(', interact=False) # long time
misc/sagedoc.py:... len(search_src("matrix", interact=False).splitlines()) > 9000 # long time
misc/sagedoc.py:... print search_src('matrix', 'column', 'row', 'sub', 'start', 'index', interact=False) # random # long time
TESTS:
As of this writing, there are about 9500 lines in the Sage library that contain “matrix”; it seems safe to assume we’ll continue to have over 9000 such lines:
sage: len(search_src("matrix", interact=False).splitlines()) > 9000 # long time
True
Check that you can pass 5 parameters:
sage: print search_src('matrix', 'column', 'row', 'sub', 'start', 'index', interact=False) # random # long time
matrix/matrix0.pyx:598: Get The 2 x 2 submatrix of M, starting at row index and column
matrix/matrix0.pyx:607: Get the 2 x 3 submatrix of M starting at row index and column index
matrix/matrix0.pyx:924: Set the 2 x 2 submatrix of M, starting at row index and column
matrix/matrix0.pyx:933: Set the 2 x 3 submatrix of M starting at row index and column