2 Provides interface to shell MAN file parser.
4 Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>
5 Copyright 2015 Dell Inc.
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 Convert a Unicode character to upper case only if
20 it maps to a valid small-case ASCII character.
22 This internal function only deal with Unicode character
23 which maps to a valid small-case ASCII character, i.e.
24 L'a' to L'z'. For other Unicode character, the input character
27 @param Char The character to convert.
29 @retval LowerCharacter If the Char is with range L'a' to L'z'.
30 @retval Unchanged Otherwise.
35 InternalShellCharToUpper (
40 Verifies that the filename has .MAN on the end.
42 allocates a new buffer and copies the name (appending .MAN if necessary)
44 ASSERT if ManFileName is NULL
46 @param[in] ManFileName original filename
48 @return the new filename with .man as the extension.
53 IN CONST CHAR16
*ManFileName
57 if (ManFileName
== NULL
) {
63 if (StrnCmp(ManFileName
+StrLen(ManFileName
)-4, L
".man", 4)==0) {
64 Buffer
= AllocateCopyPool(StrSize(ManFileName
), ManFileName
);
66 Buffer
= AllocateZeroPool(StrSize(ManFileName
) + 4*sizeof(CHAR16
));
69 (StrSize(ManFileName
) + 4*sizeof(CHAR16
))/sizeof(CHAR16
),
74 (StrSize(ManFileName
) + 4*sizeof(CHAR16
))/sizeof(CHAR16
),
84 Search the path environment variable for possible locations and test for
85 which one contains a man file with the name specified. If a valid file is found
86 stop searching and return the (opened) SHELL_FILE_HANDLE for that file.
88 @param[in] FileName Name of the file to find and open.
89 @param[out] Handle Pointer to the handle of the found file. The
90 value of this is undefined for return values
93 @retval EFI_SUCCESS The file was found. Handle is a valid SHELL_FILE_HANDLE
94 @retval EFI_INVALID_PARAMETER A parameter had an invalid value.
95 @retval EFI_NOT_FOUND The file was not found.
100 IN CONST CHAR16
*FileName
,
101 OUT SHELL_FILE_HANDLE
*Handle
104 CHAR16
*FullFileName
;
107 if ( FileName
== NULL
109 || StrLen(FileName
) == 0
111 return (EFI_INVALID_PARAMETER
);
114 FullFileName
= ShellFindFilePath(FileName
);
115 if (FullFileName
== NULL
) {
116 return (EFI_NOT_FOUND
);
120 // now open that file
122 Status
= EfiShellOpenFileByName(FullFileName
, Handle
, EFI_FILE_MODE_READ
);
123 FreePool(FullFileName
);
129 parses through Buffer (which is MAN file formatted) and returns the
130 detailed help for any sub section specified in the comma seperated list of
131 sections provided. If the end of the file or a .TH section is found then
134 Upon a sucessful return the caller is responsible to free the memory in *HelpText
136 @param[in] Buffer Buffer to read from
137 @param[in] Sections name of command's sub sections to find
138 @param[in] HelpText pointer to pointer to string where text goes.
139 @param[in] HelpSize pointer to size of allocated HelpText (may be updated)
141 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
142 @retval EFI_SUCCESS the section was found and its description sotred in
147 ManBufferFindSections(
148 IN CONST CHAR16
*Buffer
,
149 IN CONST CHAR16
*Sections
,
150 IN CHAR16
**HelpText
,
155 CONST CHAR16
*CurrentLocation
;
156 BOOLEAN CurrentlyReading
;
167 return (EFI_INVALID_PARAMETER
);
170 Status
= EFI_SUCCESS
;
171 CurrentlyReading
= FALSE
;
174 for (CurrentLocation
= Buffer
,TempString
= NULL
175 ; CurrentLocation
!= NULL
&& *CurrentLocation
!= CHAR_NULL
176 ; CurrentLocation
=StrStr(CurrentLocation
, L
"\r\n"),TempString
= NULL
178 while(CurrentLocation
[0] == L
'\r' || CurrentLocation
[0] == L
'\n') {
181 if (CurrentLocation
[0] == L
'#') {
183 // Skip comment lines
187 if (StrnCmp(CurrentLocation
, L
".TH", 3) == 0) {
189 // we hit the end of this commands section so stop.
193 if (StrnCmp(CurrentLocation
, L
".SH ", 4) == 0) {
194 if (Sections
== NULL
) {
195 CurrentlyReading
= TRUE
;
197 } else if (CurrentlyReading
) {
198 CurrentlyReading
= FALSE
;
200 CurrentLocation
+= 4;
202 // is this a section we want to read in?
204 if (StrLen(CurrentLocation
)!=0) {
205 TempString2
= StrStr(CurrentLocation
, L
" ");
206 TempString2
= MIN(TempString2
, StrStr(CurrentLocation
, L
"\r"));
207 TempString2
= MIN(TempString2
, StrStr(CurrentLocation
, L
"\n"));
208 ASSERT(TempString
== NULL
);
209 TempString
= StrnCatGrow(&TempString
, NULL
, CurrentLocation
, TempString2
==NULL
?0:TempString2
- CurrentLocation
);
210 if (TempString
== NULL
) {
211 Status
= EFI_OUT_OF_RESOURCES
;
214 SectionName
= TempString
;
215 SectionLen
= StrLen(SectionName
);
216 SectionName
= StrStr(Sections
, SectionName
);
217 if (SectionName
== NULL
) {
218 SHELL_FREE_NON_NULL(TempString
);
221 if (*(SectionName
+ SectionLen
) == CHAR_NULL
|| *(SectionName
+ SectionLen
) == L
',') {
222 CurrentlyReading
= TRUE
;
225 } else if (CurrentlyReading
) {
227 if (StrLen(CurrentLocation
)!=0) {
228 TempString2
= StrStr(CurrentLocation
, L
"\r");
229 TempString2
= MIN(TempString2
, StrStr(CurrentLocation
, L
"\n"));
230 ASSERT(TempString
== NULL
);
231 TempString
= StrnCatGrow(&TempString
, NULL
, CurrentLocation
, TempString2
==NULL
?0:TempString2
- CurrentLocation
);
232 if (TempString
== NULL
) {
233 Status
= EFI_OUT_OF_RESOURCES
;
237 // copy and save the current line.
239 ASSERT((*HelpText
== NULL
&& *HelpSize
== 0) || (*HelpText
!= NULL
));
240 StrnCatGrow (HelpText
, HelpSize
, TempString
, 0);
241 if (HelpText
== NULL
) {
242 Status
= EFI_OUT_OF_RESOURCES
;
245 StrnCatGrow (HelpText
, HelpSize
, L
"\r\n", 0);
246 if (HelpText
== NULL
) {
247 Status
= EFI_OUT_OF_RESOURCES
;
252 SHELL_FREE_NON_NULL(TempString
);
254 SHELL_FREE_NON_NULL(TempString
);
255 if (!Found
&& !EFI_ERROR(Status
)) {
256 return (EFI_NOT_FOUND
);
262 parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
263 detailed help for any sub section specified in the comma seperated list of
264 sections provided. If the end of the file or a .TH section is found then
267 Upon a sucessful return the caller is responsible to free the memory in *HelpText
269 @param[in] Handle FileHandle to read from
270 @param[in] Sections name of command's sub sections to find
271 @param[out] HelpText pointer to pointer to string where text goes.
272 @param[out] HelpSize pointer to size of allocated HelpText (may be updated)
273 @param[in] Ascii TRUE if the file is ASCII, FALSE otherwise.
275 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
276 @retval EFI_SUCCESS the section was found and its description sotred in
282 IN SHELL_FILE_HANDLE Handle
,
283 IN CONST CHAR16
*Sections
,
284 OUT CHAR16
**HelpText
,
292 BOOLEAN CurrentlyReading
;
301 return (EFI_INVALID_PARAMETER
);
304 Status
= EFI_SUCCESS
;
305 CurrentlyReading
= FALSE
;
309 ReadLine
= AllocateZeroPool(Size
);
310 if (ReadLine
== NULL
) {
311 return (EFI_OUT_OF_RESOURCES
);
314 for (;!ShellFileHandleEof(Handle
);Size
= 1024) {
315 Status
= ShellFileHandleReadLine(Handle
, ReadLine
, &Size
, TRUE
, &Ascii
);
316 if (ReadLine
[0] == L
'#') {
318 // Skip comment lines
323 // ignore too small of buffer...
325 if (Status
== EFI_BUFFER_TOO_SMALL
) {
326 Status
= EFI_SUCCESS
;
328 if (EFI_ERROR(Status
)) {
330 } else if (StrnCmp(ReadLine
, L
".TH", 3) == 0) {
332 // we hit the end of this commands section so stop.
335 } else if (StrnCmp(ReadLine
, L
".SH", 3) == 0) {
336 if (Sections
== NULL
) {
337 CurrentlyReading
= TRUE
;
341 // we found a section
343 if (CurrentlyReading
) {
344 CurrentlyReading
= FALSE
;
347 // is this a section we want to read in?
349 for ( SectionName
= ReadLine
+ 3
350 ; *SectionName
== L
' '
352 SectionLen
= StrLen(SectionName
);
353 SectionName
= StrStr(Sections
, SectionName
);
354 if (SectionName
== NULL
) {
357 if (*(SectionName
+ SectionLen
) == CHAR_NULL
|| *(SectionName
+ SectionLen
) == L
',') {
358 CurrentlyReading
= TRUE
;
360 } else if (CurrentlyReading
) {
363 // copy and save the current line.
365 ASSERT((*HelpText
== NULL
&& *HelpSize
== 0) || (*HelpText
!= NULL
));
366 StrnCatGrow (HelpText
, HelpSize
, ReadLine
, 0);
367 StrnCatGrow (HelpText
, HelpSize
, L
"\r\n", 0);
371 if (!Found
&& !EFI_ERROR(Status
)) {
372 return (EFI_NOT_FOUND
);
378 parses through the MAN file formatted Buffer and returns the
379 "Brief Description" for the .TH section as specified by Command. If the
380 command section is not found return EFI_NOT_FOUND.
382 Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
384 @param[in] Handle Buffer to read from
385 @param[in] Command name of command's section to find
386 @param[in] BriefDesc pointer to pointer to string where description goes.
387 @param[in] BriefSize pointer to size of allocated BriefDesc
389 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
390 @retval EFI_SUCCESS the section was found and its description sotred in
395 ManBufferFindTitleSection(
397 IN CONST CHAR16
*Command
,
398 IN CHAR16
**BriefDesc
,
405 CHAR16
*CurrentLocation
;
407 CONST CHAR16 StartString
[] = L
".TH ";
408 CONST CHAR16 EndString
[] = L
" 0 ";
412 || (BriefDesc
!= NULL
&& BriefSize
== NULL
)
414 return (EFI_INVALID_PARAMETER
);
417 Status
= EFI_SUCCESS
;
420 // more characters for StartString and EndString
422 TitleLength
= StrSize(Command
) + (StrLen(StartString
) + StrLen(EndString
)) * sizeof(CHAR16
);
423 TitleString
= AllocateZeroPool(TitleLength
);
424 if (TitleString
== NULL
) {
425 return (EFI_OUT_OF_RESOURCES
);
427 StrCpyS(TitleString
, TitleLength
/sizeof(CHAR16
), StartString
);
428 StrCatS(TitleString
, TitleLength
/sizeof(CHAR16
), Command
);
429 StrCatS(TitleString
, TitleLength
/sizeof(CHAR16
), EndString
);
431 CurrentLocation
= StrStr(*Buffer
, TitleString
);
432 if (CurrentLocation
== NULL
){
433 Status
= EFI_NOT_FOUND
;
436 // we found it so copy out the rest of the line into BriefDesc
437 // After skipping any spaces or zeroes
439 for (CurrentLocation
+= StrLen(TitleString
)
440 ; *CurrentLocation
== L
' ' || *CurrentLocation
== L
'0' || *CurrentLocation
== L
'1' || *CurrentLocation
== L
'\"'
441 ; CurrentLocation
++);
443 TitleEnd
= StrStr(CurrentLocation
, L
"\"");
444 if (TitleEnd
== NULL
) {
445 Status
= EFI_DEVICE_ERROR
;
447 if (BriefDesc
!= NULL
) {
448 *BriefSize
= StrSize(TitleEnd
);
449 *BriefDesc
= AllocateZeroPool(*BriefSize
);
450 if (*BriefDesc
== NULL
) {
451 Status
= EFI_OUT_OF_RESOURCES
;
453 StrnCpyS(*BriefDesc
, (*BriefSize
)/sizeof(CHAR16
), CurrentLocation
, TitleEnd
-CurrentLocation
);
457 for (CurrentLocation
= TitleEnd
458 ; *CurrentLocation
!= L
'\n'
459 ; CurrentLocation
++);
461 ; *CurrentLocation
== L
' ' || *CurrentLocation
== L
'\n' || *CurrentLocation
== L
'\r'
462 ; CurrentLocation
++);
463 *Buffer
= CurrentLocation
;
467 FreePool(TitleString
);
472 Parses a line from a MAN file to see if it is the Title Header. If it is, then
473 if the "Brief Description" is desired, allocate a buffer for it and return a
474 copy. Upon a sucessful return the caller is responsible to free the memory in
477 Uses a simple state machine that allows "unlimited" whitespace before and after the
478 ".TH", compares Command and the MAN file commnd name without respect to case, and
479 allows "unlimited" whitespace and '0' and '1' characters before the Short Description.
480 The PCRE regex describing this functionality is: ^\s*\.TH\s+(\S)\s[\s01]*(.*)$
481 where group 1 is the Command Name and group 2 is the Short Description.
483 @param[in] Command name of command whose MAN file we think Line came from
484 @param[in] Line Pointer to a line from the MAN file
485 @param[out] BriefDesc pointer to pointer to string where description goes.
486 @param[out] BriefSize pointer to size of allocated BriefDesc
487 @param[out] Found TRUE if the Title Header was found and it belongs to Command
489 @retval TRUE Line contained the Title Header
490 @retval FALSE Line did not contain the Title Header
494 IN CONST CHAR16
*Command
,
496 OUT CHAR16
**BriefDesc OPTIONAL
,
497 OUT UINTN
*BriefSize OPTIONAL
,
501 // The states of a simple state machine used to recognize a title header line
502 // and to extract the Short Description, if desired.
504 LookForThMacro
, LookForCommandName
, CompareCommands
, GetBriefDescription
, Final
508 UINTN CommandIndex
; // Indexes Command as we compare its chars to the MAN file.
509 BOOLEAN ReturnValue
; // TRUE if this the Title Header line of *some* MAN file.
510 BOOLEAN ReturnFound
; // TRUE if this the Title Header line of *the desired* MAN file.
515 State
= LookForThMacro
;
519 if (*Line
== L
'\0') {
525 // Handle "^\s*.TH\s"
526 // Go to state LookForCommandName if the title header macro is present; otherwise,
527 // eat white space. If we see something other than white space, this is not a
528 // title header line.
530 if (StrnCmp (L
".TH ", Line
, 4) == 0 || StrnCmp (L
".TH\t", Line
, 4) == 0) {
532 State
= LookForCommandName
;
534 else if (*Line
== L
' ' || *Line
== L
'\t') {
543 // Eat any "extra" whitespace after the title header macro (we have already seen
544 // at least one white space character). Go to state CompareCommands when a
545 // non-white space is seen.
546 case LookForCommandName
:
547 if (*Line
== L
' ' || *Line
== L
'\t') {
551 ReturnValue
= TRUE
; // This is *some* command's title header line.
552 State
= CompareCommands
;
553 // Do not increment Line; it points to the first character of the command
554 // name on the title header line.
559 // Compare Command to the title header command name, ignoring case. When we
560 // reach the end of the command (i.e. we see white space), the next state
561 // depends on whether the caller wants a copy of the Brief Description.
562 case CompareCommands
:
563 if (*Line
== L
' ' || *Line
== L
'\t') {
564 ReturnFound
= TRUE
; // This is the desired command's title header line.
565 State
= (BriefDesc
== NULL
) ? Final
: GetBriefDescription
;
567 else if (InternalShellCharToUpper (*Line
) != InternalShellCharToUpper (*(Command
+ CommandIndex
++))) {
573 // Handle "[\s01]*(.*)$"
574 // Skip whitespace, '0', and '1' characters, if any, prior to the brief description.
575 // Return the description to the caller.
576 case GetBriefDescription
:
577 if (*Line
!= L
' ' && *Line
!= L
'\t' && *Line
!= L
'0' && *Line
!= L
'1') {
578 *BriefSize
= StrSize(Line
);
579 *BriefDesc
= AllocateZeroPool(*BriefSize
);
580 if (*BriefDesc
!= NULL
) {
581 StrCpyS(*BriefDesc
, (*BriefSize
)/sizeof(CHAR16
), Line
);
592 } while (State
< Final
);
594 *Found
= ReturnFound
;
599 parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
600 "Brief Description" for the .TH section as specified by Command. If the
601 command section is not found return EFI_NOT_FOUND.
603 Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
605 @param[in] Handle FileHandle to read from
606 @param[in] Command name of command's section to find as entered on the
607 command line (may be a relative or absolute path or
608 be in any case: upper, lower, or mixed in numerous ways!).
609 @param[out] BriefDesc pointer to pointer to string where description goes.
610 @param[out] BriefSize pointer to size of allocated BriefDesc
611 @param[in, out] Ascii TRUE if the file is ASCII, FALSE otherwise, will be
612 set if the file handle is at the 0 position.
614 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
615 @retval EFI_SUCCESS the section was found and its description stored in
616 an allocated buffer if requested.
620 ManFileFindTitleSection(
621 IN SHELL_FILE_HANDLE Handle
,
622 IN CONST CHAR16
*Command
,
623 OUT CHAR16
**BriefDesc OPTIONAL
,
624 OUT UINTN
*BriefSize OPTIONAL
,
625 IN OUT BOOLEAN
*Ascii
636 || (BriefDesc
!= NULL
&& BriefSize
== NULL
)
638 return (EFI_INVALID_PARAMETER
);
641 Status
= EFI_SUCCESS
;
645 ReadLine
= AllocateZeroPool(Size
);
646 if (ReadLine
== NULL
) {
647 return (EFI_OUT_OF_RESOURCES
);
651 // Do not pass any leading path information that may be present to IsTitleHeader().
653 Start
= StrLen(Command
);
655 && (*(Command
+ Start
- 1) != L
'\\')
656 && (*(Command
+ Start
- 1) != L
'/')
657 && (*(Command
+ Start
- 1) != L
':')) {
661 for (;!ShellFileHandleEof(Handle
);Size
= 1024) {
662 Status
= ShellFileHandleReadLine(Handle
, ReadLine
, &Size
, TRUE
, Ascii
);
664 // ignore too small of buffer...
666 if (EFI_ERROR(Status
) && Status
!= EFI_BUFFER_TOO_SMALL
) {
670 Status
= EFI_NOT_FOUND
;
671 if (IsTitleHeader (Command
+Start
, ReadLine
, BriefDesc
, BriefSize
, &Found
)) {
672 Status
= Found
? EFI_SUCCESS
: EFI_NOT_FOUND
;
682 This function returns the help information for the specified command. The help text
683 will be parsed from a UEFI Shell manual page. (see UEFI Shell 2.0 Appendix B)
685 If Sections is specified, then each section name listed will be compared in a casesensitive
686 manner, to the section names described in Appendix B. If the section exists,
687 it will be appended to the returned help text. If the section does not exist, no
688 information will be returned. If Sections is NULL, then all help text information
689 available will be returned.
691 if BriefDesc is NULL, then the breif description will not be savedd seperatly,
692 but placed first in the main HelpText.
694 @param[in] ManFileName Points to the NULL-terminated UEFI Shell MAN file name.
695 @param[in] Command Points to the NULL-terminated UEFI Shell command name.
696 @param[in] Sections Points to the NULL-terminated comma-delimited
697 section names to return. If NULL, then all
698 sections will be returned.
699 @param[out] BriefDesc On return, points to a callee-allocated buffer
700 containing brief description text.
701 @param[out] HelpText On return, points to a callee-allocated buffer
702 containing all specified help text.
704 @retval EFI_SUCCESS The help text was returned.
705 @retval EFI_OUT_OF_RESOURCES The necessary buffer could not be allocated to hold the
707 @retval EFI_INVALID_PARAMETER HelpText is NULL.
708 @retval EFI_INVALID_PARAMETER ManFileName is invalid.
709 @retval EFI_NOT_FOUND There is no help text available for Command.
714 IN CONST CHAR16
*ManFileName
,
715 IN CONST CHAR16
*Command
,
716 IN CONST CHAR16
*Sections OPTIONAL
,
717 OUT CHAR16
**BriefDesc OPTIONAL
,
718 OUT CHAR16
**HelpText
722 SHELL_FILE_HANDLE FileHandle
;
728 EFI_DEVICE_PATH_PROTOCOL
*FileDevPath
;
729 EFI_DEVICE_PATH_PROTOCOL
*DevPath
;
731 if ( ManFileName
== NULL
735 return (EFI_INVALID_PARAMETER
);
743 // See if it's in HII first
745 TempString
= ShellCommandGetCommandHelp(Command
);
746 if (TempString
!= NULL
) {
747 TempString2
= TempString
;
748 Status
= ManBufferFindTitleSection(&TempString2
, Command
, BriefDesc
, &BriefSize
);
749 if (!EFI_ERROR(Status
) && HelpText
!= NULL
){
750 Status
= ManBufferFindSections(TempString2
, Sections
, HelpText
, &HelpSize
);
754 TempString
= GetManFileName(ManFileName
);
755 if (TempString
== NULL
) {
756 return (EFI_INVALID_PARAMETER
);
759 Status
= SearchPathForFile(TempString
, &FileHandle
);
760 if (EFI_ERROR(Status
)) {
761 FileDevPath
= FileDevicePath(NULL
, TempString
);
762 DevPath
= AppendDevicePath (ShellInfoObject
.ImageDevPath
, FileDevPath
);
763 Status
= InternalOpenFileDevicePath(DevPath
, &FileHandle
, EFI_FILE_MODE_READ
, 0);
764 FreePool(FileDevPath
);
768 if (!EFI_ERROR(Status
)) {
771 Status
= ManFileFindTitleSection(FileHandle
, Command
, BriefDesc
, &BriefSize
, &Ascii
);
772 if (!EFI_ERROR(Status
) && HelpText
!= NULL
){
773 Status
= ManFileFindSections(FileHandle
, Sections
, HelpText
, &HelpSize
, Ascii
);
775 ShellInfoObject
.NewEfiShellProtocol
->CloseFile(FileHandle
);
780 if (TempString
!= NULL
) {
781 FreePool(TempString
);