Skip to content

Commit ac5301d

Browse files
zonuexezonuexe
authored
Merge pull request #663 from emacs-php/refactor/php-local-manual
Divide functions for the PHP manual to php.el and php-local-manual.el
2 parents e075246 + 48bd19a commit ac5301d

File tree

4 files changed

+162
-139
lines changed

4 files changed

+162
-139
lines changed

‎Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
EMACS ?= emacs
2-
ELS = lisp/php.el lisp/php-align.el lisp/php-face.el lisp/php-project.el lisp/php-mode.el lisp/php-mode-debug.el
2+
ELS = lisp/php.el lisp/php-align.el lisp/php-face.el lisp/php-project.el lisp/php-local-manual.el lisp/php-mode.el lisp/php-mode-debug.el
33
AUTOLOADS = php-mode-autoloads.el
44
ELCS = $(ELS:.el=.elc)
55

‎lisp/php-local-manual.el

Lines changed: 96 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
;; Copyright (C) 2020 Friends of Emacs-PHP development
44

5-
;; Author: Eric James Michael Ritz
5+
;; Author: phil-s
66
;; Maintainer: USAMI Kenta <tadsan@zonu.me>
7-
;; URL: https://github.com/emacs-php/php-mode
7+
;; URL: https://github.com/emacs-php/php-mode/wiki/Local-PHP-Manual
88
;; Keywords: docs, php
99
;; Version: 2.0.0
1010
;; License: GPL-3.0-or-later
@@ -26,14 +26,104 @@
2626

2727
;; This package helps you search the locally installed PHP Manual.
2828
;; If you're only developing online, this feature is probably unnecessary.
29+
;;
30+
;; ## Notice
31+
;;
32+
;; This file is marked as an unmaintained feature.
33+
;; https://github.com/emacs-php/php-mode/wiki/Unmaintained-Features
34+
;;
35+
;; ## How to use
36+
;;
37+
;; see https://github.com/emacs-php/php-mode/wiki/Local-PHP-Manual
38+
;;
39+
;; ### php-local-manual-search
40+
;;
41+
;; Put follows code into your .emacs (~/.emacs.d/init.el) file:
42+
;;
43+
;; (custom-set-variables
44+
;; '(php-manual-path (expand-file-name "~/local/share/php-manual"))
45+
;; '(php-search-documentation-function #'php-local-manual-search))
46+
;;
2947

3048
;;; Code:
31-
(require 'php-mode)
49+
(require 'php)
3250

33-
(defalias 'php-local-manual-search #'php-search-local-documentation)
51+
(defconst php-local-manual-documentation-types
52+
'("function" "control-structures" "class" "book")
53+
;; "intro" and "ref" also look interesting, but for all practical purposes
54+
;; their terms are sub-sets of the "book" terms (with the few exceptions
55+
;; being very unlikely search terms).
56+
"The set (and priority sequence) of documentation file prefixes
57+
under which to search for files in the local documentation directory.")
3458

35-
;; TODO: move implementation
36-
;; (define-obsolete-function-alias 'php-search-local-documentation #'php-local-manual-search)
59+
(defvar php-local-manual--words-cache nil)
60+
61+
(defun php-local-manual--read-arg ()
62+
"Obtain interactive argument for searching documentation."
63+
;; Cache the list of documentation words available for completion,
64+
;; based on the defined types-of-interest.
65+
(let ((types-list php-local-manual-documentation-types)
66+
(words-cache php-local-manual--words-cache)
67+
(local-manual (and (stringp php-manual-path)
68+
(not (string= php-manual-path "")))))
69+
(when (and local-manual
70+
(not (assq types-list words-cache)))
71+
;; Generate the cache on the first run, or if the types changed.
72+
;; We read the filenames matching our types list in the local
73+
;; documentation directory, and extract the 'middle' component
74+
;; of each. e.g. "function.array-map.html" => "array_map".
75+
(let* ((types-opt (regexp-opt types-list))
76+
(pattern (concat "\\`" types-opt "\\.\\(.+\\)\\.html\\'"))
77+
(collection
78+
(mapcar (lambda (filename)
79+
(subst-char-in-string ?- ?_ (replace-regexp-in-string
80+
pattern "\\1" filename)))
81+
(directory-files php-manual-path nil pattern))))
82+
;; Replace the entire cache. If the types changed, we don't need
83+
;; to retain the collection for the previous value.
84+
(setq words-cache (list (cons types-list collection)))
85+
(setq php-local-manual--words-cache words-cache)))
86+
;; By default we search for (current-word) immediately, without prompting.
87+
;; With a prefix argument, or if there is no (current-word), we perform a
88+
;; completing read for a word from the cached collection.
89+
(let* ((default (current-word))
90+
(prompt (if default
91+
(format "Search PHP docs (%s): " default)
92+
"Search PHP docs: "))
93+
(collection (and local-manual
94+
(cdr (assq types-list words-cache))))
95+
(word (if (or current-prefix-arg (not default))
96+
(completing-read prompt collection nil nil nil nil default)
97+
default)))
98+
;; Return interactive argument list.
99+
(list word))))
100+
101+
;;;###autoload
102+
(defun php-local-manual-search (word)
103+
"Search the local PHP documentation (i.e. in `php-manual-path') for
104+
the word at point. The function returns t if the requested documentation
105+
exists, and nil otherwise.
106+
107+
With a prefix argument, prompt (with completion) for a word to search for."
108+
(interactive (php-local-manual--read-arg))
109+
(let ((file (catch 'found
110+
(cl-loop for type in php-local-manual-documentation-types do
111+
(let* ((doc-html (format "%s.%s.html"
112+
type
113+
(replace-regexp-in-string
114+
"_" "-" (downcase word))))
115+
(file (expand-file-name doc-html php-manual-path)))
116+
(when (file-exists-p file)
117+
(throw 'found file)))))))
118+
(when file
119+
(let ((file-url (if (string-prefix-p "file://" file)
120+
file
121+
(concat "file://" file))))
122+
(php-browse-documentation-url file-url))
123+
t)))
124+
125+
;;;###autoload
126+
(define-obsolete-function-alias 'php-search-local-documentation #'php-local-manual-search "2.0.0")
37127

38128
(provide 'php-local-manual)
39129
;;; php-local-manual.el ends here

‎lisp/php-mode.el

Lines changed: 1 addition & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@
7272
(require 'etags)
7373
(require 'speedbar)
7474
(require 'imenu)
75+
(require 'package)
7576
(require 'nadvice nil t)
7677

7778
(require 'cl-lib)
@@ -191,14 +192,6 @@ enabled."
191192
:tag "PHP Mode Do Not Use Semantic Imenu"
192193
:type 'boolean)
193194

194-
(defcustom php-completion-file ""
195-
"Path to the file which contains the function names known to PHP."
196-
:type 'string)
197-
198-
(defcustom php-manual-path ""
199-
"Path to the directory which contains the PHP manual."
200-
:type 'string)
201-
202195
;;;###autoload
203196
(if (version< emacs-version "24.4")
204197
(dolist (i '("php" "php5" "php7"))
@@ -1399,130 +1392,6 @@ current `tags-file-name'."
13991392
(message "Arglist for %s: %s" tagname arglist)
14001393
(message "Unknown function: %s" tagname))))
14011394

1402-
(defcustom php-search-documentation-browser-function nil
1403-
"Function to display PHP documentation in a WWW browser.
1404-
1405-
If non-nil, this shadows the value of `browse-url-browser-function' when
1406-
calling `php-search-documentation' or `php-search-local-documentation'."
1407-
:group 'php
1408-
:tag "PHP Search Documentation Browser Function"
1409-
:type '(choice (const :tag "default" nil) function)
1410-
:link '(variable-link browse-url-browser-function))
1411-
1412-
(defun php-browse-documentation-url (url)
1413-
"Browse a documentation URL using the configured browser function.
1414-
1415-
See `php-search-documentation-browser-function'."
1416-
(let ((browse-url-browser-function
1417-
(or php-search-documentation-browser-function
1418-
browse-url-browser-function)))
1419-
(browse-url url)))
1420-
1421-
(defvar php-search-local-documentation-types
1422-
(list "function" "control-structures" "class" "book")
1423-
;; "intro" and "ref" also look interesting, but for all practical purposes
1424-
;; their terms are sub-sets of the "book" terms (with the few exceptions
1425-
;; being very unlikely search terms).
1426-
"The set (and priority sequence) of documentation file prefixes
1427-
under which to search for files in the local documentation directory.")
1428-
1429-
(defvar php-search-local-documentation-words-cache nil)
1430-
1431-
(defun php--search-documentation-read-arg ()
1432-
"Obtain interactive argument for searching documentation."
1433-
;; Cache the list of documentation words available for completion,
1434-
;; based on the defined types-of-interest.
1435-
(let ((types-list php-search-local-documentation-types)
1436-
(words-cache php-search-local-documentation-words-cache)
1437-
(local-manual (and (stringp php-manual-path)
1438-
(not (string= php-manual-path "")))))
1439-
(when (and local-manual
1440-
(not (assq types-list words-cache)))
1441-
;; Generate the cache on the first run, or if the types changed.
1442-
;; We read the filenames matching our types list in the local
1443-
;; documentation directory, and extract the 'middle' component
1444-
;; of each. e.g. "function.array-map.html" => "array_map".
1445-
(let* ((types-opt (regexp-opt types-list))
1446-
(pattern (concat "\\`" types-opt "\\.\\(.+\\)\\.html\\'"))
1447-
(collection
1448-
(mapcar (lambda (filename) (subst-char-in-string
1449-
?- ?_ (replace-regexp-in-string
1450-
pattern "\\1" filename)))
1451-
(directory-files php-manual-path nil pattern))))
1452-
;; Replace the entire cache. If the types changed, we don't need
1453-
;; to retain the collection for the previous value.
1454-
(setq words-cache (list (cons types-list collection)))
1455-
(setq php-search-local-documentation-words-cache words-cache)))
1456-
;; By default we search for (current-word) immediately, without prompting.
1457-
;; With a prefix argument, or if there is no (current-word), we perform a
1458-
;; completing read for a word from the cached collection.
1459-
(let* ((default (current-word))
1460-
(prompt (if default
1461-
(format "Search PHP docs (%s): " default)
1462-
"Search PHP docs: "))
1463-
(collection (and local-manual
1464-
(cdr (assq types-list words-cache))))
1465-
(word (if (or current-prefix-arg (not default))
1466-
(completing-read prompt collection nil nil nil nil default)
1467-
default)))
1468-
;; Return interactive argument list.
1469-
(list word))))
1470-
1471-
(defun php-search-local-documentation (word)
1472-
"Search the local PHP documentation (i.e. in `php-manual-path') for
1473-
the word at point. The function returns t if the requested documentation
1474-
exists, and nil otherwise.
1475-
1476-
With a prefix argument, prompt (with completion) for a word to search for."
1477-
(interactive (php--search-documentation-read-arg))
1478-
(let ((file (catch 'found
1479-
(cl-loop for type in php-search-local-documentation-types do
1480-
(let* ((doc-html (format "%s.%s.html"
1481-
type
1482-
(replace-regexp-in-string
1483-
"_" "-" (downcase word))))
1484-
(file (expand-file-name doc-html php-manual-path)))
1485-
(when (file-exists-p file)
1486-
(throw 'found file)))))))
1487-
(when file
1488-
(let ((file-url (if (string-prefix-p "file://" file)
1489-
file
1490-
(concat "file://" file))))
1491-
(php-browse-documentation-url file-url))
1492-
t)))
1493-
1494-
(defsubst php-search-web-documentation (word)
1495-
"Return URL to search PHP manual search by `WORD'."
1496-
(php-browse-documentation-url (concat (or php-search-url php-site-url) word)))
1497-
1498-
;; Define function documentation function
1499-
(defun php-search-documentation (word)
1500-
"Search PHP documentation for the `WORD' at point.
1501-
1502-
If `php-manual-path' has a non-empty string value then the command
1503-
will first try searching the local documentation. If the requested
1504-
documentation does not exist it will fallback to searching the PHP
1505-
website.
1506-
1507-
With a prefix argument, prompt for a documentation word to search
1508-
for. If the local documentation is available, it is used to build
1509-
a completion list."
1510-
(interactive (php--search-documentation-read-arg))
1511-
(if (and (stringp php-manual-path)
1512-
(not (string= php-manual-path "")))
1513-
(or (php-search-local-documentation word)
1514-
(php-search-web-documentation word))
1515-
(php-search-web-documentation word)))
1516-
1517-
;; Define function for browsing manual
1518-
(defun php-browse-manual ()
1519-
"Bring up manual for PHP."
1520-
(interactive)
1521-
(browse-url (if (stringp php-manual-url)
1522-
php-manual-url
1523-
(format "%smanual/%s/" php-site-url php-manual-url))))
1524-
1525-
15261395
;; Font Lock
15271396
(defconst php-phpdoc-type-keywords
15281397
(list "string" "integer" "int" "boolean" "bool" "float"

‎lisp/php.el

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,70 @@ You can replace \"en\" with your ISO language code."
7878
:type '(choice (string :tag "URL to search PHP documentation")
7979
(const :tag "Use `php-site-url' variable" nil)))
8080

81+
(defcustom php-completion-file ""
82+
"Path to the file which contains the function names known to PHP."
83+
:type 'string)
84+
85+
(defcustom php-manual-path ""
86+
"Path to the directory which contains the PHP manual."
87+
:type 'string)
88+
89+
(defcustom php-search-documentation-function #'php-search-web-documentation
90+
"Function to search PHP Manual at cursor position."
91+
:group 'php
92+
:tag "PHP Search Documentation Function"
93+
:type '(choice (const :tag "Use online documentation" #'php-search-web-documentation)
94+
(const :tag "Use local documentation" #'php-local-manual-search)
95+
(function :tag "Use other function")))
96+
97+
(defcustom php-search-documentation-browser-function nil
98+
"Function to display PHP documentation in a WWW browser.
99+
100+
If non-nil, this shadows the value of `browse-url-browser-function' when
101+
calling `php-search-documentation' or `php-search-local-documentation'."
102+
:group 'php
103+
:tag "PHP Search Documentation Browser Function"
104+
:type '(choice (const :tag "default" nil) function)
105+
:link '(variable-link browse-url-browser-function))
106+
107+
;; Define function for browsing manual
108+
(defun php-browse-documentation-url (url)
109+
"Browse a documentation URL using the configured browser function.
110+
111+
See `php-search-documentation-browser-function'."
112+
(let ((browse-url-browser-function
113+
(or php-search-documentation-browser-function
114+
browse-url-browser-function)))
115+
(browse-url url)))
116+
117+
(defun php-browse-manual ()
118+
"Bring up manual for PHP."
119+
(interactive)
120+
(browse-url (if (stringp php-manual-url)
121+
php-manual-url
122+
(format "%smanual/%s/" php-site-url php-manual-url))))
123+
124+
(defun php-search-web-documentation (word)
125+
"Return URL to search PHP manual search by `WORD'."
126+
(interactive (list (current-word)))
127+
(php-browse-documentation-url (concat (or php-search-url php-site-url) word)))
128+
129+
(defun php-search-documentation (&optional word)
130+
"Search PHP documentation for the `WORD' at point.
131+
132+
If `php-manual-path' has a non-empty string value then the command
133+
will first try searching the local documentation. If the requested
134+
documentation does not exist it will fallback to searching the PHP
135+
website.
136+
137+
With a prefix argument, prompt for a documentation word to search
138+
for. If the local documentation is available, it is used to build
139+
a completion list."
140+
(interactive)
141+
(if (called-interactively-p 'interactive)
142+
(call-interactively php-search-documentation-function)
143+
(funcall php-search-documentation-function word)))
144+
81145
(defcustom php-class-suffix-when-insert "::"
82146
"Suffix for inserted class."
83147
:group 'php

0 commit comments

Comments
 (0)