ShellPkg/Application/Shell/ShellManParser.c

   1 /** @file
   2   Provides interface to shell MAN file parser.
   3
   4   Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include "Shell.h"
  16
  17 /**
  18   Verifies that the filename has .MAN on the end.
  19
  20   allocates a new buffer and copies the name (appending .MAN if necessary)
  21
  22   ASSERT if ManFileName is NULL
  23
  24   @param[in] ManFileName            original filename
  25
  26   @return the new filename with .man as the extension.
  27 **/
  28 CHAR16 *
  29 EFIAPI
  30 GetManFileName(
  31   IN CONST CHAR16 *ManFileName
  32   )
  33 {
  34   CHAR16 *Buffer;
  35   if (ManFileName == NULL) {
  36     return (NULL);
  37   }
  38   //
  39   // Fix the file name
  40   //
  41   if (StrnCmp(ManFileName+StrLen(ManFileName)-4, L".man", 4)==0) {
  42     Buffer = AllocateZeroPool(StrSize(ManFileName));
  43     if (Buffer != NULL) {
  44       StrCpy(Buffer, ManFileName);
  45     }
  46   } else {
  47     Buffer = AllocateZeroPool(StrSize(ManFileName) + 4*sizeof(CHAR16));
  48     if (Buffer != NULL) {
  49       StrCpy(Buffer, ManFileName);
  50       StrCat(Buffer, L".man");
  51     }
  52   }
  53   return (Buffer);
  54 }
  55
  56 /**
  57   Search the path environment variable for possible locations and test for
  58   which one contains a man file with the name specified.  If a valid file is found
  59   stop searching and return the (opened) SHELL_FILE_HANDLE for that file.
  60
  61   @param[in] FileName           Name of the file to find and open.
  62   @param[out] Handle            Pointer to the handle of the found file.  The
  63                                 value of this is undefined for return values
  64                                 except EFI_SUCCESS.
  65
  66   @retval EFI_SUCCESS           The file was found.  Handle is a valid SHELL_FILE_HANDLE
  67   @retval EFI_INVALID_PARAMETER A parameter had an invalid value.
  68   @retval EFI_NOT_FOUND         The file was not found.
  69 **/
  70 EFI_STATUS
  71 EFIAPI
  72 SearchPathForFile(
  73   IN CONST CHAR16             *FileName,
  74   OUT SHELL_FILE_HANDLE       *Handle
  75   )
  76 {
  77   CHAR16          *FullFileName;
  78   EFI_STATUS      Status;
  79
  80   if ( FileName     == NULL
  81     || Handle       == NULL
  82     || StrLen(FileName) == 0
  83    ){
  84     return (EFI_INVALID_PARAMETER);
  85   }
  86
  87   FullFileName = ShellFindFilePath(FileName);
  88   if (FullFileName == NULL) {
  89     return (EFI_NOT_FOUND);
  90   }
  91
  92   //
  93   // now open that file
  94   //
  95   Status = EfiShellOpenFileByName(FullFileName, Handle, EFI_FILE_MODE_READ);
  96   FreePool(FullFileName);
  97
  98   return (Status);
  99 }
 100
 101 /**
 102   parses through Buffer (which is MAN file formatted) and returns the
 103   detailed help for any sub section specified in the comma seperated list of
 104   sections provided.  If the end of the file or a .TH section is found then
 105   return.
 106
 107   Upon a sucessful return the caller is responsible to free the memory in *HelpText
 108
 109   @param[in] Buffer             Buffer to read from
 110   @param[in] Sections           name of command's sub sections to find
 111   @param[in] HelpText           pointer to pointer to string where text goes.
 112   @param[in] HelpSize           pointer to size of allocated HelpText (may be updated)
 113
 114   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 115   @retval EFI_SUCCESS           the section was found and its description sotred in
 116                                 an alloceted buffer.
 117 **/
 118 EFI_STATUS
 119 EFIAPI
 120 ManBufferFindSections(
 121   IN CONST CHAR16 *Buffer,
 122   IN CONST CHAR16 *Sections,
 123   IN CHAR16       **HelpText,
 124   IN UINTN        *HelpSize
 125   )
 126 {
 127   EFI_STATUS          Status;
 128   CONST CHAR16        *CurrentLocation;
 129   BOOLEAN             CurrentlyReading;
 130   CHAR16              *SectionName;
 131   UINTN               SectionLen;
 132   BOOLEAN             Found;
 133   CHAR16              *TempString;
 134   CHAR16              *TempString2;
 135
 136   if ( Buffer     == NULL
 137     || HelpText   == NULL
 138     || HelpSize   == NULL
 139    ){
 140     return (EFI_INVALID_PARAMETER);
 141   }
 142
 143   Status            = EFI_SUCCESS;
 144   CurrentlyReading  = FALSE;
 145   Found             = FALSE;
 146
 147   for (CurrentLocation = Buffer,TempString = NULL
 148     ;  CurrentLocation != NULL && *CurrentLocation != CHAR_NULL
 149     ;  CurrentLocation=StrStr(CurrentLocation, L"\r\n"),TempString = NULL
 150    ){
 151     while(CurrentLocation[0] == L'\r' || CurrentLocation[0] == L'\n') {
 152       CurrentLocation++;
 153     }
 154     if (CurrentLocation[0] == L'#') {
 155       //
 156       // Skip comment lines
 157       //
 158       continue;
 159     }
 160     if (StrnCmp(CurrentLocation, L".TH", 3) == 0) {
 161       //
 162       // we hit the end of this commands section so stop.
 163       //
 164       break;
 165     }
 166     if (StrnCmp(CurrentLocation, L".SH ", 4) == 0) {
 167       if (Sections == NULL) {
 168         CurrentlyReading = TRUE;
 169         continue;
 170       } else if (CurrentlyReading) {
 171         CurrentlyReading = FALSE;
 172       }
 173       CurrentLocation += 4;
 174       //
 175       // is this a section we want to read in?
 176       //
 177       if (StrLen(CurrentLocation)!=0) {
 178         TempString2 = StrStr(CurrentLocation, L" ");
 179         TempString2 = MIN(TempString2, StrStr(CurrentLocation, L"\r"));
 180         TempString2 = MIN(TempString2, StrStr(CurrentLocation, L"\n"));
 181         ASSERT(TempString == NULL);
 182         TempString = StrnCatGrow(&TempString, NULL, CurrentLocation, TempString2==NULL?0:TempString2 - CurrentLocation);
 183         SectionName = TempString;
 184         SectionLen = StrLen(SectionName);
 185         SectionName = StrStr(Sections, SectionName);
 186         if (SectionName == NULL) {
 187           continue;
 188         }
 189         if (*(SectionName + SectionLen) == CHAR_NULL || *(SectionName + SectionLen) == L',') {
 190           CurrentlyReading = TRUE;
 191         }
 192       }
 193     } else if (CurrentlyReading) {
 194       Found = TRUE;
 195       if (StrLen(CurrentLocation)!=0) {
 196         TempString2 = StrStr(CurrentLocation, L"\r");
 197         TempString2 = MIN(TempString2, StrStr(CurrentLocation, L"\n"));
 198         ASSERT(TempString == NULL);
 199         TempString = StrnCatGrow(&TempString, NULL, CurrentLocation, TempString2==NULL?0:TempString2 - CurrentLocation);
 200         //
 201         // copy and save the current line.
 202         //
 203         ASSERT((*HelpText == NULL && *HelpSize == 0) || (*HelpText != NULL));
 204         StrnCatGrow (HelpText, HelpSize, TempString, 0);
 205         StrnCatGrow (HelpText, HelpSize, L"\r\n", 0);
 206       }
 207     }
 208     SHELL_FREE_NON_NULL(TempString);
 209   }
 210   if (!Found && !EFI_ERROR(Status)) {
 211     return (EFI_NOT_FOUND);
 212   }
 213   return (Status);
 214 }
 215
 216 /**
 217   parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
 218   detailed help for any sub section specified in the comma seperated list of
 219   sections provided.  If the end of the file or a .TH section is found then
 220   return.
 221
 222   Upon a sucessful return the caller is responsible to free the memory in *HelpText
 223
 224   @param[in] Handle             FileHandle to read from
 225   @param[in] Sections           name of command's sub sections to find
 226   @param[out] HelpText          pointer to pointer to string where text goes.
 227   @param[out] HelpSize          pointer to size of allocated HelpText (may be updated)
 228   @param[in] Ascii              TRUE if the file is ASCII, FALSE otherwise.
 229
 230   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 231   @retval EFI_SUCCESS           the section was found and its description sotred in
 232                                 an alloceted buffer.
 233 **/
 234 EFI_STATUS
 235 EFIAPI
 236 ManFileFindSections(
 237   IN SHELL_FILE_HANDLE  Handle,
 238   IN CONST CHAR16       *Sections,
 239   OUT CHAR16            **HelpText,
 240   OUT UINTN             *HelpSize,
 241   IN BOOLEAN            Ascii
 242   )
 243 {
 244   EFI_STATUS          Status;
 245   CHAR16              *ReadLine;
 246   UINTN               Size;
 247   BOOLEAN             CurrentlyReading;
 248   CHAR16              *SectionName;
 249   UINTN               SectionLen;
 250   BOOLEAN             Found;
 251
 252   if ( Handle     == NULL
 253     || HelpText   == NULL
 254     || HelpSize   == NULL
 255    ){
 256     return (EFI_INVALID_PARAMETER);
 257   }
 258
 259   Status            = EFI_SUCCESS;
 260   CurrentlyReading  = FALSE;
 261   Size              = 1024;
 262   Found             = FALSE;
 263
 264   ReadLine          = AllocateZeroPool(Size);
 265   if (ReadLine == NULL) {
 266     return (EFI_OUT_OF_RESOURCES);
 267   }
 268
 269   for (;!ShellFileHandleEof(Handle);Size = 1024) {
 270     Status = ShellFileHandleReadLine(Handle, ReadLine, &Size, TRUE, &Ascii);
 271     if (ReadLine[0] == L'#') {
 272       //
 273       // Skip comment lines
 274       //
 275       continue;
 276     }
 277     //
 278     // ignore too small of buffer...
 279     //
 280     if (Status == EFI_BUFFER_TOO_SMALL) {
 281       Status = EFI_SUCCESS;
 282     }
 283     if (EFI_ERROR(Status)) {
 284       break;
 285     } else if (StrnCmp(ReadLine, L".TH", 3) == 0) {
 286       //
 287       // we hit the end of this commands section so stop.
 288       //
 289       break;
 290     } else if (StrnCmp(ReadLine, L".SH", 3) == 0) {
 291       if (Sections == NULL) {
 292         CurrentlyReading = TRUE;
 293         continue;
 294       }
 295       //
 296       // we found a section
 297       //
 298       if (CurrentlyReading) {
 299         CurrentlyReading = FALSE;
 300       }
 301       //
 302       // is this a section we want to read in?
 303       //
 304       for ( SectionName = ReadLine + 3
 305           ; *SectionName == L' '
 306           ; SectionName++);
 307       SectionLen = StrLen(SectionName);
 308       SectionName = StrStr(Sections, SectionName);
 309       if (SectionName == NULL) {
 310         continue;
 311       }
 312       if (*(SectionName + SectionLen) == CHAR_NULL || *(SectionName + SectionLen) == L',') {
 313         CurrentlyReading = TRUE;
 314       }
 315     } else if (CurrentlyReading) {
 316       Found = TRUE;
 317       //
 318       // copy and save the current line.
 319       //
 320       ASSERT((*HelpText == NULL && *HelpSize == 0) || (*HelpText != NULL));
 321       StrnCatGrow (HelpText, HelpSize, ReadLine, 0);
 322       StrnCatGrow (HelpText, HelpSize, L"\r\n", 0);
 323     }
 324   }
 325   FreePool(ReadLine);
 326   if (!Found && !EFI_ERROR(Status)) {
 327     return (EFI_NOT_FOUND);
 328   }
 329   return (Status);
 330 }
 331
 332 /**
 333   parses through the MAN file formatted Buffer and returns the
 334   "Brief Description" for the .TH section as specified by Command.  If the
 335   command section is not found return EFI_NOT_FOUND.
 336
 337   Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
 338
 339   @param[in] Handle             Buffer to read from
 340   @param[in] Command            name of command's section to find
 341   @param[in] BriefDesc          pointer to pointer to string where description goes.
 342   @param[in] BriefSize          pointer to size of allocated BriefDesc
 343
 344   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 345   @retval EFI_SUCCESS           the section was found and its description sotred in
 346                                 an alloceted buffer.
 347 **/
 348 EFI_STATUS
 349 EFIAPI
 350 ManBufferFindTitleSection(
 351   IN CHAR16         **Buffer,
 352   IN CONST CHAR16   *Command,
 353   IN CHAR16         **BriefDesc,
 354   IN UINTN          *BriefSize
 355   )
 356 {
 357   EFI_STATUS    Status;
 358   CHAR16        *TitleString;
 359   CHAR16        *TitleEnd;
 360   CHAR16        *CurrentLocation;
 361
 362   if ( Buffer     == NULL
 363     || Command    == NULL
 364     || (BriefDesc != NULL && BriefSize == NULL)
 365    ){
 366     return (EFI_INVALID_PARAMETER);
 367   }
 368
 369   Status    = EFI_SUCCESS;
 370
 371   TitleString = AllocateZeroPool((7*sizeof(CHAR16)) + StrSize(Command));
 372   if (TitleString == NULL) {
 373     return (EFI_OUT_OF_RESOURCES);
 374   }
 375   StrCpy(TitleString, L".TH ");
 376   StrCat(TitleString, Command);
 377   StrCat(TitleString, L" 0 ");
 378
 379   CurrentLocation = StrStr(*Buffer, TitleString);
 380   if (CurrentLocation == NULL){
 381     Status = EFI_NOT_FOUND;
 382   } else {
 383     //
 384     // we found it so copy out the rest of the line into BriefDesc
 385     // After skipping any spaces or zeroes
 386     //
 387     for (CurrentLocation += StrLen(TitleString)
 388       ;  *CurrentLocation == L' ' || *CurrentLocation == L'0' || *CurrentLocation == L'1' || *CurrentLocation == L'\"'
 389       ;  CurrentLocation++);
 390
 391     TitleEnd = StrStr(CurrentLocation, L"\"");
 392     if (TitleEnd == NULL) {
 393       Status = EFI_DEVICE_ERROR;
 394     } else {
 395       if (BriefDesc != NULL) {
 396         *BriefSize = StrSize(TitleEnd);
 397         *BriefDesc = AllocateZeroPool(*BriefSize);
 398         if (*BriefDesc == NULL) {
 399           Status = EFI_OUT_OF_RESOURCES;
 400         } else {
 401           StrnCpy(*BriefDesc, CurrentLocation, TitleEnd-CurrentLocation);
 402         }
 403       }
 404
 405       for (CurrentLocation = TitleEnd
 406         ;  *CurrentLocation != L'\n'
 407         ;  CurrentLocation++);
 408       for (
 409         ;  *CurrentLocation == L' ' || *CurrentLocation == L'\n' || *CurrentLocation == L'\r'
 410         ;  CurrentLocation++);
 411       *Buffer = CurrentLocation;
 412     }
 413   }
 414
 415   FreePool(TitleString);
 416   return (Status);
 417 }
 418
 419 /**
 420   parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
 421   "Brief Description" for the .TH section as specified by Command.  if the
 422   command section is not found return EFI_NOT_FOUND.
 423
 424   Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
 425
 426   @param[in] Handle             FileHandle to read from
 427   @param[in] Command            name of command's section to find
 428   @param[out] BriefDesc         pointer to pointer to string where description goes.
 429   @param[out] BriefSize         pointer to size of allocated BriefDesc
 430   @param[in,out] Ascii          TRUE if the file is ASCII, FALSE otherwise, will be
 431                                 set if the file handle is at the 0 position.
 432
 433   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 434   @retval EFI_SUCCESS           the section was found and its description sotred in
 435                                 an alloceted buffer.
 436 **/
 437 EFI_STATUS
 438 EFIAPI
 439 ManFileFindTitleSection(
 440   IN SHELL_FILE_HANDLE  Handle,
 441   IN CONST CHAR16       *Command,
 442   OUT CHAR16            **BriefDesc OPTIONAL,
 443   OUT UINTN             *BriefSize OPTIONAL,
 444   IN OUT BOOLEAN        *Ascii
 445   )
 446 {
 447   EFI_STATUS  Status;
 448   CHAR16      *TitleString;
 449   CHAR16      *ReadLine;
 450   UINTN       Size;
 451   CHAR16      *TitleEnd;
 452   UINTN       TitleLen;
 453   BOOLEAN     Found;
 454
 455   if ( Handle     == NULL
 456     || Command    == NULL
 457     || (BriefDesc != NULL && BriefSize == NULL)
 458    ){
 459     return (EFI_INVALID_PARAMETER);
 460   }
 461
 462   Status    = EFI_SUCCESS;
 463   Size      = 1024;
 464   Found     = FALSE;
 465
 466   ReadLine  = AllocateZeroPool(Size);
 467   if (ReadLine == NULL) {
 468     return (EFI_OUT_OF_RESOURCES);
 469   }
 470
 471   TitleString = AllocateZeroPool((4*sizeof(CHAR16)) + StrSize(Command));
 472   if (TitleString == NULL) {
 473     FreePool(ReadLine);
 474     return (EFI_OUT_OF_RESOURCES);
 475   }
 476   StrCpy(TitleString, L".TH ");
 477   StrCat(TitleString, Command);
 478   TitleLen = StrLen(TitleString);
 479   for (;!ShellFileHandleEof(Handle);Size = 1024) {
 480    Status = ShellFileHandleReadLine(Handle, ReadLine, &Size, TRUE, Ascii);
 481     if (ReadLine[0] == L'#') {
 482       //
 483       // Skip comment lines
 484       //
 485       continue;
 486     }
 487     //
 488     // ignore too small of buffer...
 489     //
 490     if (Status == EFI_BUFFER_TOO_SMALL) {
 491       Status = EFI_SUCCESS;
 492     }
 493     if (EFI_ERROR(Status)) {
 494       break;
 495     }
 496     if (StrnCmp(ReadLine, TitleString, TitleLen) == 0) {
 497       Found = TRUE;
 498       //
 499       // we found it so copy out the rest of the line into BriefDesc
 500       // After skipping any spaces or zeroes
 501       //
 502       for ( TitleEnd = ReadLine+TitleLen
 503           ; *TitleEnd == L' ' || *TitleEnd == L'0' || *TitleEnd == L'1'
 504           ; TitleEnd++);
 505       if (BriefDesc != NULL) {
 506         *BriefSize = StrSize(TitleEnd);
 507         *BriefDesc = AllocateZeroPool(*BriefSize);
 508         if (*BriefDesc == NULL) {
 509           Status = EFI_OUT_OF_RESOURCES;
 510           break;
 511         }
 512         StrCpy(*BriefDesc, TitleEnd);
 513       }
 514       break;
 515     }
 516   }
 517   FreePool(ReadLine);
 518   FreePool(TitleString);
 519   if (!Found && !EFI_ERROR(Status)) {
 520     return (EFI_NOT_FOUND);
 521   }
 522   return (Status);
 523 }
 524
 525 /**
 526   This function returns the help information for the specified command. The help text
 527   will be parsed from a UEFI Shell manual page. (see UEFI Shell 2.0 Appendix B)
 528
 529   If Sections is specified, then each section name listed will be compared in a casesensitive
 530   manner, to the section names described in Appendix B. If the section exists,
 531   it will be appended to the returned help text. If the section does not exist, no
 532   information will be returned. If Sections is NULL, then all help text information
 533   available will be returned.
 534
 535   if BriefDesc is NULL, then the breif description will not be savedd seperatly,
 536   but placed first in the main HelpText.
 537
 538   @param[in] ManFileName        Points to the NULL-terminated UEFI Shell MAN file name.
 539   @param[in] Command            Points to the NULL-terminated UEFI Shell command name.
 540   @param[in] Sections           Points to the NULL-terminated comma-delimited
 541                                 section names to return. If NULL, then all
 542                                 sections will be returned.
 543   @param[out] BriefDesc         On return, points to a callee-allocated buffer
 544                                 containing brief description text.
 545   @param[out] HelpText          On return, points to a callee-allocated buffer
 546                                 containing all specified help text.
 547
 548   @retval EFI_SUCCESS           The help text was returned.
 549   @retval EFI_OUT_OF_RESOURCES  The necessary buffer could not be allocated to hold the
 550                                 returned help text.
 551   @retval EFI_INVALID_PARAMETER HelpText is NULL
 552   @retval EFI_NOT_FOUND         There is no help text available for Command.
 553 **/
 554 EFI_STATUS
 555 EFIAPI
 556 ProcessManFile(
 557   IN CONST CHAR16 *ManFileName,
 558   IN CONST CHAR16 *Command,
 559   IN CONST CHAR16 *Sections OPTIONAL,
 560   OUT CHAR16      **BriefDesc OPTIONAL,
 561   OUT CHAR16      **HelpText
 562   )
 563 {
 564   CHAR16            *TempString;
 565   SHELL_FILE_HANDLE FileHandle;
 566   EFI_STATUS        Status;
 567   UINTN             HelpSize;
 568   UINTN             BriefSize;
 569   BOOLEAN           Ascii;
 570   CHAR16            *TempString2;
 571   EFI_DEVICE_PATH_PROTOCOL  *FileDevPath;
 572   EFI_DEVICE_PATH_PROTOCOL  *DevPath;
 573
 574   if ( ManFileName == NULL
 575     || Command     == NULL
 576     || HelpText    == NULL
 577    ){
 578     return (EFI_INVALID_PARAMETER);
 579   }
 580
 581   HelpSize    = 0;
 582   BriefSize   = 0;
 583   TempString  = NULL;
 584   //
 585   // See if it's in HII first
 586   //
 587   TempString = ShellCommandGetCommandHelp(Command);
 588   if (TempString != NULL) {
 589     TempString2 = TempString;
 590     Status = ManBufferFindTitleSection(&TempString2, Command, BriefDesc, &BriefSize);
 591     if (!EFI_ERROR(Status) && HelpText != NULL){
 592       Status = ManBufferFindSections(TempString2, Sections, HelpText, &HelpSize);
 593     }
 594   } else {
 595     FileHandle    = NULL;
 596     TempString  = GetManFileName(ManFileName);
 597
 598     Status = SearchPathForFile(TempString, &FileHandle);
 599     if (EFI_ERROR(Status)) {
 600       FileDevPath = FileDevicePath(NULL, TempString);
 601       DevPath = AppendDevicePath (ShellInfoObject.ImageDevPath, FileDevPath);
 602       Status = InternalOpenFileDevicePath(DevPath, &FileHandle, EFI_FILE_MODE_READ, 0);
 603       FreePool(FileDevPath);
 604       FreePool(DevPath);
 605     }
 606
 607     if (!EFI_ERROR(Status)) {
 608       HelpSize  = 0;
 609       BriefSize = 0;
 610       Status = ManFileFindTitleSection(FileHandle, Command, BriefDesc, &BriefSize, &Ascii);
 611       if (!EFI_ERROR(Status) && HelpText != NULL){
 612         Status = ManFileFindSections(FileHandle, Sections, HelpText, &HelpSize, Ascii);
 613       }
 614       ShellInfoObject.NewEfiShellProtocol->CloseFile(FileHandle);
 615     } else {
 616       *HelpText = NULL;
 617     }
 618   }
 619   if (TempString != NULL) {
 620     FreePool(TempString);
 621   }
 622
 623   return (Status);
 624 }