This package exports functions to read source files and parse
their headers.
Source files can be either elisp (.el) or Common Lisp (.lisp,
.lsp, .cl), and elisp sources may (require) common-lisp files
(.lisp, .lsp, .cl extensions for sources).
USAGE:
(file-emacs-variables "source.lisp")
--> (:|mode| "lisp" :|coding| "utf-8")
(scan-source-file "source.lisp" :external-format :utf-8)
--> #<source-file …>
(get-package "source.lisp")
--> #<source-package …>
LICENSE:
AGPL3
Copyright Pascal J. Bourguignon 2002 - 2015
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>
|
*emacs-head-variables* |
variable |
The emacs file variables that go to the head comment. Any other will go to the tail file variables.
Initial value: (mode coding)
|
*file-headers* |
variable |
The file header section in order generated.
Initial value: (FILE LANGUAGE SYSTEM USER-INTERFACE DESCRIPTION USAGE AUTHORS MODIFICATIONS BUGS LEGAL)
|
*line-length* |
variable |
Maximum number of character per line.
Initial value: 79
|
(dependencies self) |
generic-function |
RETURN: A list of packages the source object depends on.
ENSURE-SOURCE-FILE-PATHNAME
|
(extract-source-from-require-sexp sexp) |
function |
PRE: sexp is of the form: (REQUIRE module-name &OPTIONAL pathname-list)
module-name can be 'toto or (quote toto).
Each path name can be either a namestring, a physical path name or
a logical path name.
RETURN: A new list containing the pathname-list if present, or a list
containing the symbol-name of the module-name.
|
(file-emacs-variables filepath) |
function |
RETURN: A p-list containing the emacs file local variables in the file at FILEPATH.
FIND-FILE-IN-DIRECTORY
|
(find-file-path fname dir-paths) |
function |
RETURN: NIL or the path of FNAME found in one of DIR-PATHS.
FIND-FILE-WITH-EXTENSION
|
(get-closed-dependencies object-file load-paths &key verbose) |
function |
PRE: OBJECT-FILE is foo.fas or foo.elc, etc. RETURN: A list of object files recursively required by OBJECT-FILE.
|
(get-dependencies object-file packages load-paths &key verbose) |
function |
PRE: OBJECT-FILE is foo.fas or foo.elc, etc.
RETURN: A list of dependency for this OBJECT-FILE,
including the source-file and all the object files
of required files.
OBJECT-FILE: The file of which the dependencies are computed.
PACKAGES: A list of preloaded package names.
LOAD-PATHS: A list of directory path names where to find the files when
not found thru the logical pathname translations.
The presence in LOAD-PATHS of a logical pathname warrants
the presence in HOST-LPT of an entry mapping it to a physical
path.
VERBOSE: Prints information on *TRACE-OUTPUT*.
|
(get-depends object-files packages load-paths) |
function |
RETURN: A list of (cons object-file dependency-list).
NOTE: GET-DEPENDS uses the logical pathname translations in place
when called.
|
(get-package source-filepath &key external-format) |
function |
RETURN: The first DEFINE-PACKAGE sexp found on the top-level of the
SOURCE-FILE. If none found, then the first DEFPACKAGE sexp.
Or else, the first provide sexp, or else the file-name.
EXTERNAL-FORMAT: used to read the source file. If NIL, it's
determined from emacs file variables.
|
(get-requires source-filepath &key external-format) |
function |
RETURN: A list of REQUIRE sexps found on the top-level of the SOURCE-FILE.
EXTERNAL-FORMAT: used to read the source file. If NIL, it's
determined from emacs file variables.
|
(get-source-file filepath &key external-format) |
function |
RETURN: a source-file read from FILEPATH.
EXTERNAL-FORMAT: used to read the source file. If NIL, it's
determined from emacs file variables.
HEADER-AUTHORS
HEADER-DESCRIPTION
|
(header-licence header) |
function |
RETURN: Just the LICENCE from the LEGAL section.
HEADER-SLOT
PACKAGE-MEMBER-P
PARSE-EMACS-VARIABLES
|
(read-source-code stream &key test) |
function |
RETURN: An a-list of interesting forms from the source code:
:PACKAGES-DEFINED, :PACKAGES-USED, :ADDED-NICKNAMES,
:PROVIDES, :REQUIRES, and :TEST.
TEST: A predicate for forms that should be returned in the :TEST
entry.
BUGS: This should be rewritten using COM.INFORMATIMAGO.COMMON-LISP.SOURCE
|
(read-source-header stream &key comment-start comment-end line-char keep-spaces) |
function |
RETURN: A p-list containing the header found in the stream
at the current position;
the last line read.
NOTE: Reading stops as soon as a non-comment line is read.
If the stream can be positionned, the FILE-POSITION is set at the
beginning of this first non-comment line.
|
(scan-source-file source-filepath &key external-format load verbose keep-spaces) |
function |
DO: Makes a SOURCE-FILE instance and fills it with data got from
the source file at SOURCE-FILEPATH.
EXTERNAL-FORMAT: NIL => try to guess the encoding (use emacs local variables).
LOAD: Whether the file should be loaded before scanning it.
(needed until COM.INFORMATIMAGO.COMMON-LISP.SOURCE is used).
COMMENT-START: A regexp matching the line comment start for the header lines.
COMMENT-END: A regexp matching the line comment end for the header lines.
KEEP-SPACES:
NOTE: COMMENT-START and COMMENT-END are regexp only on clisp until
COM.INFORMATIMAGO.COMMON-LISP.REGEXP can be used.
RETURN: A SOURCE-FILE instance filled with the data from the source
file.
|
source-file |
class |
The description of the packages and dependencies of a source file.
Class precedence list: SOURCE-FILE STANDARD-OBJECT T
Class init args: PATHNAME EXTERNAL-FORMAT EMACS-VARIABLES HEADER PACKAGES-DEFINED PACKAGES-USED ADDED-NICKNAMES REQUIRES PROVIDES
SOURCE-FILE-ADDED-NICKNAMES
SOURCE-FILE-EMACS-VARIABLES
SOURCE-FILE-EXTERNAL-FORMAT
|
(source-file-for-object object-file) |
function |
RETURN: The source file for OBJECT-FILE (finding the right extension);
the extension of the object-file;
and the list of extensions couples.
SOURCE-FILE-HEADER
SOURCE-FILE-PACKAGES-DEFINED
SOURCE-FILE-PACKAGES-USED
SOURCE-FILE-PATHNAME
SOURCE-FILE-PROVIDES
SOURCE-FILE-REQUIRES
|
source-package |
class |
The description of a defpackage in a source file.
Class precedence list: SOURCE-PACKAGE STANDARD-OBJECT T
Class init args: NAME NICKNAMES DOCUMENTATION USE SHADOW SHADOWING-IMPORT-FROM IMPORT-FROM EXPORT INTERN
SOURCE-PACKAGE-DOCUMENTATION
SOURCE-PACKAGE-EXPORT
SOURCE-PACKAGE-IMPORT-FROM
SOURCE-PACKAGE-INTERN
SOURCE-PACKAGE-NAME
SOURCE-PACKAGE-NICKNAMES
SOURCE-PACKAGE-SHADOW
SOURCE-PACKAGE-SHADOWING-IMPORT-FROM
SOURCE-PACKAGE-USE
|
(write-emacs-head-variables bindings stream &key comment-start comment-end) |
function |
Write on the STREAM an emacs -*- comment line containing the given BINDINGS.
|
(write-emacs-tail-variables bindings stream &key comment-start comment-end) |
function |
Write on the STREAM an emacs file variable block containing the given BINDINGS.
|
(write-source-header headers stream &key comment-start comment-end line-char) |
function |
Write a source header in a comment. HEADERS: A P-list containing the header data. COMMENT-START: NIL or a string containing the start of comment lines. COMMENT-END: NIL or a string containing the end of comment lines. LINE-CHAR: A filler character used to draw a line in a comment. *LINE-LENGTH* The length of the line comment lines generated. The values may be strings or list of strings (lines). Possible keys are: - :file name of the file. - :language the programming language in the file. - :system the operating system this source runs on. - :user-interface the user interface framework this source uses. - :description a multi-line description of this source file. - :usage usage indications. - :authors a list of authors. - :modifications a changelog list. - :bugs a list of bugs. - :legal the license section.